Compiling OpenFDL

Table of Contents

Introduction

Alright, first off, good job on downloading the source code. The following tutorial is designed for the Windows® operating system, depending on your system configuration, some steps may become neccesary which are not documented here but may be found in other software documentation.
Now, there are primarily two ways to compile the program. The first is by using nothing but the command line (the hard way), and the second is by using a nice IDE (the easy way). For the purposes of this tutorial, we will be using Eclipse which is available, for free, at the Eclipse Project's website, and in my opinion is pretty nice.

Notes on the source code

Before modifying source code, you might want a quick summary on what each file contains and does. Therefore I recommend you read the javadocs located in the doc folder prior to starting any modifications.

Now if you read the javadocs you will notice that only two files are documented. This is because those are the only files that you really need to tinker with, in java. This is a really simple program thanks to the creators of ANTLR. All other files are created by ANTLR so for those, you should modify the grammer file (the openfdl.g file located in the antlr folder).

Requirements

Well for this, we still need Java, but not just any version of Java. What we need is the JDK version, which is not what most people have (they just have the runtime, the JRE). So if you don't have it, you should get it from Sun Microsystems. At the time of writing, the latest version was 1.5.0_03. Also, so you can use the java tools from any directory, I added the path to the tools to my PATH variable. The examples will reflect this.

The first thing we need to do is to read the *.fdl files and check if everything is within the language specifications. This means interpreting grammer/syntax/language stuff, so if you haven't done so already, go and download the antlr-2.7.5.jar file. This will let us know what we are doing.
Now, we can't use java tools to compile a *.g file that it doesn't understand now can we. For this part we will be using Apache Ant. If you are using the command line you will need this, otherwise, Eclipse comes with it. You can download Apache Ant here.

The Command Line

Depending on which file you modified you can skip certain parts..

Compiling the ANTLR grammer file (*.g)

If you modified the openfdl.g file read this section, otherwise skip to the next paragraph.
This section is simple, once you have installed Apache Ant, open a command prompt and navigate to the directory where the openfdl.g and build.xml files are located. Then simply type "ant" (no quotes) and it should then say "Build Successful" and several *.java files should have been created in that directory.

Compiling the Java source code

Navigate to the directory containing the package to the main entry point of the program in a command window and then enter a command similar to:
javac -classpath ".";c:\antlrdir\antlr-2.7.5.jar org\openfdl\core\*.java
This should create the class files for all the source code.

Packaging it all up

To create the final JAR file of the new program, you will first have to make a manifest file similar to the one included with this tutorial, or if you want the antlr-2.7.5.jar file to be located in the same folder as your JAR then don't do anything. Then enter something like this into your command line prompt:
jar cmf manifest.mf openfdl.jar src\org\openfdl\core src\org\openfdl\text

Using Eclipse

First start up Eclipse, of course. Then you can either create an empty project and import the individual files, or use the import "Existing Projects into Workspace" option as shown below.



This is why I included the .PROJECT file. After this, you have to add the JAR file to the build path, so right-click antlr-2.7.5.jar and select "Add to Build Path."



Now, if you want to compile the grammer file, either right-click the build.xml file and run as an "Ant Build" (as seen below)



to get 

or download the ANTLR plugin for Eclipse. To do this, go to "Software Updates>Find and Install.." and then "Search for new features to install." Click "New Remote Site" with http://antlreclipse.sourceforge.net/updates/ as the URL with whatever name you please to download. Now, the grammer file has an icon and highlighting and more importantly, a "Compile ANTLR Grammer" option under the right-click menu.



Copy the generated files, to your package and build your project. To create the JAR, just use the Export option and follow the directions, with the supplied manifest file.