JamPlus manual: C/C++ Rules

    # Automatically made available, so this isn't needed.
    IncludeModule c ;

The C module provides rules to build C and 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 2010, Visual Studio 2008, Visual Studio 2005, Visual Studio 2003, and Visual C++ 6. MinGW can also be specified. On other OSes, it attempts to detect GCC.

List of Rules

Rules

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.

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.

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 ActiveProject PROJECT has been specified.
	SOURCES	The list of `.cpp`, `.cxx`, and `.c` (and possibly others) 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.

    C.Application helloworld : helloworld.cpp ;

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 ActiveProject PROJECT has been specified.
	SOURCES	The list of `.cpp`, `.cxx`, and `.c` (and possibly others) 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.

    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 ActiveProject PROJECT 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 [ : THE_CONFIG : THE_PLATFORM ]

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 ActiveProject PROJECT has been specified. If `TARGET` is `*`, the flags are made available globally.
	FLAGS	The list of flags to apply.
	THE_CONFIG	(optional) If not specified, the default is all configurations.
	THE_PLATFORM	(optional) If not specified, the default is all platforms.

    # 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.C++Exceptions TARGET : TYPE [ : THE_CONFIG : THE_PLATFORM ]

For the given project TARGET, turn on/off C++ exception support within the specified configuration and platform.

Parameters:

	TARGET	The target to assign the `FLAGS` to. `TARGET` is optional if rule ActiveProject PROJECT has been specified. If `TARGET` is `*`, the flags are made available globally.
	TYPE	`true` to turn on exceptions, `false` (default) to turn off exceptions.
	THE_CONFIG	(optional) If not specified, the default is the current `$`(CONFIG).
	THE_PLATFORM	(optional) If not specified, the default is the current `$`(PLATFORM).

    # Turn on exceptions in the target mycppapp for the current $(CONFIG).
    C.C++Exceptions mycppapp : true ;

    # Turn on exceptions in the target mycppapp for all configs.
    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 [ : THE_CONFIG : THE_PLATFORM ]

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 ActiveProject PROJECT has been specified. If `TARGET` is `*`, the flags are made available globally.
	FLAGS	The list of flags to apply.
	THE_CONFIG	(optional) If not specified, the default is all configurations.
	THE_PLATFORM	(optional) If not specified, the default is all platforms.

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

    # Assign /clr:oldsyntax to all C++ files in managedapp for the debug
    # configuration and all platforms.
    C.C++Flags managedapp : /clr:oldsyntax : debug ;

    # Assign /clr:oldsyntax to all C++ files in managedapp for the debug
    # configuration and win32 platform.
    C.C++Flags managedapp : /clr:oldsyntax : debug : win32 ;

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.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 ActiveProject PROJECT 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.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 ActiveProject PROJECT has been specified.
	SOURCES	One or more .def files. .def files are searched for in .

    # Link the WorkspaceWhiz target against WorkspaceWhiz.def.
    C.DefFile WorkspaceWhiz : WorkspaceWhiz.def ;

rule C.Defines TARGET : DEFINES [ : THE_CONFIG : THE_PLATFORM ]

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

Parameters:

	TARGET	The target to assign the `DEFINES` to. `TARGET` is optional if rule ActiveProject PROJECT has been specified. If `TARGET` is `*`, the defines are made available globally.
	DEFINES	The list of defines to apply.
	THE_CONFIG	(optional) If not specified, the default is all configurations.
	THE_PLATFORM	(optional) If not specified, the default is all platforms.

    # 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.
    C.Defines * : WIN32 : : win32 ;

    # Quote a #define, keeping the quotes for compilation:
    C.Defines luacom : LUA5 "LUACOM_DLL=\\\"luacom.dll\\\"" ;

rule C.ExcludeFromBuild TARGET : SOURCES

For the given project TARGET, exclude the SOURCES from the build. If using JamToWorkspace for project generation, sources must be excluded and not simply removed from the list. Otherwise, they don't all show in the generated projects.

Parameters:

	TARGET	The target to exclude the `SOURCES` from. `TARGET` is optional if rule ActiveProject PROJECT has been specified.
	SOURCES	The list of defines to exclude.

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

rule C.Flags TYPE : TARGET : FLAGS [ : THE_CONFIG : THE_PLATFORM ]

For the given project TARGET, assign the FLAGS to the appropriate configuration and platform. 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 "rule_C_AddBuildExtensions" "C.AddBuildExtensions".
	TARGET	The target to assign the `FLAGS` to. `TARGET` is optional if rule ActiveProject PROJECT has been specified. If `TARGET` is `*`, the flags are made available globally.
	FLAGS	The list of flags to apply.
	THE_CONFIG	(optional) If not specified, the default is all configurations.
	THE_PLATFORM	(optional) If not specified, the default is all platforms.

    C.Flags CC  : * : -g -O0 -arch i386 : debug : macosx32 ;
    C.Flags C++ : * : -g -O0 -arch i386 : debug : macosx32 ;

rule C.ForceInclude TARGET : INCLUDES [ : THE_CONFIG : THE_PLATFORM ]

For the given project TARGET, assign the INCLUDES to the appropriate configuration and platform, 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 ActiveProject PROJECT has been specified. If `TARGET` is `*`, the defines are made available globally.
	INCLUDES	The list of header files to force include.
	THE_CONFIG	(optional) If not specified, the default is all configurations.
	THE_PLATFORM	(optional) If not specified, the default is all platforms.

    # Automatically #include myheader.h for all source files listed in myproject.
    C.ForceInclude myproject : myheader.h ;

rule C.IncludeDirectories TARGET : INCLUDEPATHS [ : THE_CONFIG : THE_PLATFORM ]

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

Parameters:

	TARGET	The target to assign the `INCLUDEPATHS` to. `TARGET` is optional if rule ActiveProject PROJECT has been specified. If `TARGET` is `*`, the defines are made available globally.
	INCLUDEPATHS	The list of include paths to apply.
	THE_CONFIG	(optional) If not specified, the default is all configurations.
	THE_PLATFORM	(optional) If not specified, the default is all platforms.

    # Add $(Code)/Shared to myproject for all configurations and all platforms.
    C.IncludeDirectories myproject : $(Code)/Shared ;

    # For the win32 platform, add the MFC include path.
    C.IncludeDirectories myproject : "$(MSVCNT)/atlmfc/include" : : win32 ;

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 ActiveProject PROJECT 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.

    # 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 [ : THE_CONFIG : THE_PLATFORM ]

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

Parameters:

	TARGET	The target to assign the link `DIRECTORIES` to. `TARGET` is optional if rule ActiveProject PROJECT 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 . That is, they are relative to the subdirectory specified via SubDir.
	THE_CONFIG	(optional) If not specified, the default is all configurations.
	THE_PLATFORM	(optional) If not specified, the default is all platforms.

    # Add c:/some/directory to myproject for all configurations and
    # all platforms.
    C.LinkDirectories myproject : c:/some/directory ;

    # For the win32 platform, add the MFC link directory.
    C.LinkDirectories myproject : "$(MSVCNT)/atlmfc/lib" : : win32 ;

    # Relative path:
    C.LinkDirectories myproject : ../lib ;

rule C.LinkFlags TARGET : FLAGS [ : THE_CONFIG : THE_PLATFORM ]

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

Parameters:

	TARGET	The target to assign the link `FLAGS` to. `TARGET` is optional if rule ActiveProject PROJECT has been specified. If `TARGET` is `*`, the flags are made available globally.
	FLAGS	The list of link flags to apply.
	THE_CONFIG	(optional) If not specified, the default is all configurations.
	THE_PLATFORM	(optional) If not specified, the default is all platforms.

    C.LinkFlags ManagedLuaPlus : /DELAYLOAD:LuaPlus_1100.debug.dll : debug ;
    C.LinkFlags ManagedLuaPlus : /DELAYLOAD:LuaPlus_1100.dll : release ;
    C.LinkFlags ManagedLuaPlus : /KEYFILE:\"$(SEARCH_SOURCE)/ManagedLuaPlus.snk\" ;

rule C.LinkFrameworks TARGET : FRAMEWORKS [ : THE_CONFIG : THE_PLATFORM ]

Note:: This rule is only valid on Mac OS X.

Links TARGET against the FRAMEWORKS specified. No dependencies are set, so changes to the framework will not be relinked.

Parameters:

	TARGET	The target to link `LIBRARIES` to. `TARGET` is optional if rule ActiveProject PROJECT has been specified.
	FRAMEWORKS	The list of frameworks to link. The frameworks are specified without an extension.
	THE_CONFIG	(optional) If not specified, the default is all configurations.
	THE_PLATFORM	(optional) If not specified, the default is all platforms.

    C.LinkFrameworks MyApp : CoreFoundation ;

rule C.LinkLibraries TARGET : LIBRARIES [ : THE_CONFIG : THE_PLATFORM ]

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 ActiveProject PROJECT 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 [ : THE_CONFIG : THE_PLATFORM ] rule.
	THE_CONFIG	(optional) If not specified, the default is all configurations.
	THE_PLATFORM	(optional) If not specified, the default is all platforms.

        C.LinkLibraries MiniApp : Application LuaPlusStatic Misc ;

rule C.LinkPrebuiltLibraries TARGET : LIBRARIES [ : THE_CONFIG : THE_PLATFORM ]

Makes TARGET depend on LIBRARIES and includes them during linking.

Parameters:

	TARGET	The target to link `LIBRARIES` to. `TARGET` is optional if rule ActiveProject PROJECT 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 [ : THE_CONFIG : THE_PLATFORM ] rule.
	THE_CONFIG	(optional) If not specified, the default is all configurations.
	THE_PLATFORM	(optional) If not specified, the default is all platforms.

    C.LinkPrebuiltLibraries MiniApp : advapi32 gdi32 ole32 shell32 user32 ;

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 ActiveProject PROJECT 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 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 ActiveProject.
	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.ObjectCFlags TARGET : SOURCES : FLAGS [ : THE_CONFIG : THE_PLATFORM ]

For the given SOURCES matching *.c, assign the FLAGS to the appropriate configuration and platform.

Parameters:

	TARGET	The target containing the `SOURCES`. `TARGET` is optional if rule ActiveProject PROJECT has been specified.
	SOURCES	The list of sources to assign the `FLAGS` to.
	FLAGS	The list of flags to apply.
	THE_CONFIG	(optional) If not specified, the default is all configurations.
	THE_PLATFORM	(optional) If not specified, the default is all platforms.

    # 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 [ : THE_CONFIG : THE_PLATFORM ]

For the given SOURCES matching *.cpp or *.cxx, assign the FLAGS to the appropriate configuration and platform.

Parameters:

	TARGET	The target containing the `SOURCES`. `TARGET` is optional if rule ActiveProject PROJECT has been specified.
	SOURCES	The list of sources to assign the `FLAGS` to.
	FLAGS	The list of flags to apply.
	THE_CONFIG	(optional) If not specified, the default is all configurations.
	THE_PLATFORM	(optional) If not specified, the default is all platforms.

    # 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 [ : THE_CONFIG : THE_PLATFORM ]

For the given SOURCES, assign the DEFINES to the appropriate configuration and platform.

Parameters:

	TARGET	The target containing the `SOURCES`. `TARGET` is optional if rule ActiveProject PROJECT has been specified.
	SOURCES	The list of sources to assign the `DEFINES` to.
	DEFINES	The list of defines to apply.
	THE_CONFIG	(optional) If not specified, the default is all configurations.
	THE_PLATFORM	(optional) If not specified, the default is all platforms.

    # 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 [ : THE_CONFIG : THE_PLATFORM ]

For the given SOURCES, assign the INCLUDES to the appropriate configuration and platform, 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 ActiveProject PROJECT has been specified.
	SOURCES	The list of sources to assign the force include flag to.
	INCLUDES	The list of header files to force include.
	THE_CONFIG	(optional) If not specified, the default is all configurations.
	THE_PLATFORM	(optional) If not specified, the default is all platforms.

    # Automatically #include ../common/print.h in libA.cpp.
    C.ObjectForceInclude libA : libA.cpp : ../common/print.h ;

rule C.ObjectIncludeDirectories TARGET : SOURCE : INCLUDEPATHS [ : THE_CONFIG : THE_PLATFORM ]

For the given SOURCES, assign the INCLUDEPATHS to the appropriate configuration and platform.

Parameters:

	TARGET	The target containing the `SOURCES`. `TARGET` is optional if rule ActiveProject PROJECT has been specified.
	SOURCES	The list of sources to assign the include paths to.
	INCLUDEPATHS	The list of include paths to apply.
	THE_CONFIG	(optional) If not specified, the default is all configurations.
	THE_PLATFORM	(optional) If not specified, the default is all platforms.

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

rule C.OutputName TARGET : NAME [ : THE_CONFIG : THE_PLATFORM ]

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 ActiveProject PROJECT has been specified.
	NAME	The new name of the output target.
	THE_CONFIG	(optional) If not specified, the default is all configurations.
	THE_PLATFORM	(optional) If not specified, the default is all platforms.

    # 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 [ : THE_CONFIG : THE_PLATFORM ]

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 ActiveProject PROJECT has been specified.
	OUTPUTPATH	The new output location of the generated target.
	THE_CONFIG	(optional) If not specified, the default is all configurations.
	THE_PLATFORM	(optional) If not specified, the default is all platforms.

    # 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_CONFIG : THE_PLATFORM ]

The output postfix is appended to the end of the generated target name. By default, the output postfix is .$(CONFIG). This means the resultant filename is $(OUTPUTNAME).$(CONFIG).$(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 ActiveProject PROJECT has been specified.
	POSTFIX	The new output postfix of the generated target.
	THE_CONFIG	(optional) If not specified, the default is all configurations.
	THE_PLATFORM	(optional) If not specified, the default is all platforms.

    # 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" ;
    C.OutputPostfix LuaPlusShared : .debug : debug ;
    C.OutputPostfix LuaPlusShared : : release ;

rule C.OutputPostfixClear TARGET : THE_CONFIG : THE_PLATFORM

Clear the output postfix.

Parameters:

	TARGET	The target to affect the output path change on. `TARGET` is optional if rule ActiveProject PROJECT has been specified.
	THE_CONFIG	(optional) If not specified, the default is all configurations.
	THE_PLATFORM	(optional) If not specified, the default is all platforms.

    C.OutputPostfix LuaPlusShared : .debug : debug ;
        C.OutputPostfixClear LuaPlusShared : debug ;

rule C.OutputSuffix TARGET : SUFFIX [ : THE_CONFIG : THE_PLATFORM ]

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 ActiveProject PROJECT has been specified.
	SUFFIX	The new output suffix of the generated target.
	THE_CONFIG	(optional) If not specified, the default is all configurations.
	THE_PLATFORM	(optional) If not specified, the default is all platforms.

    # The final name will be SomePlugin.appplugin.
    C.OutputSuffix SomePlugin : .appplugin ;

rule C.PrecompiledHeader TARGET : NAME : 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.
	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) ;