AgentXcpp uses SCons as an easy-to-use build system. Building agentXcpp is a one-step operation: simply invoke scons at the command line, and the library will be built. In addition, SCons provides operations to clean up the build directory, make parallel builds and others. Read the SCons documentation to learn more.

Installing the components of the agentXcpp library (header files, API documentation and the library itself) is as easy as invoking scons install. It is expected that agentXcpp is built by a package maintainer, not by an end user. Therefore, SCons is set up to install the library into the ./install-root/ directory by default, from where a package maintainer may pick it up for his package (e.g. a Redhat RPM package). The directories in which the files are installed are configurable for flexibility. Therefore, it is also possible to install agentXcpp right into a system.

This section explains how AgentXcpp is built and how SCons is used by agentXccp internally.

How to build AgentXcpp

Prerequisites

The following software is needed to build agentXcpp, simply use the versions which are easily available for your system:

Standard build environment (compiler, linker, etc.)
Doxygen, to build the documentation
SCons, to control the build process
The boost libraries

Building

To build agentXcpp, simply type

scons

You may add the -j switch to parallelize the build (e.g. -j2). The doxygen documentation will also be build and can then be found in doc/api/ and doc/internals/.

Installing

To install the library to the default location (which is 'install-root/' in the top-level directory), type

scons install

The install directories can be specified by various command-line switches. Example:

scons –prefix=/usr/local install

This will install all files in subdirectories of /usr/local/. Another example:

scons –libdir=/lib –docdir=/usr/share/doc/ –includedir=/usr/include install

This installs the shared object into /lib, the doxygen documentation into /usr/share/doc/ and the header files into /usr/include/. An added –prefix option would do nothing in this example, because the prefix is only used to calculate libdir, includedir and docdir. The following example will do the same as the previous one:

scons –prefix=/usr/ –libdir=/lib install

The build system will choose PREFIX/include (which is /usr/include in the example) as includedir and PREFIX/share/doc (which is /usr/share/doc in the example) as docdir. The default directories can be shown with scons -h.

Building the Unit Tests

The unit tests can be build with

scons testsuite

Cleaning

To clean the project directory, type:

scons -c

This doesn't clean any files installed with scons install.

How Scons works in agentXcpp

SCons is controlled via the SConstruct and SConscript files (the "Makefiles" of SCons). These files are in fact python scripts which call certain SCons functions. These SCons functions then build agentXcpp. The root directory contains an SConstruct file, and each subdirectory has a SConscript file to control the build process inside that directory.

The top-level SConstruct

The top-level SConstruct file defines the install prefix and the following directories:

libdir: where the library is installed
includedir: where the headers are installed
docdir: where the API documentation is installed

For each of them, a command-line option is added using the AddOption() function, providing a description (for the -h switch) and a default value. Then, the given options are read from the command line with GetOption() and added to the build environment. When a relative path is given, it is converted to an absolute path, because SCons functions are always invoked from the top-level directory, while the scons invocation may happen in a subsidiary directory. The following command-line options are provided:

–prefix=PREFIX
–libdir=LIBDIR
–includedir=INCLUDEDIR
–docdir=DOCDIR

Next, the git command describe is used to determine the revision from which agentXcpp is built. The revision is added to the build environment.

Finally, the subsidiary SConscript's are invoked, exporting the environment.

src/SConscript

The SConscript in src/ builds the library and provides the install target for it. Further, the library is defined as one of the default targets.

If g++ is detected, the SConscript also adds some compiler flags to get more warnings.

doc/SConscript

The SConscript in doc/ builds the doxygen documentations (API and internals). This SConscript is hackish, as scons doesn't know about doxygen, and there is currently no working Doxygen builder available for it.

First, the SConscript defines how to build the API documentation, using the SCons Command() function. As target, the generated 'api/html/index.html' file is used (although many other files are generated alongside), and 'api.doxyfile', the doxygen configuration file for the API docs, is defined as primary source for the build. The command for building begins with 'cd doc/', because the build is always started from the top-level directory, but Doxygen must be invoked in the doc directory in order to find its files. Also, this command includes shell code to feed the revision from the environment into doxygen's PROJECT_NUMBER variable to make it visible in the generated documentation.

Second, the dependencies are defined. If any dependency changes, the documentation must be rebuild. To keep things easy, all *.cpp and *.hpp files in src/ as well as all *.dox files are defined to be dependencies.

For completeness, SCons is told how to remove the built files using the Clean() function to provide proper scons -c operation and an install target for the API documentation is defined using Install().

These steps are then repeated for the internal documentation, except that no install target is defined for it. Finally, the API and internals documentations are defined as default targets.

A more appropriate implementation would scan the Doxygen configuration files for the input and output file patterns and define more accurate SCons dependencies. However, the current implementation will work until a good Doxygen builder becomes available.

unit_tests/SConscript

The SConscript in unit_tests/ builds the unit tests for agentXcpp. When using the g++ compiler, the -rpath ../src/ parameter is added so that the unit tests can find the agentXcpp shared library although it is not installed in a well-known place (like /usr/lib).

An install target is not provided, as unit tests are of course not installed on the target system. Also, the unit tests are not defined as a default target.