[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4.5.3 Building

Once you have obtained the latest Crystal Space source code package (see section Where to Get Crystal Space) and have installed or prepared the supporting libraries (see section Library Prerequisites), unpack the source code archive into a convenient directory as shown below. A description of the directory hierarchy which is created when you unpack the source code archive is available, Directory Hierarchy. A description of the files specific to the MacOS/X port is also available, MacOS/X.

 
gnutar xfz CS-package-name.tgz

A note of caution: Take care when obtaining the Crystal Space source code to ensure that the line-terminators are in Unix format (a single linefeed should terminate each line). This is an especially important consideration when transporting the code from Windows to MacOS/X. Although many MacOS/X tools deal gracefully with Windows line-terminators (a carriage-return follwed by a linefeed), not all tools do so, and may emit apparently inexplicable error messages when encountering files with Windows line-terminators. The official distributions of Crystal Space, including the stable releases and the SVN snapshots, are packaged with Unix line-terminators, which are acceptable on all supported platforms. These virgin packages themselves can be transported between Windows and MacOS/X safely

Crystal Space can be built from the command-line (Terminal.app) using either ‘make’ or Jam (see GettingJam). Both tools work equally well. In the examples below, wherever ‘make -k’ is used, you can instead substitute ‘jam’ if you so desire. Note: Apple ships a very old and highly modified version of Jam with MacOS/X which is unsuitable for building Crystal Space. If this is the only Jam which you have installed, then just build Crystal Space using ‘make’. Alternately, you may download and install a more recent version of Jam (see GettingJam). Jam might also be available via Fink (though it was not at the time of this writing).

The Crystal Space project consists of a number of components and example programs. The following commands are all issued from within the top level Crystal Space source code directory named ‘CS’.

To begin building Crystal Space, first configure the project for MacOS/X by typing the following command from within the root ‘CS’ directory:

 
./configure

At configuration time, you can also specify where Crystal Space should be installed. By default, it is installed in several subdirectories of ‘/usr/local’:

 
/usr/local/bin
/usr/local/etc/crystalspace
/usr/local/include/crystalspace
/usr/local/lib
/usr/local/lib/crystalspace
/usr/local/share/crystalspace
/usr/local/share/docs/crystalspace-x.xx

You can, however, specify a different location if desired. This setting is remembered and automatically applied later when you install the project. For example:

 
./configure --prefix=/Library/CrystalSpace

If you plan to work on Crystal Space itself, as opposed to utilizing Crystal Space for your own project, you might want to configure Crystal Space to be built in debug mode:

 
./configure --enable-debug

For a full list of configuration options, type:

 
./configure --help

If the Crystal Space source directory is read-only, if it is shared between several developers, or if you simply dislike building a project within its source tree, you can instead configure and build from a different directory. For instance:

 
mkdir $HOME/builddir
cd $HOME/builddir
/path/to/CS/configure --enable-debug

Once the project has been configured, you can begin building the Crystal Space demonstration programs. Alternately, if you are interested in building only certain components of the system, such as drivers or libraries, then you can do that instead.

To see a list of all targets which can be built, type:

 
make help

The simplest way to build the entire package, including all applications, drivers, and plug-in modules is to invoke the makefile target ‘all’:

 
make -k all

Alternately, if you are using Jam:

 
jam all

This can be a fairly time consuming operation. If you would like to be more selective and only build the necessary plug-in modules and a subset of the available applications, you can invoke their targets individually.

For example, to build all plug-in modules, you could invoke this command:

 
make -k plugins  # Builds all plug-in modules.

To build only the WalkTest application and the plug-in modules which it most commonly requires use the following target:

 
make walkall  # Builds WalkTest and most required plug-ins

For finer control over which applications and plugins are built, you can invoke their targets directly. For instance:

 
make walktest  # Builds walktest, the map exploration program
make glosx2d   # Builds glosx2d, the MacOS/X OpenGL 2D driver
make gl3d      # Builds gl3d, the OpenGL renderer

All programs require at least some plug-in modules to be present, so be sure to build those, as well, by invoking the ‘plugins’ makefile target as illustrated above if you have not already invoked the ‘all’ target.

Once you have built the project, you will probably want to install it as a software development kit (SDK). The installation phase installs everything needed to create your own programs using Crystal Space. Some resources, such as demonstration applications and certain data files are not installed since they are not required for development. Installing the SDK is optional, though recommended. If you simply wish to run the example programs, then you need not invoke the installation phase.

By default, Crystal Space is installed in subdirectories of ‘/usr/local’, however you can specify a different location when you configure the project, as explained above. Installation can be performed with the following command:

 
make install

Once you have installed the project, you can release disk space used by the build process:

 
make distclean

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated using texi2html 1.76.