Chapter 2. Building FEAR From Scratch

Table of Contents

2.1. Dependencies
2.1.1. Boost
2.1.2. DocBook XSL Templates
2.2. Development Environment
2.2.1. Python
2.2.2. SCons
2.2.3. libxml2
2.2.4. Cheetah Template Engine
2.2.5. Xalan & FOP
2.2.6. Graphviz
2.3. Automated Build
2.3.1. Source Code
2.3.2. Build Variants
2.3.3. Documentation

FEAR in itself is very easy to build. The entire process is managed by a next-generation replacement for make called SCons, which automates things that most projects dream of. So, if you have your development environment set up, building FEAR is simply a matter of typing scons from the command prompt.

Setting up the development environment and downloading the required files is not an especially difficult process; it just takes a bit of time. However, a typical user of FEAR probably only needs to download Boost, as described next. Following the instructions in the rest of the chapter is only necessary if you wish to build FEAR from scratch — for example after checking out from CVS. Different files are required for different purposes, so it's most likely you will not need to install all the software or libraries listed below.

2.1. Dependencies

Before installing the tools, you need to download some essential data files that are required for various parts of the FEAR project.

2.1.1. Boost

[Note]Note

Required by: C++ framework

Boost is a set of free peer-reviewed portable C++ source libraries. These offer robust tools similar to the Standard Template Library that simplify the code tremendously. We already use the filesystem functions for portable directory scanning, as well as the safe_pointer and lexical_cast facilities.

Boost can be downloaded from Boost download page, which refers to a page on Sourceforge. Extract the files into the base fear directory, and rename the Boost directory to be just boost without any versions numbers, so it can be found by the C++ compiler. That directory will contain at least two subdirectories fear/boost/boost (containing headers files) and fear/boost/libs (storing the implementation).

[Caution]Caution

The remaining part of this chapter is intended for advanced FEAR developers only, namely experienced programmers that are comfortable with FEAR from the user's perspective. If you're just starting out with FEAR, you do not need to go through these steps. The release SDK is designed to be very easy to compile using standard tools installed by default. See the next chapter for more information.

2.1.2. DocBook XSL Templates

[Note]Note

Required by: HTML and PDF documentation

DocBook is the format used for all the documentation. It provides a standard way of creating large articles and manuals that are heavily interlinked. Specifically, XSL templates are required to convert the DocBook XML into readable HTML or PDF.

The files can be downloaded from the DocBook download page. Be sure to get the release with the XSL templates. Extract the files into the directory fear/formatting/docbook-xsl/. That directory will contain at least two important subdirectories html/ and fo/ (for PDF output).

2.2. Development Environment

This section explains how to install the tools necessary to build FEAR — which process the files you downloaded in the previous section and the files from FEAR's repository too (or the source distribution).

2.2.1. Python

[Note]Note

Required for: everything

Python is a modern scripting language with extreme power and flexibility. The build scripts are implemented in Python, so it is required to build everything. FEAR tools are implemented in python, and many other tools used are coded in python too — including the template engine used for generating code. The high-level AI routines can be scripted in python as well.

Python is very easy to install on Windows® systems, and usually already present on other systems (e.g. linux). You should download the latest release from the Python download page. Follow the instructions on the site to get python up and running.

2.2.2. SCons

[Note]Note

Required for: everything

SCons is a software construction tool capable of managing complex builds in a portable fashion. Essentially, the SCons API is used by build scripts to describe the software in a very intuitive fashion. The implementation in Python does lots of nifty tricks to resolve dependencies and build the various files. SCons is a truly awesome tool that offers power and flexibility second to none, and — most importantly — writing the build scripts has become a pleasure (unlike make and autoconf).

Within days of introducing SCons, it already replaced the various tools and Visual Studio files. Now it handles things such as generating source code from templates, compiling C++ files, building release packages, extracting and generating documentation, among many other things. It even creates the Visual Studio project files automatically, which saves a tremendous amount of time.

SCons is very easy to install, as it is created under the standard python distutils. There's even a windows installer for you. See the SCons download page for more information.

2.2.3. libxml2

[Note]Note

Required for: processing XML, building documentation

Only the command line tools xmllint and xsltproc are required by the build scripts. They are used to pre-process various files (e.g. resolving XIncludes) and generate some documents based on XSL Templates.

Any descent *nix installation will have these tools. In Windows®, using cygwin is the safest bet. Cygwin™ is a Linux-like environment for Windows®. If you don't want to install the full Cygwin™, the files you need can be found in this archive: xmltools.zip (taken from Cygwin's binary release). Just put these files somewhere in your path.

2.2.4. Cheetah Template Engine

[Note]Note

Required for: source code generation

Cheetah is a Python-powered template engine and code generator. It provides a language to express generic templates files in an intuitive fashion. Given custom data, the engine then fill the templates and generate the target file. It supports more advanced features such as template compilation and caching, but these are not required by FEAR.

Cheetah has successfully been introduced as a replacement for the overweight XSL Templates for code generation. Despite the power of XSL (and notably XPath expressions), code generation is better suited to Cheetah as templates are much easier to implement and manage. Cheetah also generates some pages of documentation based on information extracted from demos and modules.

Cheetah is well documented, and also very easy to install thanks to Python's disutils. See the Cheetah download page for further details.

2.2.5. Xalan & FOP

[Note]Note

Required for: building documentation

Xalan and FOP are Java based tools are necessary to generate the documentation from the DocBook format. They are not the best tools in the world for building documents, but they work well enough to generate the necessary PDF. (HTML documentation is better generated with the libxml2 tools discussed previously.) See the Installing an XSLT processor from DocBook XSL: The Complete Guide.

2.2.6. Graphviz

[Note]Note

Required for: generating graphs

Graphviz is a language used to express graphs and trees. Tools are provided to process .dot graphs into images. These are used to create intuitive graphics that describe the AI architecture and file dependencies, among others.

Locate the right package on the Graphviz download page and make sure dot is in your path.

2.3. Automated Build

SCons handles the entire build process. You could just type scons in the base FEAR directory, and all the necessary files would be build. Henceforth, calling SCons would only rebuild the files changed according to their dependencies.

Building specific parts of the FEAR project is done by using SCons build targets. These are passed as parameters to SCons.

2.3.1. Source Code

The FEAR source code can be built separately from the rest of the files. The code generation is needed for building the demos as well as each of the modules. All the source code is setup as a SCons alias. This means you can type the following at the command prompt to build every source file: scons source.

2.3.2. Build Variants

There are two types of builds: debug and release. Both variants can be built together by typing scons build. Each variant is stored in a subdirectory, either build/debug or build/release. These can also be built separately with the command scons build/variant.

Specific subparts of these variants can be built too, by using the subdirectories as command line parameters. These can be build/variant/modules, build/variant/demos, build/variant/framework, etc.

2.3.3. Documentation

To build the documentation, simply tell SCons that you want to build the directory where the documents are stored. Type scons documentation from the command prompt. If SCons is setup correctly, the following will appear on your screen:

> scons documentation

scons: Reading SConscript files ...

scons: done reading SConscript files.

scons: Building targets ...

docbook documentation\guide\Guide.html

docbook documentation\overview\Overview.html

[...]

scons: done building targets.

Specific documents can be built by specifying subdirectories to build, for example scons documentation/guide for example. It will take a long time to build the documentation files, so you'll have time to grab an orange.