Toolchain Module
Defines the base class for creating custom toolchains
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]
Bases: object
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 |
---|
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 |
---|
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 |
---|
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 |
---|
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. |
---|
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. |
---|
Adds additional directories to search for files in.
Parameters: | args (an arbitrary number of strings) – A list of directories to search. |
---|
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. |
---|
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. |
---|
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. |
---|
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. |
---|
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. |
---|
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. |
---|
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. |
---|
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 |
---|
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. |
---|
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. |
---|
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 |
---|
Clears the list of literal C compiler flags.
Clears the explicitly set list of chunks and returns the behavior to the default.
Clears the list of literal compiler flags.
Clears the list of literal C++ compiler flags.
clears the list of defines
Clear the list of external directories to search.
Clear the list of external files to compile.
Clear the list of external objects to link.
Clears the framework directories, including the defaults.
Clears the list of framworks
Clears the include directories, including the defaults.
Clears the library directories, including the defaults
Clears the list of libraries
Clears the list of literal linker flags.
Clears the list of libraries
Clears the list of libraries
clears the list of undefines
Turn off the chunked/unity build system and build using individual files.
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.
Turns profiling optimizations back off
Disables all warnings.
Disable the promotion of warnings to errors.
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 |
---|
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: |
---|
Turn chunked/unity build on and build using larger compilation units. This is the default.
When this is enabled, all header files will be precompiled into a single “superheader” and included in all files.
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.
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.
Optimize output for profiling
Turns on true unity builds, combining all files into only one compilation unit.
Promote all warnings to errors.
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.
Link against a dynamic C/C++ runtime library.
Link against a static C/C++ runtime library.
Explicit list of header files to precompile. Disables chunk precompile when called.
Parameters: | args (an arbitrary number of strings) – The files to precompile. |
---|
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. |
---|
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 |
---|
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. |
---|
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.
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 |
---|
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. |
---|
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. |
---|
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.
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 |
---|
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. |
---|
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. |
---|
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 |
---|
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. |
---|
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. |
---|
Set the output architecture.
Parameters: | arch (ArchitectureType) – The desired architecture. |
---|
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. |
---|
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” ) |
---|
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 |
---|
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.
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: |
---|
Bases: csbuild.toolchain.SettingsOverrider
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 |
---|
Retrieves the BASE C compiler command for this project.
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 |
Retrieves the BASE C compiler command for precompiling headers in this project.
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 |
Retrieves the BASE C++ compiler command for this project.
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 |
Retrieves the BASE C++ compiler command for precompiling headers in this project.
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 |
Retrieves the EXTENDED C/C++ compiler command for compiling a specific file
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: |
|
---|---|
Returns: | The extended command string, including the base command string |
Return type: | str |
Retrieves the EXTENDED C/C++ compiler command for compiling a specific precompiled header
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: |
|
---|---|
Returns: | The extended command string, including the base command string |
Return type: | str |
Get the extension for intermediate object files, including the .
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 |
Get the list of architectures supported by this compiler.
Returns: | List of architectures |
---|---|
Return type: | list[str] |
Get the exit code that the compiler returns if the compile process is interrupted.
Returns: | The compiler’s interrupt exit code |
---|---|
Return type: | int |
Bases: csbuild.toolchain.SettingsOverrider
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 |
---|
Search for a library and verify that it is installed.
Parameters: |
|
---|---|
Returns: | The location to the library if found, or None |
Return type: | str or None |
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 |
Retrieves the command to be used for linking for this toolchain.
Parameters: |
|
---|---|
Returns: | The fully formatted link command |
Return type: | str |
Get the list of architectures supported by this linker.
Returns: | List of architectures |
---|---|
Return type: | list[str] |
Get the exit code that the compiler returns if the compile process is interrupted.
Returns: | The linker’s interrupt exit code |
---|---|
Return type: | int |
Bases: object
Base class used for custom toolchains To create a new toolchain, inherit from this class, and then use csbuild.RegisterToolchain()
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. |
Create a deep copy of this toolchain.
Returns: | a copy of this toolchain |
---|---|
Return type: | toolchain |