Installing the Code

This document will get you set up to begin programming SORTIE-ND.

Required Software

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

Helpful Software

Setting up the C++ Core Model Project

Get the source code for the core C++ model from http://www.ecostudies.org/SORTIE/download.html (username "user", password "sortie61"); select "C++ Project with Interface.zip". Create a directory for the C++ project, and unzip the file into there, preserving subfolders.

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

The C++ project contains:

The main project directory:

[main]/Behaviors: This folder contains the source code for SORTIE-ND's behaviors.

[main]/Interface DLL: This folder contains the 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.

[main]/Interface DLL for Java: This folder contains the 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.

[main]/Math library: This folder contains the source code for a SORTIE-ND DLL. This DLL contains some common math functions needed by SORTIE-ND, like its random number generator. [main]/Test objects: This contains code for a set of behaviors for testing use. These do not appear in the user interface. They can be used by developers and power users to help debug a run. [main]/XML: This folder contains the DTDs (document type definitions) for the XML parameter file. Setting up the C++ project in CBuilderX Presumably, at this point you have unzipped the file "C++ Project with Interface.zip" into the directory where you plan to keep your project. I will refer to this directory as "main". 1. Unzip the source code for Xerces 2.5.0 to the directory of your choice. It does not have to be in the main C++ code directory. You only need it for its header files. 2. Unzip the source code for Xerces 2.5.0 to the directory of your choice. It does not have to be in the main C++ code directory. You only need it for its header files. 3. Create a new project in CBuilderX. a. Choose "File->New." Choose the "Projects" tab. b. Choose "New Console" (this means you are setting up a DOS/command line application). c. In the first window of the wizard: Give your project a name, and point it to your main project directory. d. Leave the defaults for the other windows of the wizard. 4. Add the source code files to your project by choosing "Project->Add Files…". a. Add all .cpp files from [main]. b. Add all .cpp files from [main]/Behaviors. c. Add all .cpp files from [main]/Test Objects. d. Add "xerces-bor_2_5_0.lib", "InterfaceDLL.lib", and "mathlib.lib" from [main]. 5. Set up your include directories so the compiler knows where to look for .h files. Choose "Project->Build Options Explorer", options for BCC32, "Paths and Defines" tab. Add the following directories to "Include search path": a. [main] b. [main]/Behaviors c. [main]/Math Library d. [main]/Test Objects e. [main]/Interface DLL f. from wherever you put the Xerces 2.5.0 source, "xerces-c-src_2_5_0/src" 6. Set up your include directories so the linker knows where to look for DLLs. Choose "Project->Build Options Explorer", options for ILINK32, "Paths and Defines" tab. Add [main] to "Library search path". 7. Tell the linker what to make as the final executable. Choose "Project->Build Options Explorer", options for ILINK32, "Target Settings" tab. Choose the file "CoreModel.exe" in the main directory. 8. Set up a conditional define that tells the compiler how to deal with SORTIE-ND DLL header files. Choose "Project->Build Options Explorer", options for BCC32. Add GENERATING_DLL_APP to the "Conditional Defines". Now make or build your project (from the "Project" menu). If it is successful, you have correctly set up the project and are ready to do your own development. Using CBuilderX Here are some quick tips for using CBuilderX: · You can compile in two ways, make and build. "Make" compiles only if there have been changes to the source. "Build" (or "rebuild") does a complete re-compile no matter what. · You can compile just the code you're currently working on by choosing "Project->Make [name of file]". · To run the application in non-debug mode, choose "Run->Run Project". In this mode, all breakpoints are ignored. · To run the application in debug mode, choose "Run->Debug Project." All breakpoints will be honored. · To set a breakpoint, click just to the left of a line number. · When in debug mode, it is the default for CBuilderX to stop on all destructors, throws, and catches. To change this (which can be annoying), choose "Project->Project Properties", "Debug" tab, "DBK Debugger" tab. Setting up the C++ Test Project The C++ test project contains test code for the C++ core. It is based on CppUnit. CppUnit does not compile well on its own with Borland compilers. My solution was basically one huge, ugly hack. Despite this, it is extremely handy to have automated testing code and I continue to use it constantly. Someday I will make it lovely. Get the source code for the C++ test project model from http://www.ecostudies.org/SORTIE/download.html (username "user", password "sortie61") and selecting "C++ Test Application.zip". Create a directory for the C++ project, and unzip the file into there, preserving subfolders. If you want to download the CppUnit source code yourself, including the helpful documentation, you can do so at http://sourceforge.net/projects/cppunit/. The C++ test project contains: The main project directory: · The test code files. There is generally one test .cpp file for each SORTIE-ND .cpp file (although there are exceptions). · Xerces DLL, used for parsing XML · MathLib DLL [main]/cppunit-1.8.0: CppUnit source code. Setting up the C++ project in CBuilderX Presumably, at this point you have unzipped the file "C++ Project with Interface.zip" into the directory where you plan to keep your project. I will refer to this directory as "main". This also assumes that you have set up the C++ project. 1. Create a new project in CBuilderX. a. Choose "File->New." Choose the "Projects" tab. b. Choose "New Console" (this means you are setting up a DOS/command line application). c. In the first window of the wizard: Give your project a name, and point it to your main project directory. d. Leave the defaults for the other windows of the wizard. 2. Add the source code files to your project by choosing "Project->Add Files…". a. Add all .cpp files from the main project directory of the C++ code project EXCEPT "sortie.cpp". b. Add all .cpp files from [main]/Behaviors directory of the C++ code project. c. Add all .cpp files from [main]/Test Objects directory of the C++ code project. d. Add "xerces-bor_2_5_0.lib", and "mathlib.lib" from the [main] directory of the C++ code project. e. Add all of the .cpp files from [main] of the test project. f. Add all of the .cpp files from [main]/cppunit-1.8.0/src/cppunit of the test project. 3. Set up your include directories so the compiler knows where to look for .h files. Choose "Project->Build Options Explorer", options for BCC32, "Paths and Defines" tab. Add the following directories to "Include search path": a. [main] of the C++ test project b. [main] of the C++ code project c. [main]/Behaviors of the C++ code project d. [main]/Math Library of the C++ code project e. [main]/Test Objects of the C++ code project f. from wherever you put the Xerces 2.5.0 source, "xerces-c-src_2_5_0/src" g. [main]/cppunit-1.8.0/include of the C++ test project 4. Set up your include directories so the linker knows where to look for DLLs. Choose "Project->Build Options Explorer", options for ILINK32, "Paths and Defines" tab. Add [main] of the C++ test project to "Library search path". 5. Tell the linker what to make as the final executable. Choose "Project->Build Options Explorer", options for ILINK32, "Target Settings" tab. Name the file whatever you want (but be sure to specify the extension as .exe), and put it in the main directory. Now make or build your project (from the "Project" menu). If it is successful, you have correctly set up the project and are ready to do your own development. 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. You will probably get access violations if you run more than one test at a time. I don't know why. You will notice that there are a LOT of source files in this project. CBuilderX's linker can't actually handle all of them at once. I tend to remove several test files from the project, and add them back if I need to run them. Again, the project's a hack. Setting up the Java project Get the source code for the Java user interface from http://www.ecostudies.org/SORTIE/download.html (username "user", password "sortie61") and selecting "Java project.zip". Create a directory for the Java project, and unzip the file into there, preserving subfolders. The Java project produces as its output a Java executable called "SORTIE.jar". Tthe Java project contains: Main directory: · Manifest.mf - the manifest for the "SORTIE.jar" application file · Library files for various Java libraries [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 JBuilder JBuilder projects are easily transferred, and in my experience, don't require setup. Go into JBuilder, choose "File->Open Project", and select "JavaWrapper.jpx" from the Java project main directory. You can then begin developing. Using JBuilder Here are some quick tips for using JBuilder: · You can compile in two ways, make and build. "Make" compiles only if there have been changes to the source. "Build" (or "rebuild") does a complete re-compile no matter what. · You can compile just the code you're currently working on by choosing "Project->Make [name of file]". · To run the application in non-debug mode, choose "Run->Run Project". In this mode, all breakpoints are ignored. · To run the application in debug mode, choose "Run->Debug Project." All breakpoints will be honored. · To set a breakpoint, click just to the left of a line number. · To run a JUnit test file, right-click the filename and choose "Run test using defaults". Running the full SORTIE-ND model 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. Other development tools In practice, you could use any development tools with which you are comfortable to code SORTIE-ND. SORTIE-ND should not contain anything except ANSI-C++ and pure Java. Of course, it is highly unlikely that any other compiler will compile SORTIE-ND code without complaining. If you choose to use different software, it is up to you to figure out how to configure it correctly. Once you have done so, I will be happy to make any changes to the code to allow it to work with multiple compilers.
29-Apr-2004 07:57 AM