| Home | Libraries | People | FAQ | More

## Using BJam

| Warning
Most probably, you are looking for Boost.Build manual or Boost.Build command-line syntax. This section documents only low-level options used by the Boost.Jam build engine, and does not mention any high-level syntax of Boost.Build

If target is provided on the command line, `bjam` builds target; otherwise `bjam` builds the target `all`.

    bjam ( -option [value] | target ) *

### Options

Options are either singular or have an accompanying value. When a value is allowed, or required, it can be either given as an argument following the option argument, or it can be given immediately after the option as part of the option argument. The allowed options are:

`-a`

  Build all targets anyway, even if they are up-to-date.

`-d n`

  Enable cummulative debugging levels from 1 to n. Values are:

  1. Show the actions taken for building targets, as they are executed (the default).
  2. Show "quiet" actions and display all action text, as they are executed.
  3. Show dependency analysis, and target/source timestamps/paths.
  4. Show arguments and timming of shell invocations.
  5. Show rule invocations and variable expansions.
  6. Show directory/header file/archive scans, and attempts at binding to targets.
  7. Show variable settings.
  8. Show variable fetches, variable expansions, and evaluation of '"if"' expressions.
  9. Show variable manipulation, scanner tokens, and memory usage.
  10. Show profile information for rules, both timing and memory.
  11. Show parsing progress of Jamfiles.
  12. Show graph of target dependencies.
  13. Show change target status (fate).

`-d +n`

  Enable debugging level n.

`-d 0`

  Turn off all debugging levels. Only errors are reported.

`-f Jambase`

  Read Jambase instead of using the built-in Jambase. Only one -f flag is permitted, but the Jambase may explicitly include other files. A Jambase name of "-" is allowed, in which case console input is read until it is closed, at which point the input is treated as the Jambase.

`-j n`

  Run up to n shell commands concurrently (UNIX and NT only). The default is 1.

`-l n`

  Limit actions to running for n number of seconds, after which they are stopped. Note: Windows only.

`-n`

  Don't actually execute the updating actions, but do everything else. This changes the debug level default to `-d 2`.

`-o file`

  Write the updating actions to the specified file instead of running them.

`-q`

  Quit quickly (as if an interrupt was received) as soon as any target fails.

`-s var=value`

  Set the variable var to value, overriding both internal variables and variables imported from the environment.

`-t target`

  Rebuild target and everything that depends on it, even if it is up-to-date.

`-- value`

  The option and value is ignored, but is available from the `$(ARGV)` variable.

`-v`

  Print the version of `bjam` and exit.

#### Command-line and Environment Variable Quoting

Classic Jam had an odd behavior with respect to command-line variable (`-s...`) and environment variable settings which made it impossible to define an arbitrary variable with spaces in the value. Boost Jam remedies that by treating all such settings as a single string if they are surrounded by double-quotes. Uses of this feature can look interesting, since shells require quotes to keep characters separated by whitespace from being treated as separate arguments:

    jam -sMSVCNT="\"\"C:\Program Files\Microsoft Visual C++\VC98\"\"" ...

The outer quote is for the shell. The middle quote is for Jam, to tell it to take everything within those quotes literally, and the inner quotes are for the shell again when paths are passed as arguments to build actions. Under NT, it looks a lot more sane to use environment variables before invoking jam when you have to do this sort of quoting:

    set MSVCNT=""C:\Program Files\Microsoft Visual C++\VC98\""

### Operation

BJam has four phases of operation: start-up, parsing, binding, and updating.

#### Start-up

Upon start-up, `bjam` imports environment variable settings into `bjam` variables. Environment variables are split at blanks with each word becoming an element in the variable's list of values. Environment variables whose names end in `PATH` are split at `$(SPLITPATH)` characters (e.g., `":"` for Unix).

To set a variable's value on the command line, overriding the variable's environment value, use the `-s` option. To see variable assignments made during bjam's execution, use the `-d+7` option.

The Boost.Build v2 initialization behavior has been implemented. This behavior only applies when the executable being invoked is called "`bjam`" or, for backward-compatibility, when the `BOOST_ROOT` variable is set.

1. We attempt to load "`boost-build.jam`" by searching from the current invocation directory up to the root of the file system. This file is expected to invoke the `boost-build` rule to indicate where the Boost.Build system files are, and to load them.
2. If `boost-build.jam` is not found we error and exit, giving brief instructions on possible errors. As a backward-compatibility measure for older versions of Boost.Build, when the `BOOST_ROOT` variable is set, we first search for `boost-build.jam` in `$(BOOST_ROOT)/tools/build` and `$(BOOST_BUILD_PATH)`. If found, it is loaded and initialization is complete.
3. The `boost-build` rule adds its (optional) argument to the front of `BOOST_BUILD_PATH`, and attempts to load `bootstrap.jam` from those directories. If a relative path is specified as an argument, it is treated as though it was relative to the `boost-build.jam` file.
4. If the `bootstrap.jam` file was not found, we print a likely error message and exit.

#### Parsing

In the parsing phase, `bjam` reads and parses the `Jambase` file, by default the built-in one. It is written in the jam language. The last action of the `Jambase` is to read (via the "include" rule) a user-provided file called "`Jamfile`".

Collectively, the purpose of the `Jambase` and the `Jamfile` is to name build targets and source files, construct the dependency graph among them, and associate build actions with targets. The `Jambase` defines boilerplate rules and variable assignments, and the `Jamfile` uses these to specify the actual relationship among the target and source files.

#### Binding

After parsing, `bjam` recursively descends the dependency graph and binds every file target with a location in the filesystem. If `bjam` detects a circular dependency in the graph, it issues a warning.

File target names are given as absolute or relative path names in the filesystem. If the path name is absolute, it is bound as is. If the path name is relative, it is normally bound as is, and thus relative to the current directory. This can be modified by the settings of the `$(SEARCH)` and `$(LOCATE)` variables, which enable jam to find and build targets spread across a directory tree. See SEARCH and LOCATE Variables below.

##### Update Determination

After binding each target, `bjam` determines whether the target needs updating, and if so marks the target for the updating phase. A target is normally so marked if it is missing, it is older than any of its sources, or any of its sources are marked for updating. This behavior can be modified by the application of special built-in rules, `ALWAYS`, `LEAVES`, `NOCARE`, `NOTFILE`, `NOUPDATE`, and `TEMPORARY`. See Modifying Binding below.

##### Header File Scanning

During the binding phase, `bjam` also performs header file scanning, where it looks inside source files for the implicit dependencies on other files caused by C's #include syntax. This is controlled by the special variables $(HDRSCAN) and $(HDRRULE). The result of the scan is formed into a rule invocation, with the scanned file as the target and the found included file names as the sources. Note that this is the only case where rules are invoked outside the parsing phase. See HDRSCAN and HDRRULE Variables below.

#### Updating

After binding, `bjam` again recursively descends the dependency graph, this time executing the update actions for each target marked for update during the binding phase. If a target's updating actions fail, then all other targets which depend on that target are skipped.

The `-j` flag instructs `bjam` to build more than one target at a time. If there are multiple actions on a single target, they are run sequentially.