csbuild.toolchain module

Toolchain Module

Defines the base class for creating custom toolchains

class csbuild.toolchain.ClassCombiner(objs)

Bases: object

Represents the combined return value of a multi-object accessor.

Variables:objs – The objects contained within the combined class

@itype objs: list[object]

class csbuild.toolchain.SettingsOverrider

Bases: object

AddCcCompilerFlags(*args)

Specifies a list of literal strings to be passed to the C compiler. As this is toolchain-specific, it should be called on a per-toolchain basis.

Parameters:args (an arbitrary number of strings) – The list of flags to be passed
AddCompilerFlags(*args)

Specifies a list of literal strings to be passed to the both the C compiler and the C++ compiler. As this is toolchain-specific, it should be called on a per-toolchain basis.

Parameters:args (an arbitrary number of strings) – The list of flags to be passed
AddCxxCompilerFlags(*args)

Specifies a list of literal strings to be passed to the C++ compiler. As this is toolchain-specific, it should be called on a per-toolchain basis.

Parameters:args (an arbitrary number of strings) – The list of flags to be passed
AddDefines(*args)

Add additionally defined preprocessor directives, as if each file had a #define directive at the very top.

Parameters:args (an arbitrary number of strings) – The list of preprocessor directives to define
AddExcludeDirectories(*args)

Exclude the given directories from the project. This may be called multiple times to add additional excludes. Directories are relative to the location of the script itself, not the specified project working directory.

Parameters:args (an arbitrary number of strings) – The list of directories to be excluded.
AddExcludeFiles(*args)

Exclude the given files from the project. This may be called multiple times to add additional excludes. Files are relative to the location of the script itself, not the specified project working directory.

Parameters:args (an arbitrary number of strings) – The list of files to be excluded.
AddExtraDirectories(*args)

Adds additional directories to search for files in.

Parameters:args (an arbitrary number of strings) – A list of directories to search.
AddExtraFiles(*args)

Adds additional files to be compiled that are not in the project directory.

Parameters:args (an arbitrary number of strings) – A list of files to add.
AddExtraObjects(*args)

Adds additional objects to be passed to the linker that are not in the project directory.

Parameters:args (an arbitrary number of strings) – A list of objects to add.
AddFrameworkDirectories(*args)

Search the given directories for frameworks. This may be called multiple times to add additional directories. Directories are relative to the location of the script itself, not the specified project working directory.

Parameters:args (an arbitrary number of strings) – The list of directories to be searched.
AddFrameworks(*args)

When linking the project, link against the given frameworks. This may be called multiple times to add additional frameworks.

These will have no effect on toolchains that do not support frameworks.

Parameters:args (an arbitrary number of strings) – The list of frameworks to link in.
AddIncludeDirectories(*args)

Search the given directories for include headers. This may be called multiple times to add additional directories. Directories are relative to the location of the script itself, not the specified project working directory.

In the gcc toolchain, /usr/include and /usr/local/include (or the platform appropriate equivalents) will always be appended to the end of this list.

Parameters:args (an arbitrary number of strings) – The list of directories to be searched.
AddLibraries(*args)

When linking the project, link in the given libraries. This may be called multiple times to add additional libraries.

In the gcc toolchain, these will all be prefixed with “lib” when looking for the file to link. I.e., csbuild.Libraries(“MyLib”) will link libMyLib.so or libMyLib.a.

For compatibility, the msvc toolchain will search for the library exactly as specified, and if it can’t find it, will then search for it with the lib prefix. I.e., csbuild.Libraries(“MyLib”) will first search for MyLib.lib, and if that isn’t found, will then search for libMyLib.lib.

Parameters:args (an arbitrary number of strings) – The list of libraries to link in.
AddLibraryDirectories(*args)

Search the given directories for libraries to link. This may be called multiple times to add additional directories. Directories are relative to the location of the script itself, not the specified project working directory.

In the gcc toolchain, /usr/lib and /usr/local/lib (or the platform appropriate equivalents) will always be appended to the end of this list.

Parameters:args (an arbitrary number of strings) – The list of directories to be searched.
AddLinkerFlags(*args)

Specifies a list of literal strings to be passed to the linker. As this is toolchain-specific, it should be called on a per-toolchain basis.

Parameters:args (an arbitrary number of strings) – The list of flags to be passed
AddSharedLibraries(*args)

Similar to csbuild.toolchain.Libraries, but forces these libraries to be linked dynamically.

Parameters:args (an arbitrary number of strings) – The list of libraries to link in.
AddStaticLibraries(*args)

Similar to csbuild.toolchain.Libraries, but forces these libraries to be linked statically.

Parameters:args (an arbitrary number of strings) – The list of libraries to link in.
AddUndefines(*args)

Add explicitly undefined preprocessor directives, as if each file had a #undef directive at the very top.

Parameters:args (an arbitrary number of strings) – The list of preprocessor directives to undefine
ClearCcCompilerFlags()

Clears the list of literal C compiler flags.

ClearChunks()

Clears the explicitly set list of chunks and returns the behavior to the default.

ClearCompilerFlags()

Clears the list of literal compiler flags.

ClearCxxCompilerFlags()

Clears the list of literal C++ compiler flags.

ClearDefines()

clears the list of defines

ClearExtraDirectories()

Clear the list of external directories to search.

ClearExtraFiles()

Clear the list of external files to compile.

ClearExtraObjects()

Clear the list of external objects to link.

ClearFrameworkDirectories()

Clears the framework directories, including the defaults.

ClearFrameworks()

Clears the list of framworks

ClearIncludeDirectories()

Clears the include directories, including the defaults.

ClearLibDirectories()

Clears the library directories, including the defaults

ClearLibraries()

Clears the list of libraries

ClearLinkerFlags()

Clears the list of literal linker flags.

ClearSharedLibraries()

Clears the list of libraries

ClearStaticLibraries()

Clears the list of libraries

ClearUndefines()

clears the list of undefines

DisableChunkedBuild()

Turn off the chunked/unity build system and build using individual files.

DisablePrecompile(*args)

Disables precompilation and handles headers as usual.

Parameters:args (an arbitrary number of strings) – A list of files to disable precompilation for.

If this list is empty, it will disable precompilation entirely.

DisableProfiling()

Turns profiling optimizations back off

DisableWarnings()

Disables all warnings.

DisableWarningsAsErrors()

Disable the promotion of warnings to errors.

DoNotChunk(*files)

Prevents the listed files (or files matching the listed patterns) from ever being placed in a chunk, ever.

Parameters:files (arbitrary number of strings) – filenames or patterns to exclude from chunking
DoNotChunkTogether(pattern, *additionalPatterns)

Makes files matching the given patterns mutually exclusive for chunking. I.e., if you call this with DoNotChunkTogether(“File1.cpp”, “File2.cpp”), it guarantees File1 and File2 will never appear together in the same chunk. If you specify more than two files, or a pattern that matches more than two files, no two files in the list will ever appear together.

Parameters:
  • pattern (string) – Pattern to search for files with (i.e., Source/*_Unchunkable.cpp)
  • additionalPatterns (arbitrary number of optional strings) – Additional patterns to compile the list of mutually exclusive files with
EnableChunkedBuild()

Turn chunked/unity build on and build using larger compilation units. This is the default.

EnableChunkedPrecompile()

When this is enabled, all header files will be precompiled into a single “superheader” and included in all files.

EnableHeaderInstall()

Enables installation of the project’s headers Default target is /usr/local/include, unless the –prefix option is specified. If –prefix is specified, the target will be {prefix}/include

Parameters:s (str) – Override directory - i.e., if you specify this as “headers”, the headers will be installed

to {prefix}/headers.

EnableOutputInstall()

Enables installation of the compiled output file. Default target is /usr/local/lib, unless the –prefix option is specified. If –prefix is specified, the target will be {prefix}/lib

Parameters:s (str) – Override directory - i.e., if you specify this as “libraries”, the libraries will be installed

to {prefix}/libraries.

EnableProfiling()

Optimize output for profiling

EnableUnityBuild()

Turns on true unity builds, combining all files into only one compilation unit.

EnableWarningsAsErrors()

Promote all warnings to errors.

IgnoreExternalHeaders()

If this option is set, external headers will not be checked or followed when building. Only headers within the base project’s directory and its subdirectories will be checked. This will speed up header checking, but if you modify any external headers, you will need to manually –clean or –rebuild the project.

LinkSharedRuntime()

Link against a dynamic C/C++ runtime library.

LinkStaticRuntime()

Link against a static C/C++ runtime library.

Precompile(*args)

Explicit list of header files to precompile. Disables chunk precompile when called.

Parameters:args (an arbitrary number of strings) – The files to precompile.
PrecompileAsC(*args)

Specifies header files that should be compiled as C headers instead of C++ headers.

Parameters:args (an arbitrary number of strings) – The files to specify as C files.
SetCcCommand(s)

Specify the compiler executable to be used for compiling C files. Ignored by the msvc toolchain.

Parameters:s (str) – Path to the executable to use for compilation
SetChunkTolerance(i)

If building using ChunkSize():

Set the number of modified files below which a chunk will be split into individual files.

For example, if you set this to 3 (the default), then a chunk will be built as a chunk if more than three of its files need to be built; if three or less need to be built, they will be built individually to save build time.

If building using ChunkFilesize():

Sets the total combined filesize of modified files within a chunk below which the chunk will be split into individual files.

For example, if you set this to 150000 (the default), then a chunk will be built as a chunk if the total filesize of the files needing to be built exceeds 150kb. If less than 150kb worth of data needs to be built, they will be built individually to save time.

Parameters:i (int) – Number of files required to trigger chunk building.
SetChunks(*chunks)

Explicitly set the chunks used as compilation units.

NOTE that setting this will disable the automatic file gathering, so any files in the project directory that are not specified here will not be built.

Parameters:chunks (an arbitrary number of lists of strings) – Lists containing filenames of files to be built,

relativel to the script’s location, NOT the project working directory. Each list will be built as one chunk.

SetCxxCommand(s)

Specify the compiler executable to be used for compiling C++ files. Ignored by the msvc toolchain.

Parameters:s (str) – Path to the executable to use for compilation
SetDebugLevel(i)

Sets the debug level. Due to toolchain differences, this should be called per-toolchain, usually.

Parameters:i (either str or int) – A toolchain-appropriate debug level.
SetDefaultTarget(s)

Sets the default target if none is specified. The default value for this is release.

Parameters:s (str) – Name of the target to build for this project if none is specified.
SetHeaderInstallSubdirectory(s)

Specifies a subdirectory of {prefix}/include in which to install the headers.

Parameters:s (str) – The desired subdirectory; i.e., if you specify this as “myLib”, the headers will be

installed under {prefix}/include/myLib.

SetHeaderRecursionDepth(i)

Sets the depth to search for header files. If set to 0, it will search with unlimited recursion to find included headers. Otherwise, it will travel to a depth of i to check headers. If set to 1, this will only check first-level headers and not check headers included in other headers; if set to 2, this will check headers included in headers, but not headers included by those headers; etc.

This is very useful if you’re using a large library (such as boost) or a very large project and are experiencing long waits prior to compilation.

Parameters:i (int) – Recursion depth for header examination
SetIntermediateDirectory(s)

Specifies the directory in which to place the intermediate .o or .obj files.

Parameters:s (str) – The object directory, relative to the current script location, NOT to the project working directory.
SetMaxChunkFileSize(i)

Sets the maximum combined filesize for a chunk. The default is 500000, and this is the default behavior.

This value is ignored if SetChunks is called.

Mutually exclusive with ChunkNumFiles()

Parameters:i (int) – Maximum size per chunk in bytes.
SetNumFilesPerChunk(i)

Set the size of the chunks used in the chunked build. This indicates the number of files per compilation unit. The default is 10.

This value is ignored if SetChunks is called.

Mutually exclusive with ChunkFilesize().

Parameters:i (int) – Number of files per chunk
SetOptimizationLevel(i)

Sets the optimization level. Due to toolchain differences, this should be called per-toolchain, usually.

Parameters:i (either str or int) – A toolchain-appropriate optimization level.
SetOutput(name, projectType=0)

Sets the output options for this project.

Parameters:name (str) – The output name. Do not include an extension, and do not include the “lib” prefix for libraries on

Linux. These are added automatically.

Parameters:projectType (csbuild.ProjectType) – The type of project to compile. The options are: - ProjectType.Application - on Windows, this will be built with a .exe extension. On Linux, there is no extension. - ProjectType.SharedLibrary - on Windows, this will generate a .lib and a .dll. On Linux, this will generate a .so and prefix “lib” to the output name. - ProjectType.StaticLibrary - on Windows, this will generate a .lib. On Linux, this will generate a .a and prefix “lib” to the output name.
SetOutputArchitecture(arch)

Set the output architecture.

Parameters:arch (ArchitectureType) – The desired architecture.
SetOutputDirectory(s)

Specifies the directory in which to place the output file.

Parameters:s (str) – The output directory, relative to the current script location, NOT to the project working directory.
SetOutputExtension(name)

This allows you to override the extension used for the output file.

Parameters:name (str) – The desired extension, including the .; i.e., csbuild.Extension( ”.exe” )
SetStaticLinkMode(mode)

Determines how static links are handled. With the msvc toolchain, iterative link times of a project with many libraries can be significantly improved by setting this to :StaticLinkMode.LinkIntermediateObjects:. This will cause the linker to link the .obj files used to make a library directly into the dependent project. Link times for full builds may be slightly slower, but this will allow incremental linking to function when libraries are being changed. (Usually, changing a .lib results in a full link.)

On most toolchains, this defaults to :StaticLinkMode.LinkLibs:. In debug mode only for the msvc toolchain, this defaults to :StaticLinkMode.LinkIntermediateObjects:.

Parameters:mode – The link mode to set
SetSupportedArchitectures(*architectures)

Specifies the architectures that this project supports. This can be used to limit –all-architectures from building everything supported by the toolchain, if the project is not set up to support all of the toolchain’s architectures.

SetUserData(key, value)

Adds miscellaneous data to a project. This can be used later in a build event or in a format string.

This becomes an attribute on the project’s userData member variable. As an example, to set a value:

csbuild.SetUserData(“someData”, “someValue”)

Then to access it later:

project.userData.someData

Parameters:
  • key (str) – name of the variable to set
  • value (any) – value to set to that variable
copy()
class csbuild.toolchain.compilerBase

Bases: csbuild.toolchain.SettingsOverrider

static AdditionalArgs(parser)

Asks for additional command-line arguments to be added by the toolchain.

Parameters:parser (argparse.argument_parser) – A parser for these arguments to be added to
GetBaseCcCommand(project)

Retrieves the BASE C compiler command for this project.

The difference between the base command and the extended command is as follows:
  1. The base command does not include any specific files in it

2. The base command should be seen as the full list of compiler settings that will force a full recompile if ANY of them are changed. For example, optimization settings should be included here because a change to that setting should cause all object files to be regenerated.

Thus, anything that can be changed without forcing a clean rebuild should be in the extended command, not the base.

Parameters:project (csbuild.projectSettings.projectSettings) – The project currently being compiled, which can be used to retrieve any needed information.
Returns:The base command string
Return type:str
GetBaseCcPrecompileCommand(project)

Retrieves the BASE C compiler command for precompiling headers in this project.

The difference between the base command and the extended command is as follows:
  1. The base command does not include any specific files in it

2. The base command should be seen as the full list of compiler settings that will force a full recompile if ANY of them are changed. For example, optimization settings should be included here because a change to that setting should cause all object files to be regenerated.

Thus, anything that can be changed without forcing a clean rebuild should be in the extended command, not the base.

Parameters:project (csbuild.projectSettings.projectSettings) – The project currently being compiled, which can be used to retrieve any needed information.
Returns:The base command string
Return type:str
GetBaseCxxCommand(project)

Retrieves the BASE C++ compiler command for this project.

The difference between the base command and the extended command is as follows:
  1. The base command does not include any specific files in it

2. The base command should be seen as the full list of compiler settings that will force a full recompile if ANY of them are changed. For example, optimization settings should be included here because a change to that setting should cause all object files to be regenerated.

Thus, anything that can be changed without forcing a clean rebuild should be in the extended command, not the base.

Parameters:project (csbuild.projectSettings.projectSettings) – The project currently being compiled, which can be used to retrieve any needed information.
Returns:The base command string
Return type:str
GetBaseCxxPrecompileCommand(project)

Retrieves the BASE C++ compiler command for precompiling headers in this project.

The difference between the base command and the extended command is as follows:
  1. The base command does not include any specific files in it

2. The base command should be seen as the full list of compiler settings that will force a full recompile if ANY of them are changed. For example, optimization settings should be included here because a change to that setting should cause all object files to be regenerated.

Thus, anything that can be changed without forcing a clean rebuild should be in the extended command, not the base.

Parameters:project (csbuild.projectSettings.projectSettings) – The project currently being compiled, which can be used to retrieve any needed information.
Returns:The base command string
Return type:str
GetDefaultArchitecture()
GetExtendedCommand(baseCmd, project, forceIncludeFile, outObj, inFile)

Retrieves the EXTENDED C/C++ compiler command for compiling a specific file

The difference between the base command and the extended command is as follows:
  1. The base command does not include any specific files in it

2. The base command should be seen as the full list of compiler settings that will force a full recompile if ANY of them are changed. For example, optimization settings should be included here because a change to that setting should cause all object files to be regenerated.

Thus, anything that can be changed without forcing a clean rebuild should be in the extended command, not the base.

Parameters:baseCmd – The project’s base command as returned from :get_base_cxx_command: or :get_base_cc_command:,

as is appropriate for the file being compiled. :type baseCmd: str

Parameters:
  • project (csbuild.projectSettings.projectSettings) – The project currently being compiled, which can be used to retrieve any needed information.
  • forceIncludeFile (str) – A precompiled header that’s being forcefully included.
  • outObj (str) – The object file to be generated by this command
  • inFile (str) – The file being compiled
Returns:

The extended command string, including the base command string

Return type:

str

GetExtendedPrecompileCommand(baseCmd, project, forceIncludeFile, outObj, inFile)

Retrieves the EXTENDED C/C++ compiler command for compiling a specific precompiled header

The difference between the base command and the extended command is as follows:
  1. The base command does not include any specific files in it

2. The base command should be seen as the full list of compiler settings that will force a full recompile if ANY of them are changed. For example, optimization settings should be included here because a change to that setting should cause all object files to be regenerated.

Thus, anything that can be changed without forcing a clean rebuild should be in the extended command, not the base.

Parameters:baseCmd – The project’s base command as returned from :get_base_cxx_command: or :get_base_cc_command:,

as is appropriate for the file being compiled. :type baseCmd: str

Parameters:
  • project (csbuild.projectSettings.projectSettings) – The project currently being compiled, which can be used to retrieve any needed information.
  • forceIncludeFile (str) – Currently unused for precompiled headers.
  • outObj (str) – The object file to be generated by this command
  • inFile (str) – The file being compiled
Returns:

The extended command string, including the base command string

Return type:

str

GetExtraPostPreprocessorFlags()
GetObjExt()

Get the extension for intermediate object files, including the .

GetPchFile(fileName)

Get the properly formatted precompiled header output file for a given header input.

Parameters:fileName (str) – The input header
Returns:The formatted output file (i.e., “header.pch” or “header.gch”)
Return type:str
GetPostPreprocessorSanitationLines()
GetPreprocessCommand(baseCmd, project, inFile)
GetValidArchitectures()

Get the list of architectures supported by this compiler.

Returns:List of architectures
Return type:list[str]
InterruptExitCode()

Get the exit code that the compiler returns if the compile process is interrupted.

Returns:The compiler’s interrupt exit code
Return type:int
PragmaMessage(message)
copy()
parseOutput(outputStr)
postBuildStep(project)
postMakeStep(project)
postPrepareBuildStep(project)
preBuildStep(project)
preLinkStep(project)
preMakeStep(project)
prePrepareBuildStep(project)
class csbuild.toolchain.linkerBase

Bases: csbuild.toolchain.SettingsOverrider

static AdditionalArgs(parser)

Asks for additional command-line arguments to be added by the toolchain.

Parameters:parser (argparse.argument_parser) – A parser for these arguments to be added to
FindLibrary(project, library, libraryDirs, force_static, force_shared)

Search for a library and verify that it is installed.

Parameters:
  • project (csbuild.projectSettings.projectSettings) – The project currently being checked, which can be used to retrieve any needed information.
  • library (str) – The library being searched for
  • libraryDirs (list[str]) – The directories to search for the library in
  • force_static (bool) – Whether or not this library should be forced to link statically
  • force_shared (bool) – Whether or not this library should be forced to link dynamically
Returns:

The location to the library if found, or None

Return type:

str or None

GetDefaultOutputExtension(projectType)

Get the default extension for a given csbuild.ProjectType value.

Parameters:projectType (csbuild.ProjectType) – The requested output type
Returns:The extension, including the . (i.e., .so, .a, .lib, .exe)
Return type:str
GetLinkCommand(project, outputFile, objList)

Retrieves the command to be used for linking for this toolchain.

Parameters:
  • project (csbuild.projectSettings.projectSettings) – The project currently being linked, which can be used to retrieve any needed information.
  • outputFile (str) – The file that will be the result of the link operation.
  • objList (list[str]) – List of objects being linked
Returns:

The fully formatted link command

Return type:

str

GetValidArchitectures()

Get the list of architectures supported by this linker.

Returns:List of architectures
Return type:list[str]
InterruptExitCode()

Get the exit code that the compiler returns if the compile process is interrupted.

Returns:The linker’s interrupt exit code
Return type:int
copy()
parseOutput(outputStr)
postBuildStep(project)
postMakeStep(project)
postPrepareBuildStep(project)
preBuildStep(project)
preLinkStep(project)
preMakeStep(project)
prePrepareBuildStep(project)
class csbuild.toolchain.toolchain

Bases: object

Base class used for custom toolchains To create a new toolchain, inherit from this class, and then use csbuild.RegisterToolchain()

AddCustomTool(name, tool)
Assembler()
Compiler()
GetValidArchitectures()
Linker()
SetActiveTool(name)
Tool(*args)

Perform actions on the listed tools. Examples:

csbuild.Toolchain(“msvc”).Tool(“compiler”, “linker”).SetMsvcVersion(110)

Parameters:args (arbitrary number of strings) – The list of tools to act on
Returns:A proxy object that enables functions to be applied to one or more specific tools.
copy()

Create a deep copy of this toolchain.

Returns:a copy of this toolchain
Return type:toolchain
postBuildStep(project)
postMakeStep(project)
postPrepareBuildStep(project)
preBuildStep(project)
preLinkStep(project)
preMakeStep(project)
prePrepareBuildStep(project)

This Page