Installing the Code

In this document:

Tools

In order to program SORTIE-ND, you need following development tools installed:

Compilers

Note: these are very large files. Hopefully you have a fast connection to the internet.

Other Helpful Software

Directory Structure

There are five projects described below. Four of the projects, all except the SORTIE GUI, are written in C++. It is important to set up their directories carefully in order for the projects to work as I have described them below. These should be placed together in the same root directory which has no spaces in the name. (The Java project can go wherever it wants to.) Be careful about preserving the folder names where I have specified them below, down to the correct case. If you change them, or use a different directory structure than the one I specify, make sure you know how to update your makefiles accordingly.

Here is my directory structure set up correctly, in a root of "c:\sortie\code":

Project 1: The Core Model Code

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. Four folders should be created in your code root: "Core_Model", "Interface_DLL", "XML", and "Interface_DLL_for_Java". (See the example directory structure above.)

"Core_Model" contains:

"Interface_DLL" contains: Source code for a SORTIE-ND DLL. This DLL manages the DOS 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 DLL. This DLL allows the user interface and the core model to pass messages back and forth. Modify this code at your own risk.

"XML" contains: Document type definitions (DTDs) for the XML parameter file. This is not used directly by any code, and this folder can be removed if you want.

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

Installing Eclipse and setting up the C++ project

Eclipse is an open-source development environment that can be used to write code in many different languages, including the C++ used by SORTIE. Eclipse provides you with the tools to make code development easier - an editor that colorizes the code's syntax, windows to list the files in the project, buttons to compile and run.

Eclipse does not actually compile the code itself, and is not required in order to compile and run SORTIE. It just makes life easier 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. Troubleshooting is easiest when you are familiar with how to use these tools (writing makefiles, using "make", "g++", etc). 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.

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 tech 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 4. If you already have Eclipse installed, skip to Step 6.

Step 1 [Windows only]: Install MinGW

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. However, you probably won't ever need to use them directly (unless you want to). You just want their libraries and executables.

  1. Download and install MinGW at http://sourceforge.net/projects/mingw/. I used the file "MinGW-5.1.4.exe".
  2. IMPORTANT: Install to a directory with no spaces in it, like "c:\MinGW".
  3. When installing, you get a checklist of components you wish to install. You only need to check the gcc compiler.
  4. Once you've finished installing, put the path \MinGW\bin in your PATH environment variable. This allows you to run the MinGW software from any directory, which is critical for Eclipse. To set this on Windows XP, go to the Control Panel, open "System", then choose the "Advanced" tab. Click the button that says "Environment Variables." Under System variables, choose the one that says "Path" and add the directory (for example, "c:\mingw\bin"). Put it at the beginning of the list. DON'T ERASE ANY VALUES THAT ARE ALREADY THERE. You'll have to restart for this to take effect.

CHECK: To make sure you've done this correctly so far, open a DOS 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 every component. If the files are there, double-check the directory you added to your Path environment variable in step 4 above.

Step 2 [Windows only]: Install gdb for MinGW (maybe)

"gdb" is the debugger that goes with the GCC toolset and it might not come with your install of MinGW. Once you've installed MinGW, to see if you have it, open a DOS window and type "gdb". If it says "no such file", you don't have it and you need to install it.

Download it at http://www.mingw.org/download.shtml. I got the file "gdb-6.3-2.exe". Install it into the same directory as the rest of your MinGW install.

Step 3 [Windows only]: Install MSYS

Make sure you do this after you've installed MinGW.

  1. From SourceForge, download and install MSYS. (Search for the MinGW project.) I used file "MSYS-1.0.10.exe".
  2. Install MSYS to a directory with no spaces (like "c:\msys\1.0").
  3. During setup, it will ask you if you have MinGW installed. Tell it yes and point it to the correct directory.
  4. Put \msys\1.0\bin in your Path environment variable, just like with MinGW. Restart again.

Step 4: Install Eclipse

Make sure you have a Java Runtime Environment installed. If you don't, you can download it from www.java.com. You also need to have the Java directory in your Path environment variable. (Windows users, see the instructions for installing MinGW for instructions for modifying the Path variable.) If you don't, find the directory which has "java.exe" in it, and add that to Path. Once that's done, install Eclipse:

Windows:

  1. Download file "eclipse-SDK-3.4-win32.zip" (or your choice of other 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 don't already have Eclipse, you're on your own. Eclipse has come pre-installed on both distributions I've tried.

Step 5: Install C++ Development Tools for Eclipse

Eclipse needs to have a plugin installed in order to work with C++ (the C++ Development Tools, or CDT). You can do this from within Eclipse. Linux users, if Eclipse came pre-installed in your distribution, you probably also already have the CDT.

  1. Launch Eclipse.
  2. Choose "Help"->"Software Updates" move..."
  3. Choose the tab marked "Available Software"
  4. Check the box next to "Ganymede" and then "C and C++ Development", and then click "Install"
  5. Click through the rest of the install. After the install is completed, please make sure you accept the workbench restart.
  6. Once you have installed the C++ development tools, when you want to use the C++ environment, switch to it by clicking "Window"->"Open Perspective"->"Other"->"C/C++", or use the button at the top right of the screen.

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

CHECK:

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

Step 6: Create the SORTIE Project in Eclipse

Libraries. There are two external libraries that SORTIE requires: the Xerces 2.8.0 C++ XML parsing library, and the GNU Scientific Library 1.11 (GSL).

Windows: The DLL files for these libraries are included in the SORTIE download, but you also need a set of header files for these libraries . These can be downloaded from http://xml.apache.org/xerces-c/download.cgi and http://www.gnu.org/software/gsl/. For Xerces, choose the link for the archive download site. Choose the folder Xerces-C_2_8_0. Download the file "xerces-c-src_2_8_0.tar.gz". Uncompress into the directory where you have put your other code. See the directories section above for an example.

Linux: You can download and install the Xerces and GSL packages through your distribution, most likely. In my Ubuntu install, I use the Synaptic Package Manager to get the libgsl0-dev and libxerces28-dev packages (the "dev" version is important, as that is how you get the header files).

Now you are ready to set up the SORTIE 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".

  1. Create a new project by choosing "File"->"New"->"C++ Project".
  2. On the screen that says "C++ Project", 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. Under "Project types", choose "Executable". Click "Next".
  3. Under "Select Configurations", leave only "Debug" checked ("Release" won't hurt anything, it's just not necessary).
  4. Click "Finish". It might start trying to build the project immediately. Don't wait for it to do this, but proceed immediately to the next step:
  5. Under the "Project" menu, make sure "Build Automatically" is unchecked.

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. For instance, if the C++ Indexer is running at this point, you can cancel it now.

Now set the project options. Choose Project->Properties.

  1. [WINDOWS]: Choose "C/C++ Build" at the left of the screen, and under that, "Settings". 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 DLL. (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:
  4. Under "MinGW C++ Linker", choose "Libraries". Under "Libraries (-l)", add (if Windows) "libxerces-c", "libgsl-0", and "interfacedll" or (if Linux) "xerces-c", "gsl", "gslcblas", and "interface" (with no quotes). Under "Library search path (-L)", add \Core_Model.
  5. 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.
  6. You may notice the C++ Indexer start working (there will be a progress bar in the lower right of the screen). You don't have to wait for this to finish, but it's a good idea. The indexing needs to happen eventually. (If you can't let it finish now, don't worry. The Indexer will try again later.)

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 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.

Project 2: The C++ Test Project

The C++ test project contains test code for the C++ core model. The testing framework used is CppUnit. The test code is separate from the model code and is not required to compile the model.

Get the source code for the C++ test project model from this site. Put the code in the same root directory as the C++ core model code. It should be in a folder called "Core_Model_Tester". See the directory structure section above.

You will need to download CppUnit in order to get the header files - plus it has very helpful documentation. Download version 1.10.2 (or other versions at your own risk) at http://sourceforge.net/projects/cppunit/. Linux: Install the CppUnit dev package. There are instructions for building the CppUnit DLL in Eclipse if you want; otherwise, put the uncompressed folder in the code root folder and rename it "cppunit_eclipse".

The C++ test project contains:

Setting up the C++ test project in Eclipse

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

  1. Create a new project by choosing "File"->"New"->"C++ Project".
  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. Under "Select Configurations", leave only "Debug" checked ("Release" won't hurt anything, it's just not necessary).
  4. Click "Finish".

Now link to the SORTIE 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.

Now set the project options. Choose Project->Properties.

  1. [WINDOWS]: Choose "C/C++ Build" at the left of the screen, and under that, "Settings". 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:
  3. Under "MinGW C++ Linker", choose "Libraries". Under "Libraries (-l)", add (if Windows) "libxerces-c", "libgsl-0", and "cppunit" or (if Linux) "xerces-c", "cppunit", "gsl", "gslcblas", and "dl" (with no quotes). Under "Library search path (-L)", add \Core_Model_Tester.
  4. Choose the "Build artifact" tab. Under "Artifact name", put "../modeltester" (without the quotes). This tells Eclipse to create an executable called modeltester.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 will take longer than for the core model since there are more files to build.

Once the project is built, there should be a file called "modeltester.exe" in your \Core_Model_Tester 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 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 \Core_Model_Tester\modeltester.exe.
  4. Click the "Run" button. SORTIE 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.

If you open the file "main.cpp", you will see how to run a test. Essentially, all tests are commented out except the one you want to run. Theoretically, you are supposed to be able to let CppUnit find your tests and run them all at once. I have tried this with multiple versions of the library and get crashes that I cannot solve, and that do not happen when I run the tests one at a time. I don't know whether the trouble is with my code or CppUnit, and at this point, I don't care. This system works okay.

Running SORTIE from Linux

You can run the SORTIE 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 filename" 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'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.

Project 3: The Java GUI project

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:

[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.)

Setting up the Java project in Eclipse

  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. Click "Add library". Choose "JUnit". (This adds JUnit testing ability to the project.)
  5. Click "Finish."

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 "Model - javawrapper".
  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".

Project 4: The C++ Interface DLL

This is the library that allows SORTIE to communicate with a DOS window. 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. You just need the directory here for the header files.

If you've already installed the model code, then you will have a directory in your code root called Interface_DLL.

Setting up the C++ Interface DLL project in Eclipse

This assumes that you have set up the C++ project, and thus installed Eclipse, etc. Unlike the core model, this project uses a makefile I wrote. The makefile puts the freshly compiled DLL into the "Core_Model" directory. If your directory structure does not match my recommended structure, you should edit the makefile accordingly.

  1. Create a new project by choosing File->New->Standard Make C++ Project. Note: This is NOT the same option we started with for the model code.
  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. Under "Select a Type of Project", use the default settings - Executable (Gnu on Windows), both "Debug" and "Release" checked.
  4. Leave the defaults for the next window as well, then click "Finish".

Choose Project->Build Project to build. There should be new "interfacedll.a" and "InterfaceDLL.dll" files in "Core_Model".

Project 5: The C++ Interface DLL for Java

This is the library that allows SORTIE 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".

Setting up the C++ Interface DLL for Java project in Eclipse

This assumes that you have set up the C++ project, and thus installed Eclipse, etc. Unlike the core model, this project uses a makefile I wrote.

  1. Create a new project by choosing File->New->Standard Make C++ Project. Note: This is NOT the same option we started with for the model code.
  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_for_Java directory.
  3. Under "Select a Type of Project", use the default settings - Executable (Gnu on Windows), both "Debug" and "Release" checked.
  4. Leave the defaults for the next window as well, then click "Finish".

Choose Project->Build Project to build. There should be a new "InterfaceDLL.dll" file in "Interface_DLL_for_Java".

Tips on running Eclipse

Incorporating changes into the SORTIE-ND software

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.


Last updated: 18-May-2007 09:11 AM