Overview

Accessing the C module for the first time will auto-launch a reasonable default toolchain. On Windows, for example, the default toolchain is win64/release. You can override the default toolchain by passing the C.TOOLCHAIN=platform/config command-line option to Jam. For instance, to build win64 debug for the C toolchain, you would specify C.TOOLCHAIN=win64/debug on the Jam command-line.

jam C.TOOLCHAIN=win64/debug

Replacing one of the C.TOOLCHAIN entries with a - (dash) will insert a reasonable default.

rem On Windows, use win64/debug.
jam C.TOOLCHAIN=-/debug
 
rem On Windows, use win32/release.
jam C.TOOLCHAIN=win32/-
 
rem On Windows, use win64/release, the same as running jam without a C.TOOLCHAIN option.
jam C.TOOLCHAIN=-/-

Additionally, as a backward compatibility feature, passing PLATFORM=abc and CONFIG=defg will result in a toolchain called abc/defg.

jam PLATFORM=abc CONFIG=defg
 
# This is the same as:
#
#     jam C.TOOLCHAIN=abc/defg

rule C.Toolchain TOOLCHAIN_SPEC allows the current toolchain to be changed. The format of TOOLCHAIN_SPEC (win32/release) is slash-separated and the format is determined by the underlying Jamfiles that are executed. Additionally, at the end of the TOOLCHAIN_SPEC, you can add key=value options by preceding the option with an @ sign. See samples/toolchains-helloworld/Jamfile.jam for usages.

C.Toolchain win32/release ;
C.Toolchain win32/release@C.COMPILER=mingw
C.Toolchain win32@C.COMPILER=gcc@C.CONFIG=debug

Usage

Saving and restoring the current toolchain is performed by storing off $(C.ACTIVE_TOOLCHAIN_SPEC).

# Save the active toolchain.
local saveActiveToolchainSpec = $(C.ACTIVE_TOOLCHAIN_SPEC) ;
 
# Change to another toolchain.
C.Toolchain whatever/toolchain ;
 
# Do some work with the toolchain here.
...
 
# All done. Restore the previous one.
C.Toolchain $(saveActiveToolchainSpec) ;

Example

For the following Jamfile.jam, a single invocation of Jam will build helloworld for:

The default toolchain
win32/release for the default compiler
win32/release for Visual C++ 2010
win32/release for Visual C++ 2012
win32/release for Visual C++ 2013
win32/release for MinGW
win32/debug for Visual C++ 2013

# Build helloworld with the default toolchain or passed-in command-line toolchain.
C.Application helloworld : main.c ;
 
# Build helloworld for C.PLATFORM=win32 and C.CONFIG=release for the default compiler.
C.Toolchain win32@C.CONFIG=release ;
C.Application helloworld : main.c ;
 
# Build helloworld for C.PLATFORM=win32 and C.CONFIG=release for VS2010.
C.Toolchain win32/release@C.COMPILER=vs2010 ;
C.Application helloworld : main.c ;
 
# Build helloworld for C.PLATFORM=win32 and C.CONFIG=release for VS2012.
C.Toolchain win32/release@C.COMPILER=vs2012 ;
C.Application helloworld : main.c ;
 
# Build helloworld for C.PLATFORM=win32 and C.CONFIG=release for VS2013.
C.Toolchain win32/release@C.COMPILER=vs2013 ;
C.Application helloworld : main.c ;
 
# Build helloworld for C.PLATFORM=win32 and C.CONFIG=release for MinGW.
C.Toolchain win32/release@C.COMPILER=mingw ;
C.Application helloworld : main.c ;
 
# Build helloworld for C.PLATFORM=win32 and C.CONFIG=debug for VS2013.
C.Toolchain win32/debug@C.COMPILER=vs2013 ;
C.Application helloworld : main.c ;
 
# Build helloworld for C.PLATFORM=win32 and C.CONFIG=debug for VS2013. This will be a no-op.
C.Toolchain win32@C.COMPILER=vs2013@C.CONFIG=debug ;
C.Application helloworld : main.c ;

Technical Details

The order of toolchain file loads is as follows when C.Toolchain win32/release is called:

The C.Toolchain rule is requested. The rule is found missing, so Jam loads bin/modules/c.jam to find it.
Jam then attempts to execute an unloaded rule called C.Toolchain.win32.release. The FindMissingRule support kicks in and ends up executing rule C.Toolchain.win32.* from bin/modules/c/toolchain/win32.jam.
Toolchain spec keys are added for C.PLATFORM/PLATFORM and C.CONFIG/CONFIG. For the toolchain win32/release, the following assignments are made: C.PLATFORM=win32, PLATFORM=win32, C.CONFIG=release, CONFIG=release
Within C.Toolchain.win32.*, auto detection of the compiler is performed. First, the latest Visual Studio version is detected. Failing that, TDM/GCC is detected then MinGW. Assuming Visual Studio detection, C.Toolchain.vc.win32.Detect from bin/modules/c/toolchain/vc/win32.jam is called.
Next, C.Toolchain.vc.win32-release from bin/modules/c/toolchain/vc/win32-release.jam is called to set up some optimization flags and #defines.

samples/fakeps3/jam/c/toolchain/fakeps3.jam shows an example of handling multiple configurations and architectures within a single file.

jam C.TOOLCHAIN=fakeps3/debug/ppu

C.ToolchainSpecKeys is used to break down the basic form of C.TOOLCHAIN=whatever/whatever. It parses the / separators to assign the same value to multiple keys. For instance, C.ToolchainSpecKeys C.PLATFORM/PLATFORM assigns the value to both C.PLATFORM and PLATFORM.

C.ToolchainSpecKeys C.PLATFORM/PLATFORM C.CONFIG/CONFIG ;

Settings are now added to $(C.COMPILER_SUITE_SYMBOL) with the rule names that should be called. More than one rule name can be attached per setting; the listed rules will executed in order. The names of the settings are as follows:

C.ApplicationFromObjects_CleanIntermediates
C.ApplicationFromObjects_LinkFlags
C.ApplicationFromObjects_PostBuild
C.ApplicationFromObjects_Setup
C.C++Exceptions
C.LibraryFromObjects_LibFlags
C.LinkPrebuiltLibraries
C.MultiCppCompile_PreCompile
C.MultiCppCompile_PchDeps
C.MultiCppCompile_PostCompile
C.MultiCppCompile_SetupFlags
C.RuntimeTypeHelper
C.SharedLibraryFromObjects_CleanIntermediates
C.SharedLibraryFromObjects_ExportLib
C.SharedLibraryFromObjects_LinkFlags
C.SharedLibraryFromObjects_PostBuild
C.SharedLibraryFromObjects_RegServer
C.SharedLibraryFromObjects_UnRegServer.