This section will describe the basics of the Boost.Jam language—just enough for writing Jamfiles. For more information, please see the Boost.Jam documentation.

Boost.Jam has an interpreted, procedural language. On the lowest level, a Boost.Jam program consists of variables and rules (the Jam term for function). They are grouped in modules—there's one global module and a number of named modules. Besides that, a Boost.Jam program contains classes and class instances.

Syntantically, a Boost.Jam program consists of two kind of elements—keywords (which have a special meaning to Boost.Jam) and literals. Consider this code:

a = b ;

which assigns the value b to the variable a. Here, = and ; are keywords, while a and b are literals.

	Warning
	All syntax elements, even keywords, must be separated by spaces. For example, omitting the space character before ; will lead to a syntax error.

If you want to use a literal value that is the same as some keyword, the value can be quoted:

a = "=" ;

All variables in Boost.Jam have the same type—list of strings. To define a variable one assigns a value to it, like in the previous example. An undefined variable is the same as a variable with an empty value. Variables can be accessed with the $(variable) syntax. For example:

a = $(b) $(c) ;

Rules are defined by specifying the rule name, the parameter names, and the allowed size of the list value for each parameter.

rule example 
     (
         parameter1 : 
         parameter2 ? : 
         parameter3 + :
         parameter4 * 
     )
     {
        // body
     }

When this rule is called, the list passed as the first argument must have exactly one value. The list passed as the second argument can either have one value of be empty. The two remaining arguments can be arbitrary long, but the third argument may not be empty.

The overview of Boost.Jam language statements is given below:

helper 1 : 2 : 3 ; 
x = [ helper 1 : 2 : 3 ] ;

This code calls the named rule with the specified arguments. When the result of the call must be used inside some expression, you need to add brackets around the call, like shown on the second line.

if cond { statements } [ else { statements } ]

This is a regular if-statement. The condition is composed of:

for var in list { statements }

Executes statements for each element in list, setting the variable var to the element value.

while cond { statements }

Repeatedly execute statements while cond remains true upon entry.

return values ;
      

This statement should be used only inside a rule and assigns values to the return value of the rule.

	Warning
	The return statement does not exit the rule. For example: rule test ( ) { if 1 = 1 { return "reasonable" ; } return "strange" ; } will return strange, not reasonable.

import module ;
import module : rule ;

The first form imports the specified bjam module. All rules from that module are made available using the qualified name: module.rule. The second form imports the specified rules only, and they can be called using unqualified names.

Sometimes, you'd need to specify the actual command lines to be used when creating targets. In jam language, you use named actions to do this. For example:

actions create-file-from-another
{
    create-file-from-another $(<) $(>)
}

This specifies a named action called create-file-from-another. The text inside braces is the command to invoke. The $(<) variable will be expanded to list of generated files, and the $(>) variable will be expanded to the list of source files.

To flexibly adjust command line, you can define a rule with the same name as the action, and taking three parameters -- targets, sources and properties. For example:

rule create-file-from-another ( targets * : sources * : properties * )
{
   if <variant>debug in $(properties)
   {
       OPTIONS on $(targets) = --debug ;
   }
}
actions create-file-from-another
{
    create-file-from-another $(OPTIONS) $(<) $(>)
}

In this example, the rule checks if certain build property is specified. If so, it sets variable OPIONS that's used inside action. Note that the variable is set "on targets" -- the value will be only visible inside action, not globally. Were it set globally, using variable named OPTIONS in two unrelated actions would be impossible.

More details can be found in Jam reference, the section called “ Rules”

The Boost.Build configuration is specified in the file user-config.jam. You can edit the one in the top-level directory of Boost.Build installation or create a copy in your home directory and edit that. (See Table 25.2, “Search paths for configuration files” for the exact search paths.) The primary function of that file is to declare which compilers and other tools are available. The simplest syntax to configure a tool is:

using tool-name ;        

The using rule is given a name of tool, and will make that tool available to Boost.Build. For example, using gcc ; will make the gcc compiler available.

Since nothing but a tool name is specified, Boost.Build will pick some default settings. For example, it will use the gcc executable found in the PATH, or look in some known installation locations. In most cases, this strategy works automatically. In case you have several versions of a compiler, it's installed in some unusual location, or you need to tweak its configuration, you'll need to pass additional parameters to the using rule. The parameters to using can be different for each tool. You can obtain specific documentation for any tool's configuration parameters by invoking

bjam --help tool-name.init         

That said, for all the compiler toolsets Boost.Build supports out-of-the-box, the list of parameters to using is the same: toolset-name, version, invocation-command, and options.

The version parameter identifies the toolset version, in case you have several installed. It can have any form you like, but it's recommended that you use a numeric identifier like 7.1.

The invocation-command parameter is the command that must be executed to run the compiler. This parameter can usually be omitted if the compiler executable

For example:

using msvc : 7.1 ;
using gcc ;

If the compiler can be found in the PATH but only by a nonstandard name, you can just supply that name:

using gcc : : g++-3.2 ;

Otherwise, it might be necessary to supply the complete path to the compiler executable:

using msvc : : "Z:/Programs/Microsoft Visual Studio/vc98/bin/cl" ;

Some Boost.Build toolsets will use that path to take additional actions required before invoking the compiler, such as calling vendor-supplied scripts to set up its required environment variables. When compiler executables for C and C++ are different, path to the C++ compiler executable must be specified. The “invocation command” can be any command allowed by the operating system. For example:

using msvc : : echo Compiling && foo/bar/baz/cl ;

will work.

To configure several versions of a toolset, simply invoke the using rule multiple times:

using gcc : 3.3 ;
using gcc : 3.4 : g++-3.4 ;
using gcc : 3.2 : g++-3.2 ;

Note that in the first call to using, the compiler found in the PATH will be used, and there's no need to explicitly specify the command.

As shown above, both the version and invocation-command parameters are optional, but there's an important restriction: if you configure the same toolset more than once, you must pass the version parameter every time. For example, the following is not allowed:

using gcc ;
using gcc : 3.4 : g++-3.4 ;

because the first using call does not specify a version.

The options parameter is used to fine-tune the configuration. All of Boost.Build's standard compiler toolsets accept properties of the four builtin features cflags, cxxflags, compileflags and linkflags as options specifying flags that will be always passed to the corresponding tools. Values of the cflags feature are passed directly to the C compiler, values of the cxxflags feature are passed directly to the C++ compiler, and values of the compileflags feature are passed to both. For example, to configure a gcc toolset so that it always generates 64-bit code you could write:

using gcc : 3.4 : : <compileflags>-m64 <linkflags>-m64 ;

This section describes how invoke Boost.Build from the command line

To build all targets defined in Jamfile in the current directory with default properties, run:

bjam

To build specific targets, specify them on the command line:

bjam lib1 subproject//lib2 

To request a certain value for some property, add property=value to the command line:

bjam toolset=gcc variant=debug optimization=space

For often used features, like toolset and variant you can omit the feature name, so the above can be written as:

bjam optimization=space

Boost.Build recognizes the following command line options.

For complete specification of command line syntax, see the section called “Command line arguments”

A Main target is a user-defined named entity that can be built, for example an executable file. Declaring a main target is usually done using one of the main target rules described in the section called “Builtin rules”. The user can also declare custom main target rules as shown in the section called “Main target rules”.

Most main target rules in Boost.Build have the same common signature:

rule rule-name (
     main-target-name :
     sources + :
     requirements * :
     default-build * :
     usage-requirements * )

Some main target rules have a different list of parameters as explicitly stated in their documentation.

The actual requirements for a target are obtained by refining requirements of the project where a target is declared with the explicitly specified requirements. The same is true for usage-requirements. More details can be found in the section called “Property refinement”

obj test.release : test.cpp : <variant>release ;
obj test.debug : test.cpp : <variant>debug ;

exe a : a.cpp ;           # a.cpp is the only source file
exe b : [ glob *.cpp ] ;  # all .cpp files in this directory are sources 

lib helper : helper.cpp ;
exe a : a.cpp helper ;
# Since all project ids start with slash, ".." is directory name.
exe b : b.cpp ..//utils ;
exe c : c.cpp /boost/program_options//program_options ;

exe hello : hello.cpp : <include>/opt/boost <define>MY_DEBUG ;

lib util : util.cpp : <link>static ;
obj main : main.cpp : <optimization>off ;

lib network : network.cpp 
    : <link>shared:<define>NEWORK_LIB_SHARED
     <variant>release:<define>EXTRA_FAST
    ;

lib network : network.cpp
    : <toolset>gcc,<optimization>speed:<define>USE_INLINE_ASSEMBLER
    ;

lib network : network.cpp 
    : <conditional>@my-rule
    ;
rule my-rule ( properties * )
{
    local result ;
    if <toolset>gcc <optimization>speed in $(properties)
    {
        result += <define>USE_INLINE_ASSEMBLER ;
    }
    return $(result) ;
}  

exe main : main.cpp : -<define>UNNECESSARY_DEFINE ;

project test : requirements <threading;>multi ;
exe test1 : test1.cpp ;
exe test2 : test2.cpp : <threading;>single ;
exe test3 : test3.cpp : -<threading;>multi ;

exe hello : hello.cpp : : <threading>multi ;

lib demangler : dummy_demangler.cpp ;                      # alternative 1
lib demangler : demangler_gcc.cpp : <toolset>gcc ;   # alternative 2
lib demangler : demangler_msvc.cpp : <toolset>msvc ; # alternative 3

exe hello : hello.cpp 
    [ obj helpers : helpers.cpp : <optimization>off ] ;

explicit install_programs ;

As mentioned before, targets are grouped into projects, and each Jamfile is a separate project. Projects are useful because they allow us to group related targets together, define properties common to all those targets, and assign a symbolic name to the project that can be used in referring to its targets.

Projects are named using the project rule, which has the following syntax:

project id : attributes ;

Here, attributes is a sequence of rule arguments, each of which begins with an attribute-name and is followed by any number of build properties. The list of attribute names along with its handling is also shown in the table below. For example, it is possible to write:

project tennis 
    : requirements <threading>multi 
    : default-build release
    ;

The possible attributes are listed below.

Project id is a short way to denote a project, as opposed to the Jamfile's pathname. It is a hierarchical path, unrelated to filesystem, such as "boost/thread". Target references make use of project ids to specify a target.

Source location specifies the directory where sources for the project are located.

Project requirements are requirements that apply to all the targets in the projects as well as all subprojects.

Default build is the build request that should be used when no build request is specified explicitly.

The default values for those attributes are given in the table below.

Besides defining projects and main targets, Jamfiles often invoke various utility rules. For the full list of rules that can be directly used in Jamfile see the section called “Builtin rules”.

Each subproject inherits attributes, constants and rules from its parent project, which is defined by the nearest Jamfile in an ancestor directory above the subproject. The top-level project is declared in a file called Jamroot rather than Jamfile. When loading a project, Boost.Build looks for either Jamroot or Jamfile. They are handled identically, except that if the file is called Jamroot, the search for a parent project is not performed.

Even when building in a subproject directory, parent project files are always loaded before those of their subprojects, so that every definition made in a parent project is always available to its children. The loading order of any other projects is unspecified. Even if one project refers to another via the use-project or a target reference, no specific order should be assumed.

	Note
	Giving the root project the special name “Jamroot” ensures that Boost.Build won't misinterpret a directory above it as the project root just because the directory contains a Jamfile.

When you've described your targets, you want Boost.Build to run the right tools and create the needed targets. This section will describe two things: how you specify what to build, and how the main targets are actually constructed.

The most important thing to note is that in Boost.Build, unlike other build tools, the targets you declare do not correspond to specific files. What you declare in a Jamfile is more like a “metatarget.” Depending on the properties you specify on the command line, each metatarget will produce a set of real targets corresponding to the requested properties. It is quite possible that the same metatarget is built several times with different properties, producing different files.

	Tip
	This means that for Boost.Build, you cannot directly obtain a build variant from a Jamfile. There could be several variants requested by the user, and each target can be built with different properties.

bjam app1 lib1//lib1 toolset=gcc variant=debug optimization=full

bjam app1 lib1//lib1 gcc debug optimization=full

explicit hello_test ;