In this document:
In order to program SORTIE-ND, you need following development tools installed:
There are five projects described below. Four of the projects, all except the SORTIE GUI, are written in C++. The projects reference each other's directories. I recommend placing them together in the same root directory which has no spaces in the name. (The Java project can go wherever it wants to.)
Here is my directory structure, in a root of "c:\sortie\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. Three folders should be created in your code root: "Core_Model", "Interface_DLL", 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.
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. 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 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.
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 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. (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.
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 and only if you want to work with the GUI code, you will need the Java development tools as well.
Windows:
Linux users, you almost certainly 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. Linux users, you probably also already have the CDT. If you don't, you can do this from within Eclipse. Read the directions for your version of Eclipse to install the CDT. 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.
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://xerces.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. You may have to build the GSL library to get the header files.
Linux: You can download and install the Xerces and GSL packages through your distribution. Make sure to get the "dev" packages, as that is how you get the header files.
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. 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.
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".
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. (It will run at some point, and it's very useful, but it will work better after changing some settings.)
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".
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:
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 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:
This assumes that you have set up the C++ project, and thus installed Eclipse, etc.
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 compiler settings. This is most likely under Project->Properties. Choose "C/C++ Build" at the left of the screen, and under that, "Settings".
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:
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.
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.
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:
[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.)
Make sure you will compile your project for the appropriate Java release. Set at least the SORTIE 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:
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 to communicate with a command line 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.
This assumes that you have set up the C++ project, and thus installed Eclipse, etc.
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".
Choose Project->Build Project to build. There should be a new file called "libinterface.dll" in "Debug" or "Release".
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". Set this up the same way as the "Interface DLL" project.
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.