The C module provides rules to build C, C++, Objective C, and Objective C++ applications, shared libraries, and static libraries.

When first loaded, it attempts to detect the compiler on the machine. On Windows, it can successfully detect and run Visual Studio 2015/2013/2012/2010/2008/2005/2003 and Visual C++ 6. MinGW can also be specified. On other OSes, it attempts to detect GCC.

Support for more than one toolchain used during the same Jam execution is provided via the C Module Multiple Toolchain Support.

List of Rules

Rules

rule C.ActiveTarget TARGET

Changes the active target to TARGET. All rules taking an optional TARGET parameter will default to the active target if empty.

Parameters

TARGET The target to become active.

Returns: Returns the newly activated target.

C.ActiveTarget MyApplication ;

rule C.AddBuildExtensions TYPE : EXTS : RULE : SUFOBJ : ADD_TO_EXTENSIONS : ADD_TO_LINK

Makes a new C/C++ source extensions available to the compiler. This rule requires some additional setup, described below.

TODO: Finish me.

TYPE identifies a category of files and is a short identifier, usually all caps. It is used to access compiler flags variables during a file's compilation. If TYPE were specified as CC, then the compiler flags in the variables called preCCFLAGS, CCFLAGS, SUBDIRCCFLAGS, and PCHCCFLAGS would be used.

rule C.AddFlags TARGET : FLAGS

For the given project TARGET, add the compilation FLAGS for the current toolchain.

Parameters

TARGET	The target to add the `FLAGS` to. `TARGET` is optional if rule ActiveTarget TARGET has been specified. If `TARGET` is `*`, the flags are made available globally.
FLAGS	The list of flags to add.

C.AddFlags : -g ;

rule C.Application TARGET : SOURCES [ : OPTIONS ]

Compiles SOURCES and links them into TARGET. Platform specific .o files or, on Visual C++ compilers, .res files are passed straight through to the linker. Any file excluded from the build via rule C.ExcludeFromBuild TARGET : SOURCES is ignored.

Parameters

TARGET	The target to link `SOURCES` into. The target name is given without extension. A platform specific extension will be generated, often reflecting a configuration type. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SOURCES	The list of `.cpp`, `.cxx`, and `.c` (and possibly others) files to link into the application. Object and compiled Windows resource files may also be passed with this list.
OPTIONS	The following options are available. All options are optional.

windows - Forces a GUI application. On Windows, the application must have a WinMain function. For Visual C++, the executable is linked with /SUBSYSTEM:WINDOWS.

console (default) - Builds a console application. For Visual C++, the executable is linked with /SUBSYSTEM:CONSOLE.

Returns: Returns the list of link targets, sometimes more than one, that will be built by the Jam.

C.Application helloworld : helloworld.cpp ;

rule C.BatchCompileGroupSize TARGET [ : SIZE ]

For the given project TARGET, only allow SIZE files to be batch compiled in a given compiler execution.

Parameters

TARGET	The target to assign the `SIZE` information to. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SIZE	(optional) The maximum number of files to allow to compile on a given compiler execution. If not specified, there is no limit to the number of batch compiled files.

# wxLua takes so long to build that we don't properly take advantage of
# multithreading without splitting up the build some.
C.BatchCompileGroupSize wxLua : 5 ;

rule C.CFlags TARGET : FLAGS

For the given project TARGET, assign the FLAGS to the appropriate configuration and platform.

Parameters

TARGET	The target to assign the `FLAGS` to. `TARGET` is optional if rule ActiveTarget TARGET has been specified. If `TARGET` is `*`, the flags are made available globally.
FLAGS	The list of flags to apply.

# Assign /clr:oldsyntax to all C files in managedapp across all
# configurations and platforms.
C.CFlags managedapp : /clr:oldsyntax ;
 
# Assign /clr:oldsyntax to all C files in managedapp for the debug
# configuration and all platforms.
C.CFlags managedapp : /clr:oldsyntax : debug ;
 
# Assign /clr:oldsyntax to all C files in managedapp for the debug
# configuration and win32 platform.
C.CFlags managedapp : /clr:oldsyntax : debug : win32 ;

rule C.Clean TARGET : FILES

Add FILES to the clean target for TARGET.

Parameters

TARGET	The target to add `FILES` to for cleaning. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
FILES	The files to clean.

C.Clean : $(generatedheader) ;

rule C.C++Exceptions TARGET : TYPE

For the given project TARGET, turn on/off C++ exception support within the current toolchain.

Parameters

TARGET	The target to assign the `FLAGS` to. `TARGET` is optional if rule ActiveTarget TARGET has been specified. If `TARGET` is `*`, the flags are made available globally.
TYPE	`true` to turn on exceptions, `false` (default) to turn off exceptions.

# Turn on exceptions in the target mycppapp.
C.C++Exceptions mycppapp : true ;
 
# Turn off exceptions in the target mycppapp for all configs.
C.C++Exceptions mycppapp : false ;

rule C.C++Flags TARGET : FLAGS

For the given project TARGET, assign the C++ FLAGS for the current toolchain.

Parameters

TARGET	The target to assign the `FLAGS` to. `TARGET` is optional if rule ActiveTarget TARGET has been specified. If `TARGET` is `*`, the flags are made available globally.
FLAGS	The list of flags to apply.

# Assign /clr:oldsyntax to all C++ files in managedapp.

C.C++Flags managedapp : /clr:oldsyntax ;

rule C.CompileOptions OPTIONS

Sets options that affect how the compiler builds.

Parameters

OPTIONS The following options are available.

outputastree - Set this if you want object files to be put in subdirectories matching the directory hierarchy of the source files. .. directory entries are changed to __ so the object files stay within the build hierarchy. The default is to put all object files in one flat directory per project.

C.CompileOptions outputastree ;

rule C.ConfigureFile TARGET : DESTINATION : SOURCE : OPTIONS

For the given TARGET, run the file specified through SOURCE through a CMake-like configure mechanism and output the file to DESTINATION.

Parameters

TARGET	The target to do the processing within. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
DESTINATION	The destination filename to output the configured file to. The default output directory is `$(LOCATE_SOURCE)`.
SOURCE	The source filename to configure. The default search directory is `$(SEARCH_SOURCE)`.
OPTIONS	Either `addinclude` to add the `DESTINATION` `$(LOCATE)` directory to the private include paths or `addpublicinclude` to add it to the public include paths for inheritance.

Remarks: An example is found at tests/configurefile/.

C.ConfigureFile test : config.h : config.h.in : addinclude ;

rule C.DefFile TARGET : SOURCES

When linking the given TARGET, link the .def file(s) specified in SOURCES.

Note: At this time, the def file only affects Visual C++ applications.

Parameters

TARGET	The target to link the def file to. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SOURCES	One or more .def files. .def files are searched for in .

# Build WorkspaceWhiz.def as part of the WorkspaceWhiz target.

C.DefFile WorkspaceWhiz : WorkspaceWhiz.def ;

rule C.Defines TARGET : DEFINES [ : OPTIONS ]

Assign the DEFINES to the given project TARGET.

Parameters

TARGET	The target to assign the `DEFINES` to. `TARGET` is optional if rule ActiveTarget TARGET has been specified. If `TARGET` is `*`, the defines are made available globally.
DEFINES	The list of defines to apply.
OPTIONS	If `public` is specified, the defines specified by `DEFINES` are made available to a project using `C.Inherits`.

# Make #defines available for ABC and DEF=5 in someproject for all
# configurations and all platforms.
C.Defines someproject : ABC DEF=5 ;
 
# For the win32 platform, add a WIN32 define globally.
if $(C.PLATFORM) = win32 {
    C.Defines * : WIN32 ;
}
 
# Quote a #define, keeping the quotes for compilation:
C.Defines luacom : LUA5 "LUACOM_DLL=\\\"luacom.dll\\\"" ;
 
# Add GHI to myproject and make it available to C.Inherits users.
C.Defines someproject : GHI : public ;

rule C.ExcludeFromBuild TARGET : SOURCES

For the given project TARGET, exclude the SOURCES from the build. When using

jam --workspace

for project generation, sources must be excluded and not simply removed from the list. Otherwise, they will not show in the generated projects.

Parameters

TARGET	The target to exclude the `SOURCES` from. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SOURCES	The list of sources to exclude.

if $(PLATFORM) != xbox
{
    C.ExcludeFromBuild myproject : $(XBOX_SRCS) ;
}

rule C.ExcludeFromWorkspace TARGET : SOURCES

For the given project TARGET, exclude the SOURCES from the projects generated by

jam --workspace

.

Parameters

TARGET	The target to exclude the `SOURCES` from. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SOURCES	The list of sources to exclude.

if $(PLATFORM) != xbox
{
    C.ExcludeFromWorkspace myproject : $(XBOX_SRCS) ;
}

rule C.ExcludePatternsFromBuild TARGET : PATTERNS

For the given project TARGET, exclude the files matching regular express PATTERNS from the build. When using

jam --workspace

for project generation, sources must be excluded and not simply removed from the list. Otherwise, they will not show in the generated projects.

Parameters

TARGET	The target to exclude the files matching `PATTERNS` from. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
PATTERNS	The list of patterns used to match files to exclude from the project.

# Exclude files ending with _opengl. Effectively, this is a '*_opengl.*' exclusion.
C.ExcludePatternsFromBuild :
    .*_opengl\\..*$
;

rule C.Flags TYPE : TARGET : FLAGS

Assign the compilation FLAGS to the project TARGET. TYPE can be any known source compilation type, such as CC for C-style files, C++ for C++-style files, and on certain compilers, M for Objective C files, or MM for Objective C++ files.

Parameters

TYPE	A source compilation type added through C.AddBuildExtensions. If more than one is specified, the flags are applied to all types.
TARGET	The target to assign the `FLAGS` to. `TARGET` is optional if rule ActiveTarget TARGET has been specified. If `TARGET` is `*`, the flags are made available globally.
FLAGS	The list of flags to apply.

if $(C.PLATFORM) = macosx32  &&  $(C.CONFIG) = debug {
    C.Flags CC  : * : -g -O0 -arch i386 ;
    C.Flags C++ : * : -g -O0 -arch i386 ;
}

rule C.ForceFileType TARGET : SOURCES : FILE_TYPE

Force the FILE_TYPE of the provided SOURCES attached to TARGET.

Parameters

TARGET	The target to use when forcing the file type of `SOURCES`. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SOURCES	The list of files to affect the compilation type of.
FILE_TYPE	A known extension, such as `.c`, `.cpp`, `.m`, or `.mm`, to force the `SOURCES` to be interpreted as.

C.ForceFileType : Application.cpp : .mm ;

rule C.ForceInclude TARGET : INCLUDES

For the given project TARGET, assign the INCLUDES for the current toolchain causing that project's compilation to force the inclusion of the header before anything else.

Parameters

TARGET	The target to assign the `INCLUDES` to. `TARGET` is optional if rule ActiveTarget TARGET has been specified. If `TARGET` is `*`, the defines are made available globally.
INCLUDES	The list of header files to force include.

# Automatically #include myheader.h for all source files listed in myproject.

C.ForceInclude myproject : myheader.h ;

rule C.ForcePublic TARGET

Force the rule C.Inherits TARGET : INHERITS_TARGETS [ : OPTIONS ] public inheritance pattern for TARGET. This will treat TARGET as if one of the flag setting functions, such as rule C.Defines TARGET : DEFINES [ : OPTIONS ] or rule C.IncludeDirectories TARGET : INCLUDEPATHS [ : OPTIONS ], had been called with public OPTIONS.

C.ForcePublic is usually used in situations where rule C.Inherits TARGET : INHERITS_TARGETS [ : OPTIONS ] is called with TARGET to inherit from, but TARGET has no public defines or include directories or other flags. C.Inherits will abort as a precautionary measure assuming that Jam has not yet defined TARGET yet.

Parameters

TARGET The target to force to public.

C.ForcePublic MyLibrary ;

rule C.GetArchitecture TOOLCHAIN_SPEC

Retrieves the C.ARCHITECTURE assigned to the specified toolchain.

Parameters

TOOLCHAIN_SPEC A toolchain spec. Defaults to the current toolchain.

Returns: Returns the toolchain's architecture.

Echo Architecture - [ C.GetArchitecture ] ;

rule C.GetLinkTargets TARGET : TOOLCHAIN_SPEC

The rule C.Application TARGET : SOURCES [ : OPTIONS ] and rule C.Library TARGET : SOURCES [ : OPTIONS ] rules return the target name of the executable or library being built. The properly gristed target name is unique within the dependency graph and takes into account the currently active toolchain.

When it is not possible to save off the result when calling the C.Application or C.Library rules, the C.GetLinkTargets rule can retrieve the properly gristed target later.

Parameters

TARGET	The target to retrieve the link targets from.
TOOLCHAIN_SPEC	A tool specification such as `win32/debug` or `$(PLATFORM)/$(CONFIG)/spu`.

Returns: Returns the list of link targets, sometimes more than one, that will be built by the Jam. The target list may be passed to another rule like rule C.LinkLibraries TARGET : LIBRARIES [ : OPTIONS ].

C.Toolchain ps3/debug/spu ;
local sputhing_library = [ C.Library sputhing : sputhing.c ] ;
 
C.Toolchain ps3/debug/ppu ;
 
local also_sputhing_library = [ C.GetLinkTargets sputhing : ps3/debug/spu ] ;
 
# <ps3!release!spu:sputhing>sputhing.lib
Echo sputhing_library - $(sputhing_library) ;
 
# <ps3!release!spu:sputhing>sputhing.lib
Echo also_sputhing_library - $(also_sputhing_library) ;
 
C.LinkLibraries pputhing : $(sputhing_library) ;
C.Application pputhing : pputhing.c ;

rule C.GetActiveToolchain

Returns: Returns the active toolchain.

local saveActiveToolchain = [ C.GetActiveToolchain ] ;
local toolchainsUsed = [ BuildSimple $(saveActiveToolchain)@C.ARCHITECTURE=arm64 ] ;
toolchainsUsed += [ BuildSimple $(saveActiveToolchain)@C.ARCHITECTURE=armv7 ] ;
C.Toolchain $(saveActiveToolchain) ;

rule C.GristFiles TARGET : FILES

Grists the passed in FILES against TARGET and returns them to the user in the form: <win32/debug:TARGET>FILES

Parameters

TARGET	The target to grist. May be `*`.
FILES	The list of files to apply the target grist to.

Returns: Returns the gristed FILES.

# <platform/config:Application>filea.cpp <platform/config:Application>fileb.cpp

Echo Gristed files - [ C.GristFiles Application : filea.cpp fileb.cpp ] ;

rule C.GristTarget TARGET

Grists the passed in TARGET and returns it to the user in the form: <win32/debug>TARGET

Parameters

TARGET The target to grist. May be *.

Returns: Returns the gristed TARGET.

# <platform/config>Application

Echo Gristed target - [ C.GristTarget Application ] ;

rule C.IncludeDirectories TARGET : INCLUDEPATHS [ : OPTIONS ]

Add the INCLUDEPATHS to the given project TARGET.

Parameters

TARGET	The target to assign the `INCLUDEPATHS` to. `TARGET` is optional if rule ActiveTarget TARGET has been specified. If `TARGET` is `*`, the defines are made available globally.
INCLUDEPATHS	The list of include paths to apply.
OPTIONS	The following options are available:

prepend - Instead of appending the paths specified by INCLUDEPATHS to the include directories list, the paths will be prepended instead.

public - If public is specified, the paths specified by INCLUDEPATHS are made available to a project using C.Inherits.

# Add $(Code)/Shared as an include path to myproject.
C.IncludeDirectories myproject : $(Code)/Shared ;
 
# For the win32 platform, add the MFC include path.
C.IncludeDirectories myproject : "$(MSVCNT)/atlmfc/include" ;
 
# Add $(Code)/Shared to myproject and make it available to C.Inherits users.
C.IncludeDirectories myproject : $(Code)/Shared : public ;

rule C.IncludeInBuild TARGET : SOURCES

For the given project TARGET, re-include the SOURCES into the build.

Parameters

TARGET	The target to include the `SOURCES` from. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SOURCES	The list of source files to force include

if $(PLATFORM) != xbox
{
    C.ExcludeFromBuild myproject : $(XBOX_SRCS) ;
 
    # Probably will result in compilation errors on non-xbox platforms.
    C.IncludeInBuild myproject : $(XBOX_SRCS) ;
}

rule C.Inherits TARGET : INHERITS_TARGETS [ : OPTIONS ]

Inherits the settings from INHERITS_TARGETS and apply them to TARGET.

All include directories made public via C.IncludeDirectories are inherited. If OPTIONS contains public, the include directories are made available for any C.Inherits utilizing this TARGET as an INHERITS_TARGET.
All libraries made public via C.LinkPrebuiltLibraries are inherited and passed up the C.Inherits chain regardless of OPTIONS containing public.
All libraries made public via C.LinkLibraries are inherited and passed up the C.Inherits chain regardless of OPTIONS containing public.

If one of the targets specified in INHERITS_TARGETS has no public entries, then an error is generated.

Parameters

TARGET	The target to inherit settings from `INHERITS_TARGETS` into.
INHERITS_TARGETS	The list of targets to inherit public settings from.
OPTIONS	May be empty or may contain `public`. Behavior for `public` is described above.

C.LinkPrebuiltLibraries Misc : advapi32 shell32 user32 : public ;

C.Inherits MiniApp : Misc ;

rule C.InstallNamePath TARGET : INSTALL_NAME_PATH

On platforms with Unix-like shared libraries, C.InstallNamePath allows adjustment of the directory in which the shared library is allowed to run from.

Parameters

TARGET	The target to modify the install name path on. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
INSTALL_NAME_PATH	A valid path for shared libraries, such as `@rpath`.

C.InstallNamePath : @rpath ;

rule C.LibFlags TARGET : FLAGS

For the given project TARGET, assign the lib FLAGS to the current toolchain to be used when archiving object files into library files.

Parameters

TARGET	The target to assign the link `FLAGS` to. `TARGET` is optional if rule ActiveTarget TARGET has been specified. If `TARGET` is `*`, the flags are made available globally.
FLAGS	The list of lib flags to apply.

C.LibFlags * : /LTCG ;

rule C.Library TARGET : SOURCES [ : OPTIONS ]

Compiles SOURCES and archives them into a library called TARGET. Filenames with an .obj or .res are passed straight through to the linker. Any file excluded from the build via rule C.ExcludeFromBuild TARGET : SOURCES is ignored.

Parameters

TARGET	The targets to archive `SOURCES` into. The target name is given without extension; a platform specific extension will be generated. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SOURCES	The list of `.cpp`, `.cxx`, and `.c` to link into the application. Object and compiled Windows resource files may also be passed with this list.
OPTIONS	(optional) The following options are available:

shared - Instead of building a static library (the default), a shared library (DLL) is built.

If shared is specified for OPTIONS, the following additional options are available:

console (default) - Builds a console application. For Visual C++, the DLL is linked with /SUBSYSTEM:CONSOLE.

nodefaults - Avoid adding /SUBSYSTEM to the link flags.

noexportlib - Don't write out an export library.

nomanifest - Don't embed a manifest.

regserver - On Windows, regsvr32 is run during the build to automatically register the DLL with the system. When cleaning, regsvr32 /u is run.

windows - Forces a GUI application. For Visual C++, the DLL is linked with /SUBSYSTEM:WINDOWS.

Returns: Returns the list of link targets, sometimes more than one, that will be built by the Jam. The target list may be passed to another rule like rule C.LinkLibraries TARGET : LIBRARIES [ : OPTIONS ].

# Build a static library called mystaticlibrary from the sources
# file1.c and file2.cpp.
C.Library mystaticlibrary : file1.c file2.cpp ;
 
# Build a shared library called mystaticlibrary from the sources
# file3.c and file4.cpp.
C.Library mysharedlibrary : file3.c file4.cpp : shared ;

rule C.LinkDirectories TARGET : DIRECTORIES [ : OPTIONS ]

Assign the linker search DIRECTORIES for the given project TARGET.

Parameters

TARGET	The target to assign the link `DIRECTORIES` to. `TARGET` is optional if rule ActiveTarget TARGET has been specified. If `TARGET` is `*`, the defines are made available globally.
DIRECTORIES	The list of link directories to apply. Absolute paths are used directly. Relative paths are local to `$(SUBDIR)`. That is, they are relative to the subdirectory specified via SubDir.
OPTIONS	If `public` is specified, the directories specified by `DIRECTORIES` are made available to a project using `C.Inherits`.

# Add c:/some/directory to myproject for all configurations and
# all platforms.
C.LinkDirectories myproject : c:/some/directory ;
 
# Add the MFC link directory.
C.LinkDirectories myproject : "$(MSVCNT)/atlmfc/lib" ;
 
# Relative path that is also publicly inherited.
C.LinkDirectories myproject : ../lib : public ;

rule C.LinkFlags TARGET : FLAGS

Assign extra link FLAGS to the given project TARGET.

Parameters

TARGET	The target to assign the link `FLAGS` to. `TARGET` is optional if rule ActiveTarget TARGET has been specified. If `TARGET` is `*`, the flags are made available globally.
FLAGS	The list of link flags to apply.

if $(C.CONFIG) = debug {
    C.LinkFlags ManagedLuaPlus : /DELAYLOAD:LuaPlus_1100.debug.dll : debug ;
} else if $(C.CONFIG) = release {
    C.LinkFlags ManagedLuaPlus : /DELAYLOAD:LuaPlus_1100.dll : release ;
}
C.LinkFlags ManagedLuaPlus : /KEYFILE:\"$(SEARCH_SOURCE)/ManagedLuaPlus.snk\" ;

rule C.LinkLibraries TARGET : LIBRARIES [ : OPTIONS ]

Makes TARGET depend on Jam generated LIBRARIES and includes them during linking.

Parameters

TARGET	The target to link `LIBRARIES` to. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
LIBRARIES	The list of libraries to apply. These libraries are those generated from the rule C.Library TARGET : SOURCES [ : OPTIONS ] rule. They do not include prebuilt libraries. To link prebuilt libraries, use the rule C.LinkPrebuiltLibraries TARGET : LIBRARIES [ : OPTIONS ] rule.
OPTIONS	If `public` is specified, the libraries specified by `LIBRARIES` are made available to a project using `C.Inherits`.

C.LinkLibraries Misc : zlib : public ;

C.LinkLibraries MiniApp : Application LuaPlusStatic Misc ;

rule C.LinkPrebuiltLibraries TARGET : LIBRARIES [ : OPTIONS ]

Makes TARGET depend on LIBRARIES and includes them during linking.

Parameters

TARGET	The target to link `LIBRARIES` to. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
LIBRARIES	The list of libraries to apply. These libraries are prebuilt libraries, such as kernel32.lib, and are specified without an extension. For those libraries generated from the rule C.Library TARGET : SOURCES [ : OPTIONS ] rule, use the rule C.LinkLibraries TARGET : LIBRARIES [ : OPTIONS ] rule.
OPTIONS	If `public` is specified, the libraries specified by `LIBRARIES` are made available to a project using `C.Inherits`.

C.LinkPrebuiltLibraries MiniApp : advapi32 gdi32 ole32 shell32 user32 ;
 
C.LinkPrebuiltLibraries Misc : advapi32 shell32 user32 : public ;
C.Inherits MiniApp : Misc ;

rule C.Lump PARENT : SOURCES_VARIABLE_NAME : LUMP_NAME [ : PCH_FILENAMES : EXTRA_INCLUDE_PATHS ]

Generates a small file containing an #include amalgamation of files passed into the rule.

The name of the generated lump file is $(LOCATE_SOURCE)/!$(LUMP_NAME)!.$(LUMP_NAME:S). If LUMP_NAME does not have an extension, then the extension from $(PCH_FILENAMES[1]:S) is used. If that doesn't exist, then the default is .cpp.

The lump file has the following contents:

If a precompiled header is specified through PCH_FILENAMES, a #include "\$(PCH_FILENAMES[1])" line is added to the lump file.
For each C-style source specified in SOURCES_VARIABLE_NAME that is not excluded from the build via rule C.ExcludeFromBuild TARGET : SOURCES, a #include "filename" is added to the lump file.

Lumping may be turned off globally by setting the global variable LUMP to be 0.

Parameters

PARENT	The parent target to which the lump file belongs. `PARENT` is optional if rule ActiveTarget TARGET has been specified.
SOURCES_VARIABLE_NAME	The variable name listing the source files to be added to the lump. This is not an expanded version through `$(SRCS)` but rather, it is the actual name of the variable, `SRCS`. On return from the `Lump` rule, `SOURCES_VARIABLE_NAME` will be populated with the gristed name of the lump file. It will not contain the original file list anymore. It may include the precompiled header source filename $(PCH_FILENAMES[1]) if $(PCH_FILENAMES[3]) is set.
PCH_FILENAMES	(optional) `PCH_FILENAMES`[1] is the filename of the precompiled header source file (generally, the .cpp). `PCH_FILENAMES`[2] is the filename of the precompiled header's header file. If `PCH_FILENAMES`[2] is not specified, then `$(PCH_FILENAMES[1]:S=.h)` is used. Finally, if `PCH_FILENAMES`[3] is set to `1`, the precompiled header's source file (set through `PCH_FILENAMES`[1]) is added to the `SOURCES_VARIABLE_NAME` list.
EXTRA_INCLUDE_PATHS	If additional include paths are needed for this lump file, specify them here.

# For the Misc target, use the contents of SRCS to build a lump called
# MiscLump.cpp.  In addition, this lump should use the precompiled header file
# Misc_InternalPch.h, filtering any references to Misc_InternalPch.cpp out of
# its file lists.  Since 1 is specified as the third string item of the
# PCH_FILENAMES parameter, Misc_InternalPch.cpp is added to the SRCS list.
C.Lump Misc : SRCS : MiscLump.cpp : Misc_InternalPch.cpp Misc_InternalPch.h 1 ;
 
# A separate lump in the Misc target is made for PNG_SRCS.  It doesn't have
# a precompiled header, and it will be generated as a .c file.
C.Lump Misc : PNG_SRCS : PNGLump.c ;

rule C.NoPrecompiledHeader TARGET : FILES

Creates a precompiled header and uses it on the specified FILES.

Parameters

TARGET	The target to which the precompiled header belongs. This is needed to properly grist the precompiled header filenames. If not specified, `TARGET` defaults to the active target set via ActiveTarget.
FILES	The list of files to turn off precompiled header support for.

PCH_SRCS =
    # Some files...
    file_no_pch.c
    # More files...
;
 
# For all sources in PCH_SRCS in the Misc project, the precompiled header
# will be set to Misc_InternalPch.h.  The precompiled header file is created
# from Misc_InternalPch.cpp.
C.PrecompiledHeader Misc : Misc_InternalPch : $(PCH_SRCS) ;
 
# Turn off the precompiled header for one of the files that had PCH support
# added.
C.NoPrecompiledHeader Misc : file_no_pch.c ;

rule C.ObjectAddFlags TARGET : SOURCES : FLAGS

For the given SOURCES, add the compilation FLAGS.

Parameters

TARGET	The target containing the `SOURCES`. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SOURCES	The list of sources to add the `FLAGS` to.
FLAGS	The list of flags to add.

C.ObjectAddFlags : myfile.cpp yourfile.cpp : -g ;

rule C.ObjectCFlags TARGET : SOURCES : FLAGS

For the given SOURCES matching *.c, assign the passed in FLAGS.

Parameters

TARGET	The target containing the `SOURCES`. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SOURCES	The list of sources to assign the `FLAGS` to.
FLAGS	The list of flags to apply.

# Assign /clr:oldsyntax to all C files in managedapp across all
# configurations and platforms.
C.ObjectCFlags managedapp : somefile.c : /clr:oldsyntax ;

rule C.ObjectC++Flags TARGET : SOURCES : FLAGS

For the given SOURCES matching *.cpp or *.cxx, assign the passed in FLAGS.

Parameters

TARGET	The target containing the `SOURCES`. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SOURCES	The list of sources to assign the `FLAGS` to.
FLAGS	The list of flags to apply.

# Assign /clr:oldsyntax to all C files in managedapp across all
# configurations and platforms.
C.ObjectC++Flags managedapp : somefile.cpp : /clr:oldsyntax ;

rule C.ObjectDefines TARGET : SOURCES : DEFINES

For the given SOURCES, assign the passed in DEFINES.

Parameters

TARGET	The target containing the `SOURCES`. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SOURCES	The list of sources to assign the `DEFINES` to.
DEFINES	The list of defines to apply.

# Make #defines available for ABC and DEF=5 in someproject's justafile.cpp
# for all configurations and all platforms.
C.ObjectDefines someproject : justafile.cpp : ABC DEF=5 ;

rule C.ObjectForceInclude TARGET : SOURCES : INCLUDES

For the given SOURCES, assign the INCLUDES to the TARGET, causing that project's compilation to force the inclusion of the header before anything else.

Parameters

TARGET	The target containing the `SOURCES`. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SOURCES	The list of sources to assign the force include flag to.
INCLUDES	The list of header files to force include.

# Automatically #include ../common/print.h in libA.cpp.

C.ObjectForceInclude libA : libA.cpp : ../common/print.h ;

rule C.ObjectIncludeDirectories TARGET : SOURCE : INCLUDEPATHS [ : OPTIONS ]

For the given SOURCES, assign the INCLUDEPATHS as part of the TARGET compilation of the SOURCES.

Parameters

TARGET	The target containing the `SOURCES`. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SOURCES	The list of sources to assign the include paths to.
INCLUDEPATHS	The list of include paths to apply.
OPTIONS	The following options are available:

prepend - Instead of appending the paths specified by INCLUDEPATHS to the include directories list, the paths will be prepended instead.

# Add $(Code)/Shared to myproject's somefile.cpp for all configurations
# and all platforms.
C.ObjectIncludeDirectories myproject : somefile.cpp : $(Code)/Shared ;

rule C.ObjectRemoveFlags TARGET : SOURCES : FLAGS

For the given SOURCES, remove the compilation FLAGS.

Parameters

TARGET	The target containing the `SOURCES`. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SOURCES	The list of sources to remove the `FLAGS` from.
FLAGS	The list of flags to remove.

C.ObjectRemoveFlags : myfile.cpp yourfile.cpp : -g ;

rule C.OutputName TARGET : NAME

By default, the name of a generated executable or library is determined by the name of the TARGET. OutputName is used to override the name of the executable or library.

Parameters

TARGET	The target to affect the output name change on. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
NAME	The new name of the output target.

# Change the name of the LuaPlusShared target to LuaPlus_1100.  When
# the shared library is created, the name on disk will be LuaPlus_1100.dll.
C.OutputName LuaPlusShared : LuaPlus_1100 ;

rule C.OutputPath TARGET : OUTPUTPATH

By default, the output location of a generated executable or library is at LOCATE_TARGET. OutputPath is used to override the output location of the executable or library.

Parameters

TARGET	The target to affect the output path change on. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
OUTPUTPATH	The new output location of the generated target.

# Change the name of the LuaPlusShared target to LuaPlus_1100.  When
# the shared library is created, the name on disk will be LuaPlus_1100.dll.
#
# Also change the output location of the generated DLL.
C.OutputName LuaPlusShared : LuaPlus_1100 ;
C.OutputPath LuaPlusShared : "c:/Program Files/LuaPlus" ;

rule C.OutputPostfix TARGET : POSTFIX

The output postfix is appended to the end of the generated target name. By default, the output postfix is empty. This means the resultant filename is $(OUTPUTNAME).$(EXT).

If there is no assigned output postfix for TARGET, then the global target * is checked for a postfix.

Parameters

TARGET	The target to affect the output path change on. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
POSTFIX	The new output postfix of the generated target.

# Change the name of the LuaPlusShared target to LuaPlus_1100.  When
# the shared library is created, the name on disk will be LuaPlus_1100.dll.
#
# Also change the output location of the generated DLL.
#
# Generate the postfix as follows:
#
#   * For debug:   LuaPlus_1100.debug.dll
#   * For release: LuaPlus_1100.dll
C.OutputName LuaPlusShared : LuaPlus_1100 ;
C.OutputPath LuaPlusShared : "c:/Program Files/LuaPlus" ;
if $(C.CONFIG) = debug {
    C.OutputPostfix LuaPlusShared : .debug ;
}

rule C.OutputPostfixClear TARGET

Clear the output postfix.

Parameters

TARGET The target to affect the output path change on. TARGET is optional if rule ActiveTarget TARGET has been specified.

if $(C.CONFIG) = debug {
    C.OutputPostfix LuaPlusShared : .debug ;
    C.OutputPostfixClear LuaPlusShared ;
}

rule C.OutputSuffix TARGET : SUFFIX

The output suffix is the file extension of the generated target. By default, the output suffix is appropriate for an executable or library.

Parameters

TARGET	The target to affect the output suffix change on. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SUFFIX	The new output suffix of the generated target.

# The final name will be SomePlugin.appplugin.

C.OutputSuffix SomePlugin : .appplugin ;

rule C.OverrideToolchainSpec TOOLCHAIN_SPEC_OPTIONS : OPTIONS

Advanced functionality used when setting up overlay toolchains.

Parameters

TOOLCHAIN_SPEC_OPTIONS	TBD
OPTIONS	TBD

# From samples/newplatforms/jam/c/toolchain/win32dx.jam:
rule C.Toolchain.win32dx.* {
    # This feels like a complete hack, but the internals of the win32 toolchain
    # use $(C.PLATFORM) to make decisions about what to include next.
    #
    # Since we're using a custom platform that JamPlus does not understand by
    # default, we work around that by telling JamPlus we are using win32 as a
    # platform.  After the toolchain is loaded, we force the platform back to
    # the intended one.
    C.OverrideToolchainSpec C.PLATFORM=win32 ;
    C.Toolchain.win32.* ;
    C.OverrideToolchainSpec C.PLATFORM=win32 : remove ;
 
    C.Defines * : PLATFORM_WIN32DX ;
}

rule C.PrecompiledHeader TARGET : NAME : FILES

Creates a precompiled header based around NAME and uses it on the specified FILES.

Under Visual C++, NAME.cpp is expected to exist as part of the build. If NAME.cpp is not provided by the user, JamPlus will create an empty one automatically tied to the .cpp extension. If another extension is desired, the first parameter to NAME should be the alternate filename.

Under GCC-based compilers, the precompiled header name is automatic based on the flags and file extensions going into the build.

Parameters

TARGET	The target to which the precompiled header belongs. This is needed to properly grist the precompiled header filenames.
NAME	This parameter is made up of either one or two filenames. The first filename is the `.cpp` file used to create the precompiled header. If it does not contain an extension, `.cpp` is added. If the second filename is not specified, the default is to use the first filename with its suffix modified to `.h`. If the second filename is specified, it will represent the header file used for the precompilation.
FILES	The list of files to apply the precompiled header to.

# For all sources in PCH_SRCS in the Misc project, the precompiled header
# will be set to Misc_InternalPch.h.  The precompiled header file is created
# from Misc_InternalPch.cpp.
C.PrecompiledHeader Misc : Misc_InternalPch : $(PCH_SRCS) ;
 
# The precompiled header stdafx.h is applied to SRCS.  stdafx.cpp is used
# to create the precompiled header.
C.PrecompiledHeader SimpleMFC : stdafx.cpp stdafx.h : $(SRCS) ;

rule C.RemoveFlags TARGET : FLAGS

For the given project TARGET, remove the compilation FLAGS from the current toolchain.

Parameters

TARGET	The target to remove the `FLAGS` from. `TARGET` is optional if rule ActiveTarget TARGET has been specified. If `TARGET` is `*`, the flags are made available globally.
FLAGS	The list of flags to remove.

C.RemoveFlags : -g ;

rule C.RuntimeType TARGET : TYPE [ : THE_PLATFORM ]

For the given project TARGET, alter the build to use either a statically linked C runtime or a dynamically linked C runtime.

Note: At this time, the C runtime type only affects Visual C++ applications.

Parameters

TARGET	The target to assign the new C runtime to. `TARGET` is optional if rule ActiveTarget TARGET has been specified. If `TARGET` is `*`, the C runtime is changed globally.
TYPE	May be set to either `static` or `dynamic`. Use `static` to select a statically linked C runtime. Use `dynamic` to dynamically link against the C runtime.
THE_PLATFORM	(optional) If not specified, the default is the current platform.

# Use the statically linked C runtime for all targets.
C.RuntimeType * : static ;
 
# Use the dynamically linked C runtime for the helloworld target.
C.RuntimeType helloworld : dynamic ;

rule C.SearchSource TARGET : SOURCES : SEARCH_PATHS

For the given project TARGET, apply SEARCH_PATHS to each of the SOURCES that do not already have a SEARCH applied.

Parameters

TARGET	The target to work against. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SOURCES	The list of sources to apply `SEARCH_PATH` to.
SEARCH_PATH	The paths to search for. If none are specified, `SEARCH_SOURCE` is used. Any relative paths are rooted against `SEARCH_SOURCE`.

# Shorten the directory length for the output directory, as it exceeds 260 characters on Windows in certain cases.
#    (instead of $(NDKROOT)/sources/android/cpufeatures/cpu-features.c)
C.SearchSource : cpufeatures/cpu-features.c : $(NDKROOT)/sources/android ;

rule C.Toolchain TOOLCHAIN_SPEC

Activate the toolchain specified by TOOLCHAIN_SPEC.

Parameters

TOOLCHAIN_SPEC The toolchain to activate.

C.Toolchain win32/debug ;

rule LocateSource TARGET : DIRECTORY

Helper function to set LOCATE_SOURCE on TARGET to DIRECTORY and to override the current global LOCATE_SOURCE provided from rule SubDir TOP d1...dn : SUBNAME.

Parameters

TARGET	The target to do the processing within. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
DIRECTORY	The directory to use as the override.

LocateSource test : some/directory ;

rule LocateTarget TARGET : DIRECTORY

Helper function to set LOCATE_TARGET on TARGET to DIRECTORY and to override the current global LOCATE_TARGET provided from rule SubDir TOP d1...dn : SUBNAME.

Parameters

TARGET	The target to do the processing within. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
DIRECTORY	The directory to use as the override.

LocateTarget test : some/directory ;