CS2J: The User Guide


CS2J: The User Guide

Overview

Running the translator

Visualizing the translation

Excluding paths

Dumping the translation repository

Guiding the translation process (adding Cheats)

CS2J Parameters

.NET Framework translations

Translation files

Appendix A - Configuration File

Section [General]

Section [Experimental]

Overview

CS2J is a C# application that converts C# types (classes, structs, enums, delegates) to Java types (classes and enums).


The translator first crawls over the whole of the C# application and builds up an internal data structure, called the translation repository, that stores translation metadata for all the application's classes, structs, enums, etc. It then extends this repository from XML files that add translation metadata for .NET Framework system calls and third party libraries used by the application.   Using this translation repository it then takes each class, struct, enum, and so on, from the application and translates it to Java:

  1. Translate the C# source into a C# parse tree.
  2. Translate the C# parse tree into a Java(ish) parse tree.  This converts C# syntax into Java syntax, it doesn't translate method calls or do any translations that depend on types.
  3. Generate types for the nodes in the Java(ish) parse tree and use the translation repository to translate types and method calls into their Java equivalent.
  4. Pretty print the Java parse tree to Java source files (one per top level type in the C# source file).

Running the translator

CS2J is a Windows executable that can be run from the command line. (There is also a GUI launcher which is not yet described in this document, ask for details).

To run the translator there are three required arguments:

There are many, many more options too,  cs2j --help describes the most useful, section CS2J Parameters describes them all.

Assuming you are in the root directory of the unpacked archive then a minimal command line would be:

CS2jTranslator\bin\cs2j.exe -net-templates-dir=.\NetFramework\ -out-java-dir=<java project source> -app-dir=<cs application root>

This will translate all cs files below <cs application root> and place the resultant java files below <java project source>. (The directory structure of the java files will not match the directory structure of the C# files, instead it will match the java namespaces). To translate calls to the .NET libraries the translator will use the translation templates found below NetFramework (note, that argument is the name of a directory).

A slightly more complicated command line would be:

CS2jTranslator\bin\cs2j.exe config=..\configs\appconfig.ini -debug=5 -net-templates-dir=.\NetFramework\ -out-java-dir=<java project source> -app-dir=<cs application root> -cs-dir=<cs tx root>

This will read parameters from the configuration file ..\configs\appconfig.ini. The format of configuration files is specified in Appendix A - Configuration File.  Settings in the configuration file are overridden by the other command line arguments.

 

The command line arguments tell the translator to add all cs files below <cs application root> to the translation repository, and translate the files below <cs tx root> (for example, <cs tx root> could be a component of <cs application root>).

The translator will place the resultant java files below <java project source>. The translator will use the translation templates found below the NetFramework sub-directory to translate calls to the .NET libraries. It will write diagnostics to the terminal, increasing amounts of diagnostics are output as the debug parameter is increased from 0 to 10.

We now briefly discuss some of the other options to the translator.

Visualizing the translation

The -show-XXXX options will show the internal data structure during processing. There are options to display the parse tree at each stage: CSharp, Java Syntax, and Java.

Excluding paths

The -ex-XXX options allow you to exclude files and whole sub-trees (by giving the root of the excluded directory) from consideration.  You can block parts of the XML translation area; parts of the application when generating the translation repository; and part of the source to be translated. For these options you can specify multiple exclusion paths separated by semi-colons.

Dumping the translation repository

The translation database generated from the application can be dumped to a set of XML files with the -dumpxml option.  This produces a directory structure matching the application and XML translation namespaces.  Leaf XML files show the translation for each top level C# type. These translation files are discussed in more detail in the next section.

Guiding the translation process (adding Cheats)

The -cheatdir option points to a directory hierarchy that matches the target java output directory structure.  You can put two types of file here:

You should consider carefully before using the cheats facility.  We do not use it for our main translated product. For code that we can't translate we move it into a separate (untranslated) namespace (e.g. Application.Utils) and write separate versions for .NET and Java.

CS2J Parameters

argument

default

meaning

-version

false

output CS2J version

-help

false

output help message, listing most common options

-v

increase verbosity

-debug

1

set debug level for diagnostic messages (0..10)

-debug-template-extraction

true

if false turn off debug for template extraction phase

-warnings

true

output CS2J warnings

-warnings-resolve-failures

false

output warnings for failure to resolve external references

-show-csharp

false

output representation of C# parse tree

-show-javasyntax

false

output representation of parse tree after C# to Java syntax pass

-show-java

false

output representation of final parse tree before pretty print pass

-D

set a C# preprocessor token (can be repeated)

-dump-xmls

false

dump translation templates (including those for the C# application being processed)

-out-xml-dir

tmpXMLs sub directory

directory to dump translation templates

-out-java-dir

current directory

directory to write java output files

-cheat-dir

directories containing cheat files

-net-templates-dir

directories/files containing translation templates

-ex-net-templates-dir

directories/files to exclude from -net-templates-dir

-app-dir

as -cs-dir

directories/files containing C# application

-ex-app-dir

directories/files to exclude from -app-dir

-cs-dir

directories/files containing C# code to translate

-ex-cs-dir

directories/files to exclude from -cs-dir

-alt-translations

list of translation template variants that should have priority

-keep-parens

true

carry over (redundant) parenthesis from C# source

-timestamp-files

true

add timestamp comment to head ofl Java files

-blanket-throw

true

add “throws Exception” to all methods

-make-javadoc-comments

true

convert C# XML documentation comments to Javadoc comments

-make-java-naming-conventions

true

rename method names to conform to the usual Java conventions (ExecutePool() becomes executePool()). This option implies “LCC” is added to alt-translations.

-experimental-enums-to-numeric-consts

false

convert enums to integer constants

-experimental-unsigned-to-signed

false

convert unsigned C# data types to signed Java data types

-experimental-unsigned-to-bigger-signed

false

convert unsigned C# data types to bigger Java signed types (e.g., ushort to int)

-config

INI file specifying configuration options (see Appendix A).

.NET Framework translations

The provided .NET framework translations are in the NetFramework\System sub-folder.  This is structured in the same way as the .NET framework namespace, i.e., the translation for "System.Collections.ArrayList" is the file System\Collections\ArrayList.xml. (This is just a convention, the location and name of a translation file is irrelevant).


These files are XML, the translator is a bit finicky about their structure and if it sees something it doesn't recognise it often fails silently.  


A useful trick when a translation doesn't seem to be picked up is to ask the translator to dump the translation database (option -dump-xmls) and look at the resultant XML files to see if it recognized the translation template.

Translation files

The format of the translation file deserves another document, unfortunately it isn't written (yet). Look at the provided translations under NetFramework for inspiration and, as always, ask us for help.

Appendix A - Configuration File

Section [General]

key

default

meaning

verbose

0

verbosity level

debug

1

set debug level for diagnostic messages (0..10)

debug-template-extraction

as debug

set a different debug level for template extraction phase

warnings

true

output CS2J warning messages

warnings-resolve-failures

false

output warnings for failure to resolve external references

show-csharp

false

output representation of C# parse tree

show-javasyntax

false

output representation of parse tree after C# to Java syntax pass

show-java

false

output representation of final parse tree before pretty print pass

define

set a C# preprocessor token (multiple tokens can be separated by ‘|’ character)

dump-xmls

false

dump translation templates (including those for the C# application being processed)

out-xml-dir

tmpXMLs sub directory

directory to dump translation templates

out-java-dir

current directory

directory to write java output files

cheat-dir

directories containing cheat files

net-templates-dir

directories/files containing translation templates

ex-net-templates-dir

directories/files to exclude from -net-templates-dir

app-dir

as cs-dir

directories/files containing C# application

ex-app-dir

directories/files to exclude from -app-dir

cs-dir

directories/files containing C# code to translate

ex-cs-dir

directories/files to exclude from -cs-dir

alt-translations

list of translation template variants that have priority over default

keep-parens

true

keep (redundant) parenthesis from C# source

timestamp-files

true

add timestamp comment to head of Java files

blanket-throw

true

add “throws Exception” to all methods

make-javadoc-comments

true

convert C# XML documentation comments to Javadoc comments

make-java-naming-conventions

true

rename method names to conform to the usual Java conventions (ExecutePool() becomes executePool()). This option implies “LCC” is added to alt-translations.


Section [Experimental]

enums-to-numeric-consts

false

convert enums to integer constants

unsigned-to-signed

false

convert unsigned C# data types to signed Java data types

unsigned-to-bigger-signed

false

convert unsigned C# data types to bigger Java signed types (e.g., ushort to int)