csbuild.projectSettings module

ProjectSettings module

Defines the projectSettings class.

var currentProject:  The current project being built. Note that if this is accessed outside of an @project

block, the project returned will only be a temporary variable that will not be valid for compilation :type currentProject: projectSettings

var rootGroup:This is the top-level project group that all projects and project groups fall under.

It has no name and is NOT itself a valid or “real” group. :type rootGroup: ProjectGroup

var currentGroup:  The current group that’s being populated type currentGroup:  ProjectGroup

class csbuild.projectSettings.ProjectGroup(name, parentGroup)

Bases: object

Defines a group of projects, and also may contain subgroups.

Variables:

• tempprojects – Temporary list of projects directly under this group
• projects – Fully fleshed-out list of projects under this group

Dict is { name : { target : project } } :type projects: dict[str, dict[str, projectSettings]]

Variables:

• subgroups – List of child groups
• name – Group name
• parentGroup – The group’s parent group

class csbuild.projectSettings.projectSettings

Bases: object

Contains settings for the project

Variables:

• name – The project’s name
• key – A unique key made by combining project name and target
• workingDirectory – The directory containing all of the project’s files
• linkDepends – The projects that this one depends on for linking
• srcDepends – The projects that this one depends on for compiling
• func – The project’s settings function - the function wrapped in the @project decorator
• libraries – The libraries the project will link against
• staticLibraries – The libraries the project will forcibly statically link against
• sharedLibraries – The libraries the project will forcibly statically link against
• includeDirs – Directories to search for included headers in
• libraryDirs – Directories to search for libraries in
• optLevel – Optimization level for this project
• debugLevel – Debug level for this project
• defines – #define declarations for this project
• undefines – #undef declarations for this project
• cxx – C++ compiler executable for this project
• cc – C compiler executable for this project
• hasCppFiles – Whether or not the project includes C++ files
• objDir – Output directory for intermediate object files
• outputDir – Output directory for the final output file
• csbuildDir – Output directory for csbuild internal data, subdir of objDir
• outputName – Final filename to be generated for this project
• headerInstallSubdir – Subdirectory that headers live in for this project
• sources – Source files within this project that are being compiled during this run
• allsources – All source files within this project
• allheaders – Headers within this project
• type – Project type
• ext – Extension override for output
• profile – Whether or not to optimize for profiling
• cxxCompilerFlags – Literal flags to pass to the C++ compiler
• ccCompilerFlags – Literal flags to pass to the C compiler
• linkerFlags – Literal flags to pass to the linker
• excludeDirs – Directories excluded from source file discovery
• excludeFiles – Files excluded from source file discovery
• _outputDir_set – Whether or not the output directory has been set
• _objDir_set – Whether or not the object directory has been set
• _debugLevel_set – Whether or not debug settings have been set
• _optLevel_set – Whether or not optimization settings have been set
• allPaths – All the paths used to contain all headers included by this project
• chunks – Compiled list of chunks to be compiled in this project
• chunksByFile – Dictionary to get the list of files in a chunk from its filename
• useChunks – Whether or not to use chunks
• chunkTolerance – minimum number of modified files needed to build a chunk as a chunk
• chunkSize – number of files per chunk
• chunkFilesize – maximum file size of a built chunk, in bytes
• chunkSizeTolerance – minimum total filesize of modified files needed to build a chunk as a chunk
• headerRecursionDepth – Depth to recurse when building header information
• ignoreExternalHeaders – Whether or not to ignore external headers when building header information
• defaultTarget – The target to be built when none is specified
• chunkedPrecompile – Whether or not to precompile all headers in the project
• precompile – List of files to precompile
• precompileExcludeFiles – List of files NOT to precompile
• cppHeaderFile – The C++ precompiled header that’s been built (if any)
• cHeaderFile – The C precompiled header that’s been built (if any)
• needsPrecompileCpp – Whether or not the C++ precompiled header needs to be rebuilt during this compile
• needsPrecompileC – Whether or not the C++ precompiled header needs to be rebuilt during this compile
• unity – Whether or not to build in full unity mode (all files included in one translation unit)
• precompileDone – Whether or not the project’s precompile step has been completed
• noWarnings – Whether or not to disable all warnings for this project
• toolchains – All toolchains enabled for this project
• cxxCmd – Base C++ compile command, returned from toolchain.get_base_cxx_command
• ccCmd – Base C compile command, returned from toolchain.get_base_cc_command
• cxxpccmd – Base C++ precompile command, returned from toolchain.get_base_cxx_precompile_command
• ccpccmd – Base C precompile command, returned from toolchain.get_base_cc_precompile_command
• recompileAll – Whether or not conditions have caused the entire project to need recompilation
• targets – List of targets in this project with their associated settings functions, decorated with @target
• targetName – The target name for this project as it’s currently being built
• _finalChunkSet – The list of chunks to be built after building all chunks, determining whether or not to build them as chunks, etc.
• compilationCompleted – The number of files that have been compiled (successfully or not) at this point in the compile process. Note that this variable is modified in multiple threads and should be handled within project.mutex
• compilationFailed – Whether or not ANY compilation unit has failed to successfully compile in this build
• useStaticRuntime – Whether or not to link against a static runtime
• cppHeaders – List of C++ headers
• cHeaders – List of C headers
• activeToolchainName – The name of the currently active toolchain
• activeToolchain – The actual currently active toolchain
• warningsAsErrors – Whether all warnings should be treated as errors
• _builtSomething – Whether or not ANY file has been compiled in this build
• outputArchitecture – The architecture to build against
• libraryLocations – evaluated locations of the project’s libraries
• scriptPath – The location of the script file this project is defined in
• mutex – A mutex used to control modification of project data across multiple threads
• preBuildStep – A function that will be executed before compile of this project begins
• postBuildStep – A function that will be executed after compile of this project ends
• parentGroup – The group this project is contained within
• state – Current state of the project
• startTime – The time the project build started
• endTime – The time the project build ended
• extraFiles – Extra files being compiled, these will be rolled into project.sources, so use that instead
• extraDirs – Extra directories used to search for files
• extraObjs – Extra objects to pass to the linker

Note

Toolchains can define additional variables that will show up on this class’s instance variable list when that toolchain is active. See toolchain documentation for more details on what additional instance variables are available.

AddToSet(key, value)

AppendList(key, value)

CanJoinChunk(chunk, newFile)

ContainsChunk(inputChunkFile)

ExtendList(key, value)

GetAttr(name)

GetAttrNext(name)

RediscoverFiles()

Force a re-run of the file discovery process. Useful if a postPrepareBuild step adds additional files to the project. This will have no effect when called from any place other than a postPrepareBuild step.

SetAttr(name, value)

SetAttrNext(name, value)

SetValue(key, value)

UnionSet(key, value)

UpdateDict(key, value)

class UserData

Bases: object

copy()

projectSettings.check_libraries()

Checks the libraries designated by the make script. Invokes ld to determine whether or not the library exists.1 Uses the -t flag to get its location. And then stores the library’s last modified time to a global list to be used by the linker later, to determine whether or not a project with up-to-date objects still needs to link against new libraries.

projectSettings.copy()

projectSettings.finalizeSettings()

Finalize the settings by applying the settings from the selected toolchain and architecture :return: None

projectSettings.finalizeSettings2()

Extra-finalize the settings by pulling in settings from the project dependency tree :return: None

projectSettings.follow_headers(headerFile, allheaders)

Follow the headers in a file. First, this will check to see if the given header has been followed already. If it has, it pulls the list from the allheaders global dictionary and returns it. If not, it populates a new allheaders list with follow_headers2, and then adds that to the allheaders dictionary

projectSettings.follow_headers2(headerFile, allheaders, n, parent)

More intensive, recursive, and cpu-hogging function to follow a header. Only executed the first time we see a given header; after that the information is cached.

projectSettings.get_chunk(srcFile)

Retrieves the chunk that a given file belongs to.

projectSettings.get_files(sources=None, headers=None, cHeaders=None)

Steps through the current directory tree and finds all of the source and header files, and returns them as a list. Accepts two lists as arguments, which it populates. If sources or headers are excluded from the parameters, it will ignore files of the relevant types.

projectSettings.get_full_path(headerFile, relativeDir)

projectSettings.get_included_files(headerFile)

projectSettings.make_chunks(l)

Converts the list into a list of lists - i.e., “chunks” Each chunk represents one compilation unit in the chunked build system.

projectSettings.name = None

Type:str

Project name

projectSettings.precompile_headers()

projectSettings.prepareBuild()

projectSettings.save_md5(inFile)

projectSettings.save_md5s(sources, headers)

projectSettings.should_recompile(srcFile, ofile=None, for_precompiled_header=False)

Checks various properties of a file to determine whether or not it needs to be recompiled.