In this document:
In order to program SORTIE-ND, you need following development tools installed:
Note: these are very large files. Hopefully you have a fast connection to the internet.
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":
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".
I wrote this after switching to Eclipse and the GCC compiler set and figuring it all out by trial-and-error. When I say to do things in a certain way below, I note my reasons where possible. The reason is usually "because it didn't work if I did it any other way". If you are an experienced user of any of this software, please, feel free to rely on your own knowledge and depart from the instructions.
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. 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).
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 already have Eclipse installed, skip to Step 6.
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.
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.
"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.
Make sure you do this after you've installed MinGW.
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. (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:
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.
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.
In addition to the SORTIE code, you also need a set of header files for the Xerces 2.6.0 C++ XML parsing library. These can be downloaded from http://xml.apache.org/xerces-c/download.cgi. Choose the link for the archive download site. Choose the folder Xerces-C_2_6_0. Download the file "xerces-c-src_2_6_0.tar.gz". Uncompress into the directory where you have put your other code. See the directories section above for an example.
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. At the bottom of the screen, you'll see several tabs, marked "Problems", "Console", and "Properties". You may also see a "Progress" tab, which is extremely useful for monitoring progress and cancelling processes. If you don't see it, here's how to make it visible: On the "Window" menu, go to "Show View"->"Other…". Expand the "Basic" 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.
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:
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.
The Xerces folder can be set up differently depending on what exactly you downloaded. If the header files (.hpp) are in /xerces-c-src_2_6_0/src rather than /xerces-c-src_2_6_0/include, edit line 16 of the makefile in /OBJS. Replace "-I${ALL_CODE_ROOT}/xerces-c-src_2_6_0/include" with "-I${ALL_CODE_ROOT}/xerces-c-src_2_6_0/src".
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/. 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.
The core model code allows Eclipse to write its makefile. The test code uses a makefile that I wrote. I did this so that the test code could build in the core model code files, and Eclipse isn't smart enough to handle the directories. (Or if it is, I haven't figured out how yet.)
This means that if you change the test code project, you will also have to edit the makefile. The makefile is in the /OBJS/ directory. Once you've set up the test code project in Eclipse, you can edit it from within Eclipse; or, you can use a programmer's text editor (but stay away from NotePad and the like, which will probably add and strip tab and whitespace characters in a way that will mess you up). The most likely job you will have is adding new code files. To do this, open \OBJS\makeobjs.mk. You will see lists of code files, grouped by function (test, SORTIE core, SORTIE behaviors, etc). Add the new file to the appropriate list. If you need more information about makefiles, see the GNU Make manual.
Now set the project options. Choose Project->Properties. Choose "C/C++ Make Project" at the left of the screen. On the right of the screen, choose the "Binary Parser" tab. Make sure that only PE Windows Parser is checked.
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.
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.)
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 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.
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.
Choose Project->Build Project to build. There should be new "interfacedll.a" and "InterfaceDLL.dll" files in "Core_Model".
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".
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.
Choose Project->Build Project to build. There should be a new "InterfaceDLL.dll" file in "Interface_DLL_for_Java".
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.