CS2 JWhite Paper
CS2 JWhite Paper
CS2 JWhite Paper
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:
● The directory where the XML .Net Framework translation files are held. e.g
NetFramework.
● The directory that is the root of the C# application to be translated.
● The directory where the java classes will be written (e.g. JavaProject/src).
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 nettemplatesdir=.\NetFramework\ outjavadir=<java project source> appdir=<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 nettemplatesdir=.\NetFramework\
outjavadir=<java project source> appdir=<cs application root> csdir=<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 subdirectory
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 showXXXX 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 exXXX options allow you to exclude files and whole subtrees (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 semicolons.
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:
● files with extension .none: If file nothankyou.none exists in the cheats area then
the translator won't produce a class file for nothankyou.
● files with extension .java: If file manualisbetter.java exists in the cheats area then
the translator will copy manualisbetter.java instead of its own translation.
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
v increase verbosity
debug 1 set debug level for diagnostic messages
(0..10)
debugtemplateextraction true if false turn off debug for template extraction
phase
D set a C# preprocessor token (can be
repeated)
cheatdir directories containing cheat files
nettemplatesdir directories/files containing translation
templates
exnettemplatesdir directories/files to exclude from
nettemplatesdir
exappdir directories/files to exclude from appdir
csdir directories/files containing C# code to
translate
excsdir directories/files to exclude from csdir
alttranslations list of translation template variants that
should have priority
config INI file specifying configuration options (see
Appendix A).
.NET Framework translations
The provided .NET framework translations are in the NetFramework\System subfolder.
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 dumpxmls) 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)
define set a C# preprocessor token (multiple
tokens can be separated by ‘|’
character)
cheatdir directories containing cheat files
nettemplatesdir directories/files containing translation
templates
exnettemplatesdir directories/files to exclude from
nettemplatesdir
exappdir directories/files to exclude from
appdir
csdir directories/files containing C# code to
translate
excsdir directories/files to exclude from csdir
alttranslations list of translation template variants that
have priority over default
Section [Experimental]