Getting Started with the Cafu Source Code

This text explains how you get and compile the Cafu source code.

Most steps that are explained below are only necessary once, when you get and compile the Cafu source code for the first time.

This section explains how you initially get the Cafu source code. The Cafu source code can be obtained from a compressed archive or by checking out from its Subversion repository.

The easiest way to get the Cafu source code is to download the compressed archive for your platform from www.cafu.de/downloads.

The contents of the Windows and Linux archives is the same (inclusive end-of-line style), but Linux users should still get tar archive as it properly sets the executable flags that are required for the build scripts.

Extract the archive contents into an arbitrary directory and you're ready for the next step.

Alternatively, you can also check out the Cafu source code directly from its Subversion repository.

Subversion is a version control system that allows the Cafu developers to work on their copy of the source code independently of each other, and to distribute the latest version of the source code to users and developers at any time.

If you don't know Subversion yet, please have a look at the Subversion website and the Subversion Book. The book is very well written and available for free in several languages.

We recommend that you prefer checking out the source code from the repository over getting it from a compressed archive whenever possible: The code from the repository is always the latest and can easily be updated at any time. There is no better way to get and share new features and bug fixes conveniently and simple.

Check out the source code at the command-line under Windows or Linux with this command:

> svn checkout https://svn.lcube.de/dev123/projects/cafu/trunk Cafu

This command assumes that you have already installed the Subversion command-line client. You can get Subversion binaries from the Getting Subversion website for Windows, Linux and many other systems. Note that with most Linux distributions, installing Subversion via the systems package manager is usually preferred. If you prefer using Subversion with a graphical user interface, you can use Subversion clients like TortoiseSVN as well.

Cafu uses SCons as its software build system on all supported platforms. SCons is a modern replacement for make and Makefiles. SCons requires the Python scripting language to be installed, so that you have to get and install both Python and SCons on your computer.

Under Windows, first get and install Python from http://www.python.org/download/, then get and install SCons from http://www.scons.org/download.php. Note that at this time, you have to get the latest version 1.2.0.d20100306 of SCons, version 1.2.0 is labeled stable but it's older and doesn't work.

That is normally all, but you may wish to check if the Python installer added Pythons Scripts directory to the PATH environment variable of your system. For example, if Python was installed in C:\Program Files\Python26, then PATH should contain C:\Program Files\Python26\Scripts. Otherwise, you have to add the proper directory manually.

In order to verify that everything is working correctly, open a new command prompt and enter scons -v:

> scons -v
SCons by Steven Knight et al.:
        engine: v1.2.0.d20100306.r4691, 2010/03/06 16:22:36, by bdbaddog on mvdog
Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation

The report of the SCons version indicates that both Python and SCons are ready for use.

Under Linux, just use the systems package manager in order to install SCons. The package manager will automatically install SCons and all software that SCons depends on, such as Python.

This section lists additional software packages that must be installed on a Linux system before the Cafu source code can be compiled.

On a fresh, newly installed Ubuntu 8.04 (Hardy Heron) system, you'll additionally need the following packages. This can be done at the command prompt with the apt-get install command, or via the easier to use “Synaptic Package Manager” (recommended). Similar packages and package management systems also exist on RedHat Linux, SuSE, etc., where you can proceed analogously.

• A graphics driver with 3D hardware acceleration (the right driver is usually auto-detected and installed by the “Driver Manager”).
• build-essential – The compiler and basic tools required to compile C and C++ programs.
• libgtk2.0-dev – Developer files for GTK 2.0, needed for building wxGTK.
• libgl1-mesa-dev and libglu1-mesa-dev – OpenGL developer files, needed for building wxGTK and the Cafu rendering subsystem. On Debian Sarge (3.1), the packages xlibmesa-gl-dev and xlibmesa-glu-dev used to serve the same purpose, but on newer systems, they have been replaced by the libgl(u)1-mesa-dev packages.
• libasound2-dev – ALSA developer files, needed for building OpenAL-Soft.

Make sure that when you're done, all packages from the list and their dependencies are installed on your Linux system.

Cafu can be compiled as 32-bit and 64-bit software on all platforms. The following compilers are supported:

These are just the compilers that we regularly use here at CFS, other compilers should work as well. As the Cafu source code is very portable, compilers that are sufficiently standards compliant can be employed without further ado.

Copy file Cafu/CompilerSetup.py.tmpl to Cafu/CompilerSetup.py, then open the new Cafu/CompilerSetup.py file for editing:

# Edit the settings and paths in this file as required for your system.
 
# The default compiler to be used for each platform.
# Note that this can easily be overridden at the command-line
# by the "cmp" parameter. Example: scons -Q cmp=vc8
defaultCompilerWin32="vc9";     # Valid values are "vc8" and "vc9".
defaultCompilerLinux="g++";     # Currently, only "g++" is a valid value.

Note that the file must really be copied as described above, renaming it or editing the .tmpl source file is not enough.

The actual file may have more lines, but these are all you need. Edit the default compiler settings as required, that is, if you use Visual C++ 2005, change the vc9 into vc8. Most people will probably find the defaults correct and thus have to edit nothing at all. That's all – save and quit.

You are now ready compile the Cafu source code. When you do this for the first time, be prepared that it will take a while: Everything is being built from scratch, twice, as we have debug and release builds.

At the command prompt, change into the top-level Cafu directory (where also the files CompilerSetup.py and SConstruct are), then type:

> scons -Q

This will start the compilation.

Under Linux, if you have a multi-core system, you can speed-up the build by allowing N jobs as once:

> scons -Q -j N

where N is the maximum number of jobs to start at once. Try for example -j 4 on a quad-core machine.

You may use the time while the build process is running to download some supplemental files. These files are not strictly required, but will help you with trying out the newly compiled programs as described below.

We recommend that you download and extract the following files:

Note that although these files are zip archives, they are for use on all platforms (Windows and Linux). With these files, you can immediately run the Cafu engine and see some example worlds when the compilation has finished.

When the SCons script has finished, all Cafu programs have been built in several build variants, namely debug, profile and release:

• The debug variant contains additional program information and no code optimizations, and is often used during development and for finding and fixing bugs.
• The release variant has program optimizations enabled in order to maximize the execution speed, and it contains no debug information. This variant is usually shipped to end users.
• The profile variant is almost like the release variant, but also contains some debug information in order to make it suitable for use with a performance profiler. This variant is not being built by default, you have to call SCons with the proper parameters or edit the CompilerSetup.py script in order to activate profile builds.

As all variants can be built for each compiler on each platform, the build process organizes the binaries in a directory hierarchy of the form

 build/$platform/$compiler/$variant 

That is, if your compiler is Visual C++ 2008 (abbreviated as vc9) and your platform is Windows (abbreviated as win32), and you want to run the release variant of the new programs, then the related binaries are relative to the path

 build/win32/vc9/release/ 

Another important consideration is that all programs assume the top-level Cafu directory as their working directory.

Combining these facts provides you with several options on how you can run the new programs:

1. Copy the programs of the platform, compiler and build variant of your choice from Cafu/build/$platform/$compiler/$variant/… directly into the Cafu directory. This is what we do at CFS for the prepackaged binary releases, as end-users can then simply and directly double-click each executable in the Windows Explorer.
2. Create a Windows link (.lnk) or batch (.bat) file in the proper working directory that calls the desired program in its original location.
3. For developers, the most flexible and recommended approach is to run the program directly from the command prompt: First change the current working directory to Cafu, then type the relative path to the desired program (TAB completion – also on Windows – proves to be a great help here!).
   For example, running the debug version of CaWE under Windows looks like this (note that the example also shows the current working directory at the left, the actual command follows the > character):

    D:\Cafu> build\win32\vc9\debug\CaWE\CaWE.exe 

   Running the release version of Cafu under Linux looks like this:

    ~/Cafu> ./build/linux2/g++/release/Ca3DE/Cafu 

If you have downloaded the binary assets as instructed above, you can now run your self-compiled Cafu engine e.g. at build\win32\vc9\release\Ca3DE\Cafu.exe and enjoy one of the included demo levels!

Congratulations! When you get here, you have managed to successfully compile the Cafu source code and run the resulting binaries. You may now wish to familiarize yourself more completely with the world of Cafu.

One way to do this is to approach Cafu from a map designers perspective, for example by exploring the Cafu World Editor CaWE. CaWE is not only a map editor, it also contains the GUI editor, a font conversion tool, a materials viewer and (soon) a model editor. CaWE can also act as a bridge towards scripting: map scripting, GUI scripting, materials scripting and vegetation scripting are powerful features in Cafu, and it doesn't stop there!

Programmers may instead prefer to dig into the source code right away – just pick your favorite piece of code, and start reading and hacking.

Or you just browse the files and folders in the Cafu directory, and start with whatever you feel most attracted to.

In any case, if you have questions or comments, or if you need help, write us a message at the support forums at any time!