Building from source on Linux
From CSP
| Table of contents |
Introduction
This page provides a step by step guide to building CSP under GNU/Linux. 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.
Step 1: Dependencies
Download and install all of the current build dependencies. Note that these dependencies are available as precompiled packages in many Linux distributions, and some may already be installed. Under Debian you can use apt-cache search to locate packages by name, and apt-get install to install them. Similar package managers (e.g., rpm, emerge) can be used on other systems.
Step 2: Client Setup
Install a subversion client and check out the latest source code. Again, the subversion client is probably available as a package on your system and may be installed by default. If not, you can always download it from tigris (http://subversion.tigris.org).
Create a directory to hold the source code and use the svn tool to check out the code:
$ mkdir csp.testing $ cd csp.testing $ svn co https://csp.svn.sourceforge.net/svnroot/csp/trunk/csp
We'll refer to csp.testing as your client directory. You can have more than one client, which is often useful for development (e.g., one client for testing other people's changes, one client for your work). Each client would be placed in a separate directory (e.g., csp.testing, csp.cockpit_design, etc.). The client directory names are not important; any naming convention will do.
When you checkout the source code you will also get almost all of the data needed to run CSP. The main exception is the terrain. You'll need to download it from SourceForge (http://sourceforge.net/project/showfiles.php?group_id=17780&package_id=67314). Grab the latest version of BalkanTerrain and unpack it into a directory 'outside' your client workspace. Then create a symlink from your client to the terrain data. For example, assuming you have downloaded the terrain data to /tmp:
$ cd .. $ ls csp.testing $ tar vxjf /tmp/BalkanTerrain-0.2.tbz $ ls csp.testing Terrain $ cd csp.testing/csp/data $ ln -s ../../../Terrain terrain
You only need to download and unpack the data once, but you will need to repeat the last step (creating a symbolic link to the terrain) for each client you check out.
Step 3: Building
GCC-4.1 is used for development under GNU/Linux, and we recommend that you use this version if at all possible. The code should continue to build cleanly in GCC-3.3 and up, but small incompatibilities may be introduced inadvertently over time. Note that various versions of GCC break ABI compatibility with earlier versions, so be careful not to mix and match libraries built with different versions of the compiler.
CSP uses the SCons build system (http://scons.sf.net). Most GNU/Linux distributions should provide a recent version (>=0.96.93 is required) of SCons, but you may have to install it explicitly (e.g. apt-get install scons under Debian). Building all of CSPSim with SCons is fairly simple. Assuming you just checked out a fresh copy of the repository as describe above, the following commands should do the trick:
$ cd csp.testing/csp $ sudo python tools/setup.py $ scons -Q all
The first command just changes to the top-level CSP directory (your workspace). The second command will install a module named csp.py in your Python site-packages directory (which generally requires root access to modify, hence the sudo). This module includes some magic to allow Python to find other modules in your CSP workspace. The final command checks for necessary third-party libraries and builds all the source code in the workspace. If you run into build problems, please post a message to the CSP forums.
Step 4: Running CSPSim
Once you have successfully built everything, it's time for the smoke test:
$ cd bin $ python sim.py
If all goes well, the sim should start and you will find yourself in the cockpit after a few seconds. If the sim won't run, you need to look in the logs to find out why. The sim.log file in the current directory contains the most useful messages, but may not contain much information since logging is set to a pretty low level by default. To enable more verbose logging, rerun the sim as follows:
$ python sim.py --logpri=DEBUG
If you can't figure out the problem, it's time to ask for help on the forum.
Step 5: Miscellaneous
Joystick calibration
Your joystick will probably need to be calibrated. If so, use jscal, a joystick calibration utility. If jscal is not included with you distribution, you can probably find it with a search engine or download it from: http://www.icculus.org/lgfaq/files/jsutils.tar.gz. Another very useful diagnostic program included in that package is called jstest. If jstest fails to recognize your joystick, you probably need to rebuild your kernel with proper input device support. You can find information about kernel support for various joysticks on the web, and you can always ask for help on the CSP forums. Of course, even if jscal finds your joystick, the default joystick mapping that CSP builds may not work with your particular joystick. If any of the axes that seem to work in jstest fail to function properly in the simulation, read tools/hid/README to find out how to create a custom mapping for your joystick.
Data compiler
CSP maintains certain static data in XML files under the csp/data/xml directory. The application does not use these files directly but instead uses a binary archive compiled from the XML sources. When you run the simulation for the first time, it should automatically create this archive (csp/bin/sim.dar). Whenever you modify the XML files you need to rebuild this archive. To do so, just run with the "--compile" option:
$ python sim.py --compile
You can also use the "--help" option to get more information.
