## Chapter 4. Overview

This section will provide the information necessary to create your own projects using Boost.Build. The information provided here is relatively high-level, and Chapter 7, Detailed reference as well as the on-line help system must be used to obtain low-level documentation (see `--help`).

Boost.Build actually consists of two parts - Boost.Jam, a build engine with its own interpreted language, and Boost.Build itself, implemented in Boost.Jam's language. The chain of events when you type bjam on the command line is:

1. Boost.Jam tries to find Boost.Build and loads the top-level module. The exact process is described in the section called “Initialization”

2. The top-level module loads user-defined configuration files, `user-config.jam` and `site-config.jam`, which define available toolsets.

3. The Jamfile in the current directory is read. That in turn might cause reading of further Jamfiles. As a result, a tree of projects is created, with targets inside projects.

4. Finally, using the build request specified on the command line, Boost.Build decides which targets should be built, and how. That information is passed back to Boost.Jam, which takes care of actually running commands.

So, to be able to successfully use Boost.Build, you need to know only four things:

- How to configure Boost.Build

- How to write declares targets in Jamfiles

- How the build process works

- Some Basics about the Boost.Jam language. See the section called “Boost.Jam Language”.

## Boost.Jam Language

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:

- Literals (true if at least one string is not empty)

- Comparisons: `a `operator` b` where `operator` is one of `=`, `!=`, `<`, `>`, `<=`, `>=`. The comparison is done pairwise between each string in the left and the right arguments.

- Logical operations: `! a`, `a && b`, `a || b`

- Grouping: `( cond )`

    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”