Attention
To support CSBuild’s operation, Python’s import lock is DISABLED once CSBuild has started.
This should not be a problem for most makefiles, but if you do any threading within your makefile, take note: anything that’s imported and used by those threads should always be implemented on the main thread before that thread’s execution starts. Otherwise, CSBuild does not guarantee that the import will have completed once that thread tries to use it. Long story short: Don’t import modules within threads.
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 framworks 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.
| Parameters: | args (an arbitrary number of strings) – The list of directories to be searched. |
|---|
Add frameworks for Objective-C/C++ compilations.
| Parameters: | args (an arbitrary number of strings) – The list of libraries 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 |
|---|
Adds an option to the argument parser. The syntax for this is identical to the ArgParse add_argument syntax; see the :argparse: documentation
Include the given makefile script as part of this build process.
Attention
The included file will be loaded in the current file’s namespace, not a new namespace.
This doesn’t work the same way as importing a module. Any functions or variables defined in the current module will be available to the called script, and anything defined in the called script will be available to the calling module after it’s been called. As a result, this can be used much like #include in C++ to pull in utility scripts in addition to calling makefiles. The result is essentially as if the called script were copied and pasted directly into this one in the location of the AddScript() call.
| Parameters: | incFile (str) – path to an additional makefile script to call as part of this build |
|---|
Similar to csbuild.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.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.
Clear the list of defined preprocessor directives
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 include directories
Clears the list of libraries
Clears the library directories
Clears the list of literal linker flags.
Clears the list of dynamically-linked libraries
Clears the list of statically-linked libraries
Clear the list of undefined preprocessor directives
Bases: object
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
Enables installation of the compiled output file. The default installation directory is /usr/local/lib.
Optimize output for profiling
Turns on true unity builds, combining all files into only one compilation unit.
Promote all warnings to errors.
Gets the default argument for the requested option
| Parameters: | argname (str) – the name of the option |
|---|
Gets all of the arguments parsed by the argument parser.
| Returns: | an argparse.Namespace object |
|---|---|
| Return type: | argparse.Namespace |
Retrieve the given option from the parsed command line arguments.
| Parameters: | option (str) – The name of the option, without any preceding dashes. |
|---|
ArgParse replaces dashes with underscores, but csbuild will accept dashes and automatically handle the conversion internally.
| Returns: | The given argument, if it exists. If the argument has never been specified, returns csbuild.ARG_NOT_SET. |
|---|
If –help has been specified, this will ALWAYS return csbuild.ARG_NOT_SET for user-specified arguments. Handle csbuild.ARG_NOT_SET to prevent code from being unintentionally run with –help.
Get the list of targets currently being built.
If no target has been specified (the default is being used), this list is empty.
| Returns: | The list of targets |
|---|---|
| Return type: | list[str] |
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.
Bases: object
Link against a dynamic C/C++ runtime library.
Link against a static C/C++ runtime library.
Disable the built-in “debug” and “release” targets.
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. |
|---|
Bases: object
Specifies the type of project to compile
Register a new project generator for use in solution generation.
| Parameters: |
|
|---|
Register a new toolchain for use in the project.
| Parameters: |
|
|---|
Bases: object
Sets the active toolchain to be used when building the project.
On Windows platforms, this is set to msvc by default. On Linux platforms, this is set to gcc by default.
This will be overridden if the script is executed with the –toolchain option.
| Parameters: | name (str) – The toolchain to use to build the project |
|---|
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 |
|---|
Please see detailed description.
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 (DebugLevel) – How (and if) symbols should be generated |
|---|
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 (OptimizationLevel) – The level of optimization to use |
|---|
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 (str) – The desired architecture. Choose from x86, x64, ARM. |
|---|
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.LinkLibs:. 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.
Specifies the toolchains that this project supports. This can be used to limit –all-toolchains from building everything supported by csbuild, if the project is not set up to support all of the toolchains.
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: |
|---|
Default debug target.
Default release target.
Bases: object
Stop compilation when the first error is encountered.
Perform actions on the listed toolchains. Examples:
csbuild.Toolchain(“gcc”).NoPrecompile() csbuild.Toolchain(“gcc”, “msvc”).EnableWarningsAsErrors()
| Parameters: | args (arbitrary number of strings) – The list of toolchains to act on |
|---|---|
| Returns: | A proxy object that enables functions to be applied to one or more specific toolchains. |
Specifies settings for a specific list of architectures.
Specifies settings that affect a single specific file
| Parameters: |
|
|---|
Decorator that creates a post-build step for the containing project. Post-build steps run after the project has successfully compiled and linked.
| Parameters: | func ((Implicit) function) – (Implicit) The function wrapped by this decorator |
|---|
Note
The function this wraps should take a single argument, which will be of type csbuild.projectSettings.projectSettings.
Decorator that creates a post-make step for the containing project. Post-make steps run after all projects have finished building and linking. This step will only run if the entire build process was successful.
| Parameters: | func ((Implicit) function) – (Implicit) The function wrapped by this decorator |
|---|
Note
The function this wraps should take a single argument, which will be of type csbuild.projectSettings.projectSettings.
Decorator that creates a post-compile step for the containing project. Post-PrepareBuild steps run just after the project completes its build preparation. This is the only place where running project.RediscoverFiles() has any appreciable effect.
| Parameters: | func ((Implicit) function) – (Implicit) The function wrapped by this decorator |
|---|
Note
The function this wraps should take a single argument, which will be of type csbuild.projectSettings.projectSettings.
Decorator that creates a pre-build step for the containing project. Pre-build steps run just before the project begins compiling.
| Parameters: | func ((Implicit) function) – (Implicit) The function wrapped by this decorator |
|---|
Note
The function this wraps should take a single argument, which will be of type csbuild.projectSettings.projectSettings.
Decorator that creates a pre-link step for the containing project. Pre-link steps run after a successful compile of the project, but before the project links.
| Parameters: | func ((Implicit) function) – (Implicit) The function wrapped by this decorator |
|---|
Note
The function this wraps should take a single argument, which will be of type csbuild.projectSettings.projectSettings.
Decorator that creates a pre-make step for the containing project. Pre-make steps run after all projects’ preparation steps have completed and their final chunk sets have been collected, but before any compiling starts.
| Parameters: | func ((Implicit) function) – (Implicit) The function wrapped by this decorator |
|---|
Note
The function this wraps should take a single argument, which will be of type csbuild.projectSettings.projectSettings.
Decorator that creates a pre-build step for the containing project. Pre-PrepareBuild steps run just before the project begins preparing its build tasks.
| Parameters: | func ((Implicit) function) – (Implicit) The function wrapped by this decorator |
|---|
Note
The function this wraps should take a single argument, which will be of type csbuild.projectSettings.projectSettings.
Decorator used to declare a project. linkDepends and srcDepends here will be used to determine project build order.
| Parameters: |
|---|
(or a subdirectory) should contain the project’s source files.
| Parameters: | linkDepends – A list of other projects. This project will not be linked until the dependent projects |
|---|
have completed their build process. These can be specified as either projName, Link(projName, scope), or Src(projName, scope).
projName will be converted to Link(projName, ScopeDef.Final) Link will cause the project it applies to to link this dependency. Src will cause the project it applies to to wait until this project finishes before it starts its build at all.
Specifies a grouping of projects. This will add scope to the global project settings, and will additionally be used in solution generation to group the projects.
| Parameters: | name (str) – The name to identify this project group |
|---|
Specifies settings for a target. If the target doesn’t exist it will be implicitly created. If a target does exist with this name, this function will be appended to a list of functions to be run for that target name, unless override is True.
| Parameters: |
|---|