Setting Up the Code for Development and Compilation

In this document:

• Supported Platforms
• Software Structure and Compiling Under Alternate Environments
• Step by Step Instructions for Setting Up Development Using Eclipse
• Tools
• Directory Structure
• Project 1: The Core Model Code
  • Installing Eclipse and setting up the C++ project
    • Step 1 [Windows only]: Install MinGW and MSYS
    • Step 2: Install Eclipse
    • Step 3: Install C++ Development Tools for Eclipse
    • Step 4: Create the SORTIE-ND Project in Eclipse
• Project 2: The C++ Test Project
  • Setting up the C++ test project in Eclipse
• Running SORTIE-ND from Linux
• Project 3: The Java GUI project
  • Setting up the Java project in Eclipse
• Project 4: The C++ Interface library
• Project 5: The C++ Interface DLL for Java
• Tips on running Eclipse
• Incorporating changes into the SORTIE-ND software

The Windows environment is considered SORTIE-ND's "native" environment and is fully supported. The core C++ model code is provided with appropriate modifications to run on Linux systems from the command line. The Java GUI should run on any environment with Java installed, but the direct link between it and the core model only operates on Windows. This means the GUI can be used to work with parameter files and output files, but simulations must be launched from the command line on other systems. See Porting to another OS for more information on what you need to know to attempt a build of SORTIE-ND on another system.

The core part of the SORTIE-ND software is the processing engine, written in C++. This can be used by itself from the command line if you have the appropriate parameter files prepared. The other half of the SORTIE-ND software is a Java program that provides a GUI for creating parameter files, launching the processing engine, and viewing output.

I use the Eclipse development environment to write code for both parts, and I give very detailed instructions for setting it up below for those who may be new to this. In case you want to use a different environment or set up makefiles, here is how the code needs to be compiled:

The Core Model C++ Code

• Xerces C++ parsing library 3.1.2 is installed
• GNU Scientific Library 1.16 is installed (other versions will probably work too, they don't seem to change their interfaces too much)
• The SORTIE-ND interface library is compiled as a shared library (see below)

The main function is in the file SORTIE.cpp.

All .cpp files are to be compiled in the root directory, the root/Behaviors directory, and the root/Behaviors/NCI directory.

Define the symbol GENERATING_DLL_APP in the preprocessor.

Includes:

• All source folders
• Header directory for Xerces C++ 3.1.2 library
• Directory for GNU Scientific Library 1.16
• Directory for the SORTIE-ND interface library

Link in the three aforementioned libraries.

The executable is called "coremodel".

The code makes external system calls to gzip and tar. Make sure that these are installed and their paths in your path environment variable.

The SORTIE-ND interface library has no external dependencies. Compile the code as a shared library.

This section will guide you through setting up an environment to work with the code in SORTIE-ND. This is very detailed and assumes very little prior knowledge.

In order to work with the code in SORTIE-ND, you need the following development tools installed:

• A program that can uncompress ZIP or .tar.gz format files. If you don't already have a program you like, I like 7-zip.
• Eclipse, MinGW, and MSYS for building both the C++ core and Java GUI. Instructions for downloading and installing are below.
• Xerces 3.1.2 C++ library is used to parse the XML files (parameter and output files). (Note the version number: 3.1.2!) Instructions for downloading and installing are below.
• GNU Scientific Library 1.16 does the mathematical heavy lifting. Instructions for downloading and installing are below.
• To work directly with parameter and output files (XML) use any text editor. You can find a more elaborate XML editor if you wish to pay for it. For a handy programmer's text editor, try jEdit.

There are five projects described below. Four of the projects (all except the SORTIE-ND GUI) are written in C++. Some of these projects are dependencies for other projects. You probably do not need to work with all of them. I recommend placing at least the C++ projects together in the same root directory which has no spaces in the name.

Get the source code for the core C++ model from this site. Uncompress the code into your code root directory, one that has no spaces in the path name. Three folders should be created in your code root: "Core_Model", "Interface_DLL", and "Interface_DLL_for_Java". (See the example directory structure above.) If you are using the Linux version of the code, "Interface_DLL_for_Java" is ommitted.

"Core_Model" contains:

• Code files (.cpp and .h)
• [Windows] "gzip.exe" and "tar.exe", third-party executables used by SORTIE-ND
• [Windows] "libxerces-c-3-1-1.dll", Xerces library, used for parsing XML files
• [Windows] "libgsl-0.dll" and "libgslcblas-0.dll", files for the GNU scientific library, used for mathematical operations
• [Windows] "libinterface.dll", the library that forms the link between SORTIE-ND and the user (you have the source for these libraries in the "Interface DLL" folder)
• /Behaviors folder: Source code for SORTIE-ND's behaviors.

"Interface_DLL" contains: Source code for a SORTIE-ND library. This library manages the command line interface that is used when you launch the core model directly, without using the user interface. Modify this code at your own risk.

"Interface_DLL_for_Java" contains: Source code for a SORTIE-ND library. This library allows the user interface and the core model to pass messages back and forth. Modify this code at your own risk.

The C++ project creates an executable called "coremodel.exe".

Eclipse is an open-source development environment that can be used to write code in many different languages, including the C++ and Java used by SORTIE-ND. Eclipse provides you with the tools to make code development easier.

Eclipse does not actually compile the code itself, and is not required in order to compile and run SORTIE-ND. It just makes life easier when writing the code. If you are using Windows, you have to download and separately install a compiler set for Eclipse to use. By default, it works with the GCC (GNU Compiler Collection) tools. If you have Linux, you most likely already have all these tools installed.

For Windows, there are several installs for GCC, the two most common of which are MinGW and Cygwin. I have chosen MinGW because I had better luck getting its Windows libraries to work with SORTIE-ND.

If you have little or no programming and/or Windows power user experience: I have given step-by-step instructions for setting this up, but I warn you that this might hurt. Read the instructions before you start. If the terms used make no sense to you, do some reading first (on C++ development, Windows software development, GCC tools, etc). Before you start, you might want to find a guru to help you when you get stuck. Also, you should probably back up your data because you are going to do things that can seriously mess up your system if you get them wrong. (Software development tends to be like that...)

In the directions below, I use a lot of directory examples. In Windows, case doesn't matter in directory names; but in the Linux/UNIX world, case does matter. Since we're working with tools that are ports of Linux/UNIX software, case will matter sometimes. When in doubt, be consistent. If your directory is "C:\MinGW", and I write "c:\mingw" as an example below, use your own directory's case.

If you use Linux, skip to step 2. If you already have Eclipse installed, skip to step 4.

MinGW really consists of two parts, MinGW and MSYS. From the MinGW website (www.mingw.org):

MinGW: A collection of freely available and freely distributable Windows specific header files and import libraries combined with GNU toolsets that allow one to produce native Windows programs that do not rely on any 3rd-party C runtime DLLs.

MSYS: A Minimal SYStem to provide POSIX/Bourne configure scripts the ability to execute and create a Makefile used by make.

You need both of these to use Eclipse and compile SORTIE-ND.

1. Download and install MinGW + MSYS at http://sourceforge.net/projects/mingw/. The current version of SORTIE-ND has been installed with gcc version 4.6.1.
2. IMPORTANT: Install to a directory with no spaces in it, like "c:\MinGW". Use the default if you can, because Eclipse will automatically look for it there.
3. When installing, you get a checklist of components you wish to install. Add the C++ compiler, MSYS, and the MinGW Developer Toolkit.
4. Once you've finished installing, put the path C:\MinGW\bin and C:\MinGW\MSYS\1.0\bin (or your appropriate versions) in your PATH environment variable. This allows you to run the MinGW software from any directory, which is critical for Eclipse.

CHECK: To make sure you've done this correctly so far, open a command line window (to any directory EXCEPT \MinGW\bin) and type "gcc". It should say "gcc: no input files". Then type "g++". It should say "g++: no input files". If it says "[gcc or g++] is not recognized as an internal or external command, operable program or batch file", something's wrong. Check to make sure that both "gcc.exe" and "g++.exe" are in your \MinGW\bin path. If they aren't, reinstall MinGW and make sure you choose to install the correct components (C++ compiler, not C compiler!). If the files are there, double-check the directory you added to your Path environment variable in step 4 above.

Make sure you have a Java Runtime Environment installed. If you don't, you can download it from www.java.com. (Note: if you plan on working with the SORTIE-ND GUI code, skip to that section and just install the proper JDK.) You also need to have the Java directory in your Path environment variable.

There are a bewildering number of download options for Eclipse, with many different versions of each release. In the end, it doesn't really matter which configuration you choose, because you can always add any options you need later. You are going to need Eclipse with the C++ development tools installed in order to work with the core model code. If you want to work with the GUI code, you will need the Java development tools as well.

Windows:

1. Download your preferred Eclipse version from http://www.eclipse.org/.
2. Unzip the file into the directory where you want Eclipse (such as c:\eclipse). Again, no spaces in the filename. This is all that is required to install Eclipse.
3. Launch Eclipse by double-clicking the "eclipse.exe" in your Eclipse directory. When you launch Eclipse for the first time, it will ask you in what directory you want to keep your workspace. Use a directory with no spaces in the filename, and not a directory where you'll put any code.

Linux users, if you use a distribution with a user interface rather than a command line, you probably have Eclipse as an available option in your software repository. Install according to your distribution.

Eclipse needs to have a plugin installed in order to work with C++ (the C++ Development Tools, or CDT). If you downloaded an Eclipse release for C\C++ developers, you've already got it. If you don't, you can do this from within Eclipse. Read the directions for your version of Eclipse to install the CDT.

You might want to pause here and find your way around Eclipse. They have tutorials in the help.

Compile and run a simple "Hello World" program. This way, if you have trouble setting up SORTIE-ND later, you'll know that you have your compilers and development software set up correctly.

Libraries. There are two external libraries that SORTIE-ND requires: the Xerces C++ XML parsing library, and the GNU Scientific Library (GSL); and one included library to interface between the two parts of SORTIE-ND.

Windows: The DLL files for these libraries are included in the SORTIE-ND download, but you also need a set of header files for these libraries . These can be downloaded from http://xerces.apache.org/xerces-c/download.cgi and http://www.gnu.org/software/gsl/. Make absolutely sure you get the correct versions. You may have to build the GSL library to get the header files.

Linux: You will need to download and build the Xerces and GSL libraries. You may be able to simply install the packages through your distribution, in which case make sure you get the versions right. Make sure to get the "dev" packages in order to get the header files. See below for how to compile the interface library.

Note: If you have a gcc compiler version other than the one noted above (type "gcc -v" at a command prompt to find out), the Xerces libraries may not link in correctly when building SORTIE-ND. In that case, you will need to download and build the correct version of the Xerces library from source with your compiler. It looks extremely scary (to Windows types) but is in fact pretty easy once you carefully read the directions for building. If you do need to build the Xerces library, note that the following applies to gcc 4.6.1: The build instructions tell you to configure with the following command:

./configure LDFLAGS=-no-undefined

But you have to do this instead:

./configure
make libxerces_c_la_LDFLAGS="-release 3.1 -no-undefined"

Now you are ready to set up the SORTIE-ND project for compiling. When I refer to directories here, something like "\Core_Model" refers to that directory in your root code directory. For example, my root code directory is c:\sortie\code. So for me, "\Core_Model" means "c:\sortie\code\Core_Model".

In Eclipse, create a new C++ executable project. (The exact menu options vary by release.) Wizard options:

• Choose whatever name you want for your project. Uncheck the box that says "Use default location" under project contents, and set the directory to the \Core_Model directory.
• Your "Project type" is the appropriate variation on C++ executable, empty project.
• If you have a choice of toolchains, choose "MinGW GCC".

To control processes and see status, you can use the "Progress" tab. It will be at the bottom of the screen with several tabs, marked "Problems", "Console", "Properties", etc. If you don't see it, here's how to make it visible: On the "Window" menu, go to "Show View"->"Other...". Expand the "General" section, and click "Progress". Once you have the "Progress" tab, you can view it to get the status of background processes and cancel them.

Now set the compiler settings. This is most likely under Project->Properties. Choose "C/C++ Build" at the left of the screen, and under that, "Settings".

1. [WINDOWS]: On the right of the screen, choose the "Binary Parsers" tab. Make sure that only PE Windows Parser is checked. (Linux, obviously, skip this step.)
2. [WINDOWS]: Choose the "Tool Settings" tab. Under "GCC C++ Compiler", choose "Preprocessor". Under "Defined Symbols", add GENERATING_DLL_APP. This is to get it working correctly with the Interface library. (Linux, this define is not necessary.)
3. Under "GCC C++ Compiler", choose "Directories". (Linux, if you formally installed the Xerces and GSL development packages, Eclipse should be able to find the header files, assuming they ended up in /usr/include; if not, you may need to add the directories.) Add the following list of directories:
   • \Core_Model
   • \Core_Model\Behaviors
   • \Core_Model\Behaviors\NCI
   • \Interface_DLL
   • [xerces root]\include IF IT EXISTS, otherwise use [xerces root]\src
   • GSL root directory
4. Under "MinGW C++ Linker", choose "Libraries". Under "Libraries (-l)", add (if Windows) "libxerces-c-3-1-2", "libgsl-0", and "libinterface" or (if Linux) "xerces-c", "gsl", "gslcblas", and "interface" (with no quotes). Under "Library search path (-L)", add \Core_Model.
5. Under Compiler Miscellaneous settings, add "-m32" to the "Other flags" line. This compiles the code as 32-bit, to maintain compatibility with 32-bit operating systems.
6. Choose the "Build artifact" tab. Under "Artifact name", put "../coremodel" (without the quotes). This tells Eclipse to create an executable called coremodel.exe and put it in the root code directory.

Now it's time to try building the project. Choose Project->Build Project. A complete build may take several minutes depending on the speed of your computer.

Once the project is built, there should be a file called coremodel.exe in your \Core_Model directory. You can launch it from DOS, or run it from Eclipse (for debugging, for example). To run it from Eclipse, you need to create a run configuration:

1. Choose "Run->Run Configurations..."
2. Click on "C/C++ Local Application", and click "New".
3. Name it whatever you want. For "Project", make sure it says your project name. Under "C\C++ Application", choose \Core_Model\coremodel.exe.
4. Click the "Run" button. SORTIE-ND will launch in the console window at the bottom of the screen.
5. [Windows]: Prepare debugging: On the "Debugger" tab, choose "Cygwin GDB Debugger".
6. To debug, click the debug icon after you have a run configuration set up.

Notes: I had to build the Xerces library myself. None of the binaries I downloaded worked for me, on either Windows or Linux. The libraries I include are the ones I built. If you get errors that appear to come from Xerces, try building the library yourself from source. There are instructions for doing it that come with the download.

If you get a "permission denied" error from the linker, check to see if you are running Microsoft Security Essentials. If so, you need to go to the settings and uncheck "Enable behavior monitoring."

The C++ test project contains test code for the C++ core model. The testing framework used is googletest. The test code is separate from the model code and is not required to compile the model. If you make model changes, though, do make a model test case for them.

Get the source code for the C++ test project model from this site. It should be in a folder called "Core_Model_Tester".

You will need to download googletest in order to get the header files. Download version 1.6 at https://github.com/google/googletest. If you are working with a non-Windows system, or a different compiler version, you will need to build the gtest library.

Note on gtest: I have been unable to get gtest to build on Windows after version 1.6.0. (If you need that version, get in touch.) In MSYS navigate to the "make" directory and just type "make". The samples may not compile but the main library will. Rename it to libgtest-main and off you go.

The C++ test project contains:

• The test code files. There is generally one test .cpp file for each SORTIE-ND .cpp file (although there are exceptions).
• [Windows]: Libraries, the same as for the core model.

This assumes that you have set up the C++ project, and thus installed Eclipse, etc.

1. In Eclipse, create a new C++ executable project. (The exact menu options vary by release.)
2. On the screen that says "C++ Project", choose whatever name you want for your project. Uncheck the box that says "Use default" under project contents, and set the directory to the \Core_Model_Tester directory.
3. If you have a choice of toolchains, choose "MinGW GCC".
4. Click "Finish".

Now link to the SORTIE-ND source. Click "File->New->Folder". Click the "Advanced>>" button. Check "Link to folder in the file system". Browse to the Core_Model directory.

There are some files we don't want to include in the build of the test. For each of the files listed below, right-click it (under the test project), then choose "Exclude from build..." and select all the checkboxes that come up.

• Core_Model\SORTIE.cpp
• Harvest_Interface_Test_Code\Fake_Harvester_1\main.cpp
• Harvest_Interface_Test_Code\Fake_Harvester_2\main.cpp
• Harvest_Interface_Test_Code\Fake_Harvester_3\main.cpp
• Harvest_Interface_Test_Code\Fake_Harvester_4\main.cpp
• Harvest_Interface_Test_Code\Fake_Harvester_5\main.cpp
• Harvest_Interface_Test_Code\Fake_Harvester_6\main.cpp

Now set the compiler settings. This is most likely under Project->Properties. Choose "C/C++ Build" at the left of the screen, and under that, "Settings".

1. [WINDOWS]: On the right of the screen, choose the "Binary Parser" tab. Make sure that only PE Windows Parser is checked. (Linux, obviously, skip this step.)
2. Under "GCC C++ Compiler", choose "Directories". Add the following list of directories:
   • \Core_Model_Tester
   • \Core_Model
   • \Core_Model\Behaviors
   • \Core_Model\Behaviors\NCI
   • [xerces root]\include IF IT EXISTS, otherwise use [xerces root]\src
   • GSL root directory
   • [gtest root]\include
3. Under "MinGW C++ Linker", choose "Libraries". Under "Libraries (-l)", add (if Windows) "libxerces-c-3-1-2", "libgsl-0", and "gtest_main" or (if Linux) "xerces-c", "gtest_main", "gsl", "gslcblas", and "dl" (with no quotes). Under "Library search path (-L)", add \Core_Model_Tester.

Now it's time to try building the project. Choose Project->Build Project. A complete build will take longer than for the core model since there are more files to build.

Once the project is built, to run it from Eclipse, you need to create another run configuration:

1. Choose "Run->Run Configurations..."
2. Click on "C/C++ Local Application", and click "New".
3. Name it whatever you want. For "Project", make sure it says your project name. Under "C\C++ Application", choose the executable.
4. Click the "Run" button. SORTIE-ND will launch in the console window at the bottom of the screen.
5. To debug, click the debug icon after you have a run configuration set up.

You can control which tests to run in the Run Configuration for the tester code. In the "Arguments" tab, add the following: --gtest_filter=*.* Adjust this expression to match the tests you want to run. For example, --gtest_filter=GLIPoints.* runs all tests in the GLIPoints unit (TestGLIPoints.cpp).

You can run the SORTIE-ND core from the shell by navigating to the home directory and typing ./coremodel.exe. This opens up a text-based interface that leads you through the steps of running a prepared parameter file. You can also type ./coremodel.exe filenam with a parameter or batch file replacing "filename", and it will run automatically. (This works on DOS too, in Windows, leaving off the ./ bit of course.)

You may need to set your library directory environment variable to include the path to the Xerces C++ parsing libraries and SORTIE-ND's own text interface library. On Linux, this is LD_LIBRARY_PATH. Add the /lib directory in the Xerces root directory, and the Core_Model home folder.

The current GUI is written for Java 7. If you do not have the Java 7 SDK installed, you may get errors and warnings.

Get the source code for the Java user interface from this site. Create a directory for the Java project, and unzip the file into there, preserving subfolders.

The Java project creates a Java executable called "SORTIE.jar" and contains:

Main directory:

• Manifest.mf - the manifest for the "SORTIE.jar" application file
• SORTIE jar description.jardesc - file for building the "SORTIE.jar" application file

[main]/lib: A collection of Java libraries (as .jar files) that the SORTIE-ND user interface requires; most are third-party, one is the SORTIE-ND help file.

[main]/src: The source code. This is divided into two directories for the two Java packages into which the user interface code is split: "javawrapper" and "datavisualizer".

[main]/test: A collection of JUnit test files for testing the application. (JUnit is built into JBuilder.)

1. Switch to the Java perspective in Eclipse by choosing "Window"->"Open Perspective"->"Java" (or "Other"->"Java").
2. Choose "File"->"New"->"Java Project...".
3. Type whatever name you want under "Project name". Choose "Create project from existing source" and navigate to \JavaWrapper. Click "Next".
4. Choose the "Libraries" tab. Make sure JUnit has been included. If not, click "Add library". Choose "JUnit". (This adds JUnit testing ability to the project.)
5. Click "Finish."

Make sure you will compile your project for the appropriate Java release. Set at least the SORTIE-ND project to use the JRE from the current release minus one.

Now you can try building the project by right-clicking the project name and choosing "Build Project". To create the SORTIE.jar file, right-click on the "SORTIE Jar Description.jardesc" file within the Java project and choose "Create JAR".

To run the project from within Eclipse:

1. Select the project, then choose "Run"->"Run..."
2. Select "Java Application" on the left and click the "New" icon above it. This should create a new option default-marked "New_configuration".
3. Under "Name", rename it to something meaningful. Next to "Main class", click "Search". Choose "sortie.parfile.Model".
4. Click "Run".

If you want to run a JUnit test, open up the "test" folder in the left-hand "Package Explorer" pane. Right-click the test file you want to run, then choose "Run As"->"JUnit Test".

This is the library that allows SORTIE-ND to communicate with a command line window. You almost certainly won't ever need to change this code or set up this project.

If you need to compile this library, it already has a makefile. For either Windows or Linux, it should be sufficient to navigate to the library directory and type "make". This will not install the library in the sense that Linux users are used to: it will simply compile the library in the directory itself. You can leave it there, or move it to the directory of your choice. Just point the main code project to the directory with the header files for the includes, and the directory with the library for the linker.

This is the library that allows SORTIE-ND to communicate with the Java GUI. You almost certainly won't ever need to change this code or set up this project. Don't bother setting up this project if you don't need it.

If you've already installed the model code, then you will have a directory in your code root called "Interface_DLL_for_Java". In case you want to set this up in Eclipse:

1. Create a new C++ shared library project.
2. On the screen that says "New Project", choose whatever name you want for your project. Uncheck the box that says "Use default" under project contents, and set the directory to the \Interface_DLL directory.
3. If you have a choice of toolchains, choose "MinGW GCC".

Now set the compiler settings. This is most likely under Project->Properties. Choose "C/C++ Build" at the left of the screen, and under that, "Settings".

1. Under "GCC C++ Compiler", choose "Directories". Add \Core_Model (add relative directory from workspace).
2. Under Compiler Miscellaneous settings, add "-m32" to the "Other flags" line. This compiles the code as 32-bit, to maintain compatibility with 32-bit operating systems.
3. Choose the "Build artifact" tab. Under "Artifact name", put "interface" (without the quotes). Make sure the prefix is set to "lib" and extension set to "dll", so the whole library will be "libinterface.dll".

Choose Project->Build Project to build. There should be a new file called "libinterface.dll" in "Debug" or "Release".

• Eclipse isn't installed in the usual way on Windows, so it doesn't show up where programs usually do. It helps to find the "eclipse.exe" file and make a shortcut to it, and put the shortcut where you want it (for instance, on your desktop or quick launch toolbar).
• Once you have a list of multiple projects in Eclipse, make sure you select the right one before editing properties, running, etc. Get in the habit of selecting the project you're working on in the left-hand pane before you open a menu command. Or, do tasks by right-clicking on a project name.
• When you want to run a project from within Eclipse, it's a good idea to click the drop-down arrow next to the "Run" button and choose the project from there. Just because a project is selected doesn't mean that's the one Eclipse is going to run.
• Running and debugging are different operations. If you want to debug, double-click on the left gutter next to a line of code to set a breakpoint, then specifically click the "Debug" button. Clicking "Run" will not cause execution to stop at breakpoints.

If you've made changes to either the user interface or the core model, you will at some point like to try them out. Once you have compiled a new version of either "CoreModel.exe" or "SORTIE.jar", you can see how it interacts with the rest of the application. The easiest way to do this is to install the SORTIE-ND user package, and then replace the appropriate file with your new version.