Building from source on Windows
From CSP
| Table of contents |
Introduction
This page provides a step-by-step guide to building CSP under Windows. Installing all the dependencies and building from source can be daunting, but our goal is to make the process as simple and intuitive as possible. If you find information here that is unclear or out of date, please correct it or notify someone on the CSP forum.
To compile and run CSP we recommend a moderately fast computer (minimum 1GHz Athlon), 512MB of RAM, and a modern 3D graphics card (GeForce4 or better).
Dependencies and Tools
Building CSP requires the following packages and tools:
- CSP DevPack 0.6.1 (http://prdownloads.sourceforge.net/csp/cspdevpack-0.6.1-installer.exe?download). This executable will install precompiled libraries and header files for the external dependencies. It will also set the CSPDEVPACK environment variable, which is used by the build system to locate these files. See Building the Third-Party Libraries for building the dependencies yourself.
- Visual C++ 2005 Express Edition (http://msdn.microsoft.com/vstudio/express/visualc). Unless you have VC++ 7.1/8 or an other standard-compliant C++ compiler already installed, download this free compiler and development environment. CSP is known to compile with these versions of the Microsoft compiler. Older versions of the Microsoft compiler are not supported and will probably not work. (Compilers from other vendors have not been tested. Please report back if you do.)
- Microsoft Platform SDK (http://msdn.microsoft.com/platformsdk). Unless the Platform SDK is already installed with your compiler you also need to install the Microsoft Platform SDK. It is not included with Visual C++ 2005 Express Edition. Follow the instructions at the given link to download.
- Python 2.4 (http://python.org/ftp/python/2.4.1/python-2.4.1.msi). Parts of the CSP simulator is programmed in the Python programming language. Open this Windows Installer file to install Python. Version 2.3 works as well.
- SWIG 1.3.27 (http://prdownloads.sourceforge.net/swig/swigwin-1.3.27.zip). CSP depends on SWIG for interfacing C++ and Python code. Unzip the file to create "C:\Program Files\swigwin-1.3.27". Versions 1.3.21 and newer should also work, 1.3.36 works for sure.
- SCons 1.2.0 (http://sourceforge.net/project/showfiles.php?group_id=30337). This executable installs the SCons build system used and extended by CSP. Make sure SCons is installed correctly. Especially on Vista machines the install script might run into trouble. If you encounter problems, go to the command line and execute python setup.py install. Older versions are likely not to work.
- TortoiseSVN (http://tortoisesvn.net). CSP uses Subversion (http://subversion.tigris.org) for version control, so you will need a compatible client to check out the source code from the repository. TortoiseSVN is our recommended Subversion client under Windows, as it provides a simple graphical interface, but you can use other clients or plain Subversion commands if you so wish.
Checking Out a Working Copy
Note: We assume you are using TortoiseSVN here. If you are unfamiliar with source code management with Subversion, you may want to browse the TortoiseSVN documentation (http://tortoisesvn.net/doc_release). The "Checking Out A Working Copy" section of the manual is particularly relevant. If you are using a different client, refer to its documentation and adapt the instructions below accordingly.
Create a folder in Windows Explorer where you want to place the source code for CSP, also referred to as a working copy. This could be any folder but we recommend creating a new folder with a distinctive name. We will use "My Documents\CSP Testing" in this guide.
Right-click the folder to pop up the context menu and select the command "SVN Checkout" (if not visible, it should be located under the "TortoiseSVN" submenu). In the "Checkout" dialog box that comes up, enter the following URL in the "URL of repository" field:
https://csp.svn.sourceforge.net/svnroot/csp/trunk
The "Checkout directory" field should already be set to the chosen folder. If not, correct it. Uncheck both the "Only check out the top folder" and "Omit externals" checkboxes. Under "Revision" select "HEAD Revision" — unless you intentionally want an older version, in which case you should enter the revision number you want. Finally, click "OK".
TortoiseSVN will then download the selected revision of the CSP source code from the CSP repository, creating a new folder named "csp" inside the chosen folder.
Downloading the Terrain
The CSP repository does not include the terrain for the simulator, hence the check out above lacks necessary terrain files. So in addition to the check out you must download the latest BalkanTerrain (http://sourceforge.net/project/showfiles.php?group_id=17780) package and manually install it into your working copy. Download and extract the terrain package to the "csp\data\terrain" folder. Once extracted this folder should contain a large number of BMP files. Be careful that these do not end up under "csp\data\terrain\terrain".
Setting Up the Environment
Several environment variables must be set for the compiler and libraries to function properly in the CSP build system. See the KB310519 support article (http://support.microsoft.com/default.aspx?scid=kb;en-us;310519) from Microsoft if you are unfamiliar with environment variables under Windows XP. In Windows 95/98/ME you need to modify "autoexec.bat" and then reboot the computer.
The following environment variables settings provide an example of a working configuration on one particular development system. Note that line breaks after each semicolon have been added here to make the text more readable, though the actual settings for each variable must be a single continuous line.
PATH=C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\Bin;
C:\Program Files\Microsoft Visual Studio 8\Common7\IDE;
C:\Program Files\Microsoft Visual Studio 8\VC\BIN;
C:\Program Files\Microsoft Visual Studio 8\Common7\Tools;
C:\Windows;
C:\Windows\System32;
C:\Program Files\Python24;
C:\Program Files\swigwin-1.3.27
LIB=C:\Program Files\Microsoft Visual Studio 8\VC\LIB;
C:\Program Files\Microsoft Platform SDK\Lib;
C:\Program Files\Python24\libs
INCLUDE=C:\Program Files\Microsoft Visual Studio 8\VC\INCLUDE;
C:\Program Files\Microsoft Platform SDK\INCLUDE
CSPDEVPACK=C:\Program Files\cspdevpack-0.6
This example is provided only as a guide — the actual paths may differ on your system depending on Windows version, compiler, Platform SDK version, and installation paths.
Note that both Python and SWIG are included in the PATH variable. It is important that you be able to open a command prompt and run python, swig, scons, cl, and link directly without specifying the full path. Note that SCons is typically available via the Python path, so it doesn't have its own entry in the PATH variable. The CSPDEVPACK variable should be set automatically by the devpack installer — if it is not set correctly you should manually set it.
Building CSP
Open a Command Prompt, e.g. by selecting Start | Run and entering "cmd", or by selecting Start | All Programs | Visual Studio 2005 Express Edition | Visual Studio Tools | Visual Studio 2005 Command Prompt. The latter method has the advantage of setting up the environment variables for the compiler, which is particularily benefitial if you have many compilers and/or compiler versions installed. In any case, ensure that the environment variables are set as described above.
Change the current directory to the "csp" folder in your working copy root folder. For example, if you checked out the source code following the instructions above you could enter the following commands:
%homedrive% cd "%homepath%\My Documents\CSP Testing\csp"
Once in the "csp" folder, execute the following command:
python tools/setup.py
This step only needs to be done once. It will configure your Python installation to know about CSP. If it succeeds you will not need to run it again as long as you don't reinstall Python. Next run the following command:
scons config
The "config" build argument runs various tests to check that your environment is configured correctly. If this step fails, verify that you've correctly followed all the instructions above. Post a message on the forum if you need assistance. Finally run the following command:
scons all
The "all" build argument builds all of CSP. A few warnings are expected — particularly when compiling source files generated by SWIG — but the build should run to completion without error. This step can take anywhere from a few minutes to tens of minutes depending on your computer.
You can also use the "-jX" option to perform a parallel build on multicore CPUs. Just repace the "X" with the number of cores of your CPU. Using this option will reduce the build time dramatically. However, when building the debug version on Windows, the parallel build option will prevent debug symbols from being added to the .pdb file. Thus, no debug info will be available! If you need debug info, please do not use this option.
Using Visual Studio for Source Code Editing
If you want to use the Visual Studio IDE to browse and edit the source code you can use scons to build a project file. Go to the "csp" folder as described in the above paragraph and enter:
scons vcproj
This will create a project file that can be opened in Visual Studio. As this project file is not part of the CSP SVN repository you have to repeat this step manually whenever a file was added or removed from the project. If you want to add files yourself you have to edit the scons script.
Please note that this project file can only be used for editing the code, but not for building the project. Only building via scons is currently supported for Visual Studio.
Running the Simulator
From a command prompt, change to the "bin" subfolder and run the simulation:
cd "%homepath%\My Documents\CSP Testing\csp\bin" python sim.py
If everything works correctly, this should bring up a new window that displays a sequence of splash screens, followed by the virtual world as seen from the cockpit. If you get any crashes, error messages or other erratic behaviour at this point, please report back on the forums.
Troubleshooting
- If the "python tools/setup.py" command gives "import" related errors, it may be because the name of the checked out "csp" folder is incorrect. It has to be lower-case "csp". If it is not, rename the folder and retry the "python tools/setup.py" command. This problem is usually the result of checking out "trunk\csp" (as per old instructions here) into a user-named folder rather than checking out the top-level "trunk". The latter will always create the "csp" folder with the correct name and case.
If any of the steps above fail, please document the symptoms, underlying problem(s), and solution here and post a note on the forum to notify the developers. Of course also update any of the instructions above that are erroneous, misleading, or incomplete.
Appendix: Building the Third-Party Libraries
If you prefer to build the external dependencies yourself — which is quite difficult and not recommended — you will need to place the dll, lib, and header files into a directory layout that is similar to the standard devpack installation. Ask on the forum if you need help.
