|
The Power in your Hands |
The Jam build-tool provides a versatile, unified build process across many platforms including, build-configuration, cross-compilation, automated unit-tests, and concurrent execution of build steps. This is a a step-by-step introduction to the Jam-based build system, demonstrating how to build the Platinum framework on various platforms. The complete build and installation process consists of the following four steps:
The jam tool must always be invoked in the project root, where the files named 'Jamconfigure', 'Jamrules' and 'Jamfile' are located. A batch script is provided for Windows platforms and a POSIX shell-script for all other platforms, which builds the jam executable the first time it is excuted. Most examples will use the posix shell script when commands are shown. On Windows hosts you can use the script 'jam.bat' with exactly the same arguments.
Configuring the Build
The first thing that needs to be done is to configure the build. In this step, tests will be run to detect what features the target platform offers. Tests may fail if requirements are not met, in which case additional preparations must be taken like installing additional system headers or libraries. To configure the build with default build options, simply change to the project root directory and execute the appropriate build script with the 'configure' target. The command below configures the project on Windows when executed from a command shell:
Accordingly, on POSIX systems, a script named jam.sh can be used to configure the build:
Note, that after a checkout the jam script might need to be made executable with the chmod command (chmod +x ./jam.sh).
During configuration, all build options will be printed out. Most of them can be changed and you can repeat the configure step as often as you like, until the configuration matches your needs.
Debugging support and optimizations can be enabled when the build is configured. Use the command line option '–debug' to enable a debugable build and the option '–optimize' to enable optimized builds. Both options can be mixed, to build binaries with optimization and debugging support:
Normally, release builds only use the option '–optimize', while debug builds only use the option '–debug', respectively.
The other build options are set by setting jam variables on the command line or setting environment variables with the same names. When jam is invoked, all environment variables will be available as jam variables in the build scripts. A jam variable can be set with the command line option -s followed by a variable/valuepair separated by the equal sign (-sVARIABLE=VALUE). For example, if you do not like the flags used for optimization you can set the OPTIM variable. The following example sets the compiler flags used for optimization to -O3:
If multiple toolsets are installed on the build host, one can be selected by setting the TOOLSET build option. Possible toolsets are vc8, vc9, vc10, gcc, qcc, xlc and sunpro. The default toolset on a Unix host may not be gcc, but the compiler/linker of the respective vendor. For example, the default toolset on AIX is the XLC compiler and the default toolset on Solaris is the Sun Workshop compiler. The GNU compiler can be used instead of the systems default compiler by setting the option TOOLSET to 'gcc' explicitly:
On windows systems you can also select a specific visual studio compiler if more than one version of visual studio is installed. The following example selects the Visual Studio 2008 compiler:
The build options TARGET_OS and TARGET_OSPLAT need to be set for cross compiling. Possible values for the target operating system are nt, linux, macosx, wince or qnxnto. Possible values for the target CPU platform are x86, ppc, arm, mips, sh4 or sparc.
Windows CE targets need to be cross compiled under Windows hosts. Therefore the TARGET_OS and TARGET_OSPLAT variables need to be set when the build is configured. The following command builds for windows CE on ARM CPUs:
QNX targets can be cross compiled on both, QNX and windows build hosts. In the first case, only the TARGET_OSPLAT option needs to be set, in the latter case the TARGET_OS also needs to be set. The following command can be used on a windows host to build for QNX on PowerPC CPUs:
Building with Jam
All artefacts that are created during the build process are refered to as 'targets'. A target can be a binary file, such as a executable, or a so-called pseudo-target, which usually references other targets. All targets form a dependency tree. If jam is invoked to build a target, all dependencies will be resolved automatically and be built first. If jam is invoked without any further options, all targets will be built:
To build a specific target of the project simply invoke jam with a target name. The following command will build the target libPt.so and all its dependencies:
To completely rebuild a target and its dependencies, the command line parameter -a can be passed to jam. The option -a can be used with or without a specific target. Thus the following command will rebuild the whole project:
The pseudo-target 'clean' plays a special role in the jam build system. All artefacts that are created during the build process are dependents of the 'clean' peseudo-target. When jam is invoked with the target clean, all artefacts will be deleted if they exist. Therefore the following command will remove all artefacts that were created by a build with default options:
Finally, two command line options can make the build more convenient. You can use the command line option '-jN' to specify how many actions should be executed in parallel, where N is the maximum number of parallel actions (e.g. -j2 to use up to two CPUs). The command line option '-q' will stop the build when the first error is encountered.
Build Verification
The pseudo-target 'test' causes jam to build all unit-tests and execute them. This will not work for cross compiling for obvious reasons. If a unit-test fails the whole build will be reported to have failed. The target test is not a dependent of the target all, so unit-tests are not built and executed by default. The following example builds the whole projects and executes the unit-test.
Installation
Installation of the built artifacts is performed by the means of a pseudo-target 'install'. With default settings, no real installation will be performed, but the relevant files will only copied to a directory named 'deploy'. If you dare to copy files to your system directories you can set the INSTALL_DIR (root directory of the installation), INSTALL_BINDIR (directory to install programs), INSTALL_INCLUDEDIR (directory to install header files and INSTALL_LIBDIR (directroy to install libraries). You can set these at configuration time or just before installation. The following command will install the files in the '/opt' directory:
This means that a directory named Pt will be created with three subdirectories named 'include', 'lib' and 'bin'. As you may have guessed, INSTALL_DIR is used as the base for the other variables INSTALL_BINDIR, INSTALL_INCLUDEDIR and INSTALL_LIBDIR. Alternatively, you can set the three latter variables to separate directories to have full control of the installation.