AgentXcpp uses SCons as an easy-to-use build system. Therefore, 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 more.

How to build AgentXcpp

A short introduction of the prerequisites and the build process of agentXcpp is given in Building and Installing AgentXcpp. If you want to hack on agentXcpp itself, some more commands become handy. You can easily (re)build agentXcpp with

# While in top-level directory: Build agentXcpp
scons

SCons keeps track of all dependencies, for example included headers, and rebuilds only the parts that it really need to. It even might skip the linker step if compilation generated unchanged object files. To build only part of the project, use can use

# While in src/: Build only the library
scons -u
# While in doc/: Build only the documentation
scons -u

The -u parameter tells SCons to walk the directory tree up to find the SConsctruct file. Another useful command is

# Remove all files created by SCons
scons -c

This removes the files which were produced by calling scons. Files installed with scons install are left alone. Note that this cleaning command is rarely needed. Unlike autotools or the like, SCons doesn't get stuck if dependencies change.

How Scons works in agentXcpp

AgentXcpp includes two SCons tools located in site_scons/site_tools/: qt4 and doxygen. Both tools were not created by the agentXcpp developer and both have other license terms. However, when distributing agentXcpp under its license terms, these tools can safely distributed along, as long as they are changed under their own terms.

The root directory contains a 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 a number of command-line options using the AddOption() function, providing a description (for the -h switch) and a default value. These options become available in addition to the standard SCons options and can be seen with scons -h. Then, the given options are read from the command line with GetOption() and the proper actions are taken.

The following options are currently provided:

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

which define the following SCons environment variables:

libdir: where the library gets installed
includedir: where the headers get installed
docdir: where the API documentation gets installed
prefix: used to build up default values for the above options

When a relative path is given for any of these options, 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 subdirectory.

After processing the command line, the SConscript invokes getVersion() from the getversion.py script to determine the version from which agentXcpp is built. The version string is added as environment variable 'revision'.

Next, the SConscript checks for some tools and provides useful error messages if something is missing.

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

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 produce more warnings.

doc/SConscript

The SConscript in doc/ builds the doxygen documentations (API and internals). It uses the SCons doxygen tool to do so. This tool is included in the agentXcpp source repository and was extended to support the DOXYPROJECTNUMBER environment variable, which appends the PROJECT_NUMBER option to the doxyfile before running doxygen. This way, the version information can be built into the documentation.

For API documentation, the SConscript defines an install target. The internals documentation is not intended to be installed in a system, because the audience are developers who like to work on the agentXcpp source code.

Further, clean targets are defined, and default targets are specified so that the documentations are built by default.