Boost.Jam

Introduction
Features
Contents
Installing

Introduction

Boost.Jam (BJam) is a build tool based on FTJam, which in turn is based on Perforce Jam. It contains significant improvements made to facilitate its use in the Boost Build System, but should be backward compatible with Perforce Jam.

This is version 3.1.3 of BJam and is based on version 2.4 of Jam/MR:

/+\
+\  Copyright 1993-2002 Christopher Seiwald and Perforce Software, Inc.
\+/
This is Release 2.4 of Jam/MR, a make-like program.
License is hereby granted to use this software and distribute it
freely, as long as this copyright notice is retained and modifications
are clearly marked.
ALL WARRANTIES ARE HEREBY DISCLAIMED.

Features

Jam is a make(1) replacement that makes building simple things simple and building complicated things manageable.

Jam's language is expressive, making Jamfiles (c.f. Makefiles) compact. Here's a sample:

Main smail : main.c map.c resolve.c deliver.c
     misc.c parser.y alias.c pw.c headers.c
     scanner.l getpath.c str.c ;

This builds "smail" from a dozen source files. Jam handles header file dependencies automatically and on-the-fly.

Jam is very portable: it runs on UNIX, VMS, Mac, and NT. Most Jamfiles themselves are portable, like the sample above.

Jam is unintrusive: it is small, it has negligible CPU overhead, and it doesn't create any of its own funny files (c.f. Odin, nmake, SunOS make).

Jam can build large projects spread across many directories in one pass, without recursing, tracking the relationships among all files. Jam can do this with multiple, concurrent processes.

Jam isn't under the blinkin GNU copyright, so you can incorporate it into commercial products.

Jam.html	Jam and language reference.
Jambase.html	Reference for the Jambase boilerplate file.
Jamfile.html	Easy reading on creating a Jamfile and using jam.
RELNOTES	Release 2.4 release notes.
Porting	Notes on porting jam to wildcat platforms.

Installing

Installing BJam after building it is simply a matter of copying the generated executables someplace in your PATH. For building the executables there are a set of build bootstrap scripts to accomodate particular environments. The scripts take one optional argument, the name of the toolset to build with. When the toolset is not given an attempt is made to detect an available toolset and use that. The build scripts accept these areguments:

<build script name> [toolset]

Running the scripts without arguments will give you the best chance of success. On Windows platforms from a command console do:

cd <jam source location>
.\build.bat

On Unix type platforms do:

cd <jam source location>
sh ./build.sh

If the scripts fail to detect an appropriate toolset to build with your particular toolset may not be auto-detectable. In that case, you can specify the toolset as the first argument, this assumes that the toolset is readily available in the PATH. The supported toolsets, and wether they are auto-detected, are:

Script	Platforms	Toolsets	Detection
`build.bat`	Windows NT, 2000, and XP	`borland`, Borland C++Builder (BCC 5.5)	* Common install location: `"C:\Borland\BCC55"` * `BCC32.EXE` in `PATH`
		`metrowerks`, MetroWerks CodeWarrior C/C++ 7.x, 8.x	* `CWFolder` variable configured * `MWCC.EXE` in `PATH`
		msvc, Microsoft Visual C++ 6.x	* Common install locations: `"C:\Program Files\Microsoft Visual Studio"`, `"C:\Program Files\Microsoft Visual C++"` * `CL.EXE` in `PATH`
		vc7, Microsoft Visual C++ 7.x	* Common install location: `"C:\Program Files\Microsoft Visual Studio .NET"`
`build.sh`	Unix, Linux, Cygwin, etc.	como, Comeau.Computing C/C++	* `como` in `PATH`
		gcc, GNU GCC	* `gcc` in `PATH`
		intel-linux, Intel C++ for Linux	* Common install location: `"/opt/intel/compiler50"` * `icc` in `PATH`
		kcc, Intel KAI C++	* `KCC` in `PATH`
		vacpp, IBM VisualAge C++	* `xlc` in `PATH`
	MacOS X	darwin, Apple MacOS X GCC	* `uname` is `"Darwin"`

The built executables are placed in a subdirectory specific to your platform. For example, in Linux running on an Intel x86 compatible chip, the executables are placed in: "bin.linuxx86". There are two executables generated: jam[.exe], and bjam[.exe], both are the same binary but with different names. The "jam" invocation is used for compatability with the Perforce Jam/MR functionality, whereas "bjam" is used for the extended Boost.Build functionality.

The build scripts support additional invocation arguments for use by developers of Boost.Jam. The extra arguments come after the toolset, and can take the form of "--options" or targets for the build.jam script:

<build script name> [toolset] [--options* [targets]*]

There is current only one available option, "--debug", which builds debugging versions of the executable. When built they are placed in their own directory "bin.<platform>.debug".

Currently there are two targets supported: dist, and clean. Respectively they: generate packages (compressed archives) as appropriate for distribution in the platform, or remove all the built executables and objects.

Revised 12 November, 2002

Boost.Jam

Introduction

Features

Contents

Installing