A guide to Sharpen — a great tool for converting Java to C#

Following on from my tips on porting Java to C#, I’ve put together a step by step guide to getting Sharpen working.
This is primarily because the Sharpen documentation is minimal, confusing and difficult to follow if you are not a regular Eclipse and Ant user. The few tutorials I could find were also confusing.

Sharpen does an excellent job of converting Java to C# while also accomodating common syntax and library differences between the languages.
This can be a massive time saver when you are faced with a Java library that contains 1000s of lines of code.

Before we dive into the details, let me make it clear that I see Sharpen as a way to kickstart the porting process, not as a one stop porting solution. You should expect to get your hands dirty fixing up the C# that Sharpen produces.

OK, with my disclaimers out the way, lets get into the guide.
My focus is on getting started with the GUI tools, though Sharpen can also be setup as a command line facility.

Prerequisites

• Eclipse. All you need is the Java Developers version. Download & install.
  Sharpen is an Eclipse plug-in so naturally you gonna need Eclipse here.
• Sharpen.
  Don’t use the official Sharpen source code since it hasn’t been maintained. Download Lluis Sanchez’s already compiled sharpen.core jar found in the ngit project on github. That’s all your need for Sharpen.Lluis’s version has several bugfixes and is better maintained since the MonoDevelop team use Sharpen to keep their nGit port of JGit in sync.
• Sharpen config files.The actual Sharpen conversion process runs via an Ant build script and uses properties files to configure the environment. Understanding how these work from the reference documentation was a pain.To make things simpler, I consolidated the configs a bit, merged in configs from Lluis’s nGit project and stripped out unused bits.
  Download my config files zip and extract for later use below.
• Sharpen C# utility classes.
  Sharpen preserves many Java method signatures with a set of special utility classes. This avoids issues where C# does not match Java for common methods such as Substring(). Lluis has extended the Sharpen base utility set with more classes, so naturally we want to sponge off that too.
• Download all the classes found in the Sharpen folder of the NGit project.

<aside>Eclipse for Visual Studio people

If you come from an exclusively Visual Studio world then Eclipse can be a bit of a weird experience.
I’m not going to explain Eclipse here, but to help you get your head around it:

• Eclipse Workspace = Visual Studio solution
• Eclipse Project = VS project
• Eclipse Build Path = VS project references
• Java JARs = .Net DLLs
• Eclipse Perspectives = Different UI configuration — kinda like how you can set up VS as being optimised for C# development or VB development or Web development

Open the Java library in Eclipse

Check if the Java library came with an existing Eclipse .project file — it should be in the root folder of the source.
If you have a .project file then do the following:

1. Start up Eclipse
2. If Eclipse asks you for a workspace location, choose the default.
3. If you have a “Welcome” screen, close it to reveal the Java perspective.
4. Go to File -> Import.
5. Choose the General -> Existing Projects into Workspace option. Hit Next.
6. Choose Select root directory and browse to the root of the Java library source.
7. Eclipse should pick up at least one project in the Projects listing panel
8. Make sure all projects listed are ticked and click Finish.

If there isn’t a .project file then you need to create a new Eclipse project for the source:

1. Go to File -> New -> Project
2. Choose Java -> Java Project and hit Next
3. Enter a project name
4. Uncheck the “Use default location” option and in the Location field, browse to the root folder of the Java library. Hit Next
5. In the Java Settings screen, you should see the various library folders picked up in the Source tab.
6. Check your Java library folder for any external jar files. These are normally in a “lib” folder in the root directory of the library. If you find any, then you need to make sure these are listed in the Libraries tab. If not, add these via the Libraries tab, using the Add External JARs option.
7. Click Finish to create the project

Eclipse will automatically compile the projects, much like VS does and will report any errors. If you get errors then you need to fix them. Google is your friend :)

Make sure your Java library compiles. It must compile for Sharpen to work with it.

Add Sharpen as an Eclipse plugin
There’s some stuff on the Sharpen documentation about how to build the Sharpen plugin from the source code, however thanks to the sharpen jar file we downloaded from Lluis’s github, we can skip that part.

Simply copy the sharpen jar file to the “plugins” folder found in the root of your Eclipse installation. Sharpen will now be picked up by Eclipse as a plug-in :)

Add the Sharpen config and build files to your Java project
Grab my config files from where ever you extracted them and add them into the root of your Java library project. You do this by copying the files into the project folder found in your Eclipse workspace directory.

They must be in the root of your Java project!

Then edit the files as follows:

sharpen.properties

1. Set dir.workspace to be the path to your Eclipse workspace root.
   Use Unix slashes (/) for directories.
2. Set file.jvm.jdk1.5 to point at the java.exe found in your JDK installation.
   If you don’t have a JDK installed, get it and install now.
3. Set eclipse.home to be the path to your Eclipse installation root.
4. Ensure eclipse.startup.jar is set to the available eclipse.equinox.launcher jar found in the plugins subfolder of your Eclipse root.
   This can be a big gotcha.
   It took me a while to figure out that my version of Eclipse had a newer launcher jar (version 1.2). So make double sure that this setting matches the file name of your launcher jar exactly.

run-sharpen.xml
This is the Ant build definition. Look for my CHECK THIS SETTING comments.

1. Ensure the dir attribute of the <target><copy><fileset> element is set to the subfolder of your Java library containing the Java source files to convert.
   This is usually the “src” folder, but if there are unit tests included in say a “test” folder then you will need to run Sharpen once with dir = src and once with dir = test to convert all Java code.
2. Ensure that all external JAR files your Java project references are listed as <arg> value and path pairs. See the examples I’ve included in the file (don’t forget to remove these too!). To get a list of your project’s external JAR references, right click the project in Package Explorer, go to Build Path -> Configure Build Path and check the Libraries tab.
3. Sharpen will build your Java project before conversion — this is why it needs to know about all the external reference JARs.

sharpen-all-options
This file allows you to customise how Sharpen converts the Java code. The Sharpen documentation outlines these options pretty well. The options file I included is based on Lluis’s one, but edit as you wish. One change you should make is to change your Java library’s base namespace to a C# style one in all the generated cs files.

To do this, edit the sample line “-namespaceMapping org.mylibrary NMyLibrary” as needed.

header.txt
The text in this file will be automatically added to the top of every converted CS file. Edit this as needed. Preferably remove my idiot message.
Make sure that you honour the license statements and conditions of the Java library — porting it to .Net does not exempt you from licenses!

Whew. OK so tons of config and setup stuff done.

You are now ready to convert your Java code!

Run Sharpen

1. Right click on the run-sharpen.xml file in the Package Explorer and go to Run As -> Ant Build.
2. You should see a Console pane come up and Ant will start running.
   You want to see a BUILD SUCCESSFUL message at the end.
3. The converted C# files will be output to the sharpen/sharpened.net subfolder of your Java project’s root folder.
   Open Windows Explorer and navigate there to delight in seeing many .cs files :)

Add the Sharpen utility classes to your C# project
So now that you have converted a zillion lines of Java to C# in 20 seconds with Sharpen, you naturally will want to add the converted source to your .Net project.

When you do, expect to see a stack of compilation errors related to missing Sharpen classes.
This is because the Sharpen-generated C# code uses a number of utility classes to bridge the gap between Java and C# method signatures.

This is easy to sort out. Add the Sharpen folder that you downloaded in the Prerequisites section to your project in Visual Studio. Make sure to include all the cs files found in that Sharpen folder.

Now the hard work begins…
At this stage, everything should be sweet as far as the Sharpen part goes.
Just don’t expect the C# code to compile :)

Remember Sharpen converts the code as best as it can, but you still need to put in the elbow grease to get your port completed and compiling.

The good news is you now have a great starting point of generated C# to work with.

Originally published at pauldb-blog.tumblr.com on Wed. December 28, 2011 @ 11:57 pm.