Project

The project is the primary SBuildr’s primary interface. It keeps track of all source files, and project targets.

class sbuildr.Project(root: str = None, dirs: Set[str] = {}, build_dir: str = None)
PROJECT_API_VERSION = 1

Represents a project. Projects include two default profiles with the following configuration: release: BuildFlags().O(3).std(17).march("native").fpic() debug: BuildFlags().O(0).std(17).debug().fpic().define("S_DEBUG"), attaches file suffix “_debug” These can be overridden using the profile() function.

Parameters:
  • root – The path to the root directory for this project. All directories and files within the root directory are considered during searches for files. If no root directory is provided, defaults to the containing directory of the script calling this constructor.
  • dirs – Additional directories outside the root directory that are part of the project. These directories and all contents will be considered during searches for files.
  • build_dir – The build directory to use. If no build directory is provided, a directory named ‘build’ is created in the root directory.
build(targets: List[sbuildr.project.target.ProjectTarget] = None, profile_names: List[str] = None) → float

Builds the specified targets for this project. Configuration should be run prior to calling this function.

Parameters:
  • targets – The targets to build. Defaults to all targets.
  • profile_names – The profiles for which to build the targets. Defaults to all profiles.
Returns:

Time elapsed during the build.
clean(profile_names: List[str] = None, nuke: bool = False, dry_run: bool = True)

Removes build directories and project artifacts.

Parameters:
  • profile_names – The profiles for which to remove build directories. Defaults to all profiles.
  • nuke – Whether to remove all build directories associated with the project, including profile build directories.
  • dry_run – Whether this is a dry-run, in which case SBuildr will only display which directories would be removed rather than removing them. Defaults to True.
configure(targets: List[sbuildr.project.target.ProjectTarget] = None, profile_names: List[str] = None, BackendType: type = <class 'sbuildr.backends.rbuild.RBuildBackend'>) → None

Configure does 3 things: 1. Finds dependencies for the specified targets. This involves potentially fetching and building dependencies if they do not exist in the cache. 2. Configures the project’s build graph after discovering libraries for targets. Before calling configure(), a target’s libs/lib_dirs lists are not guaranteed to be complete. 3. Configure the project for build using the specified backend type. This includes generating any build configuration files required by this project’s backend.

This function must be called prior to building.

Parameters:
  • targets – The targets for which to configure the project. Defaults to all targets.
  • profile_names – The names of profiles for which to configure the project. Defaults to all profiles.
  • BackendType – The type of backend to use. Since SBuildr is a meta-build system, it can support multiple backends to perform builds. For example, RBuild (i.e. sbuildr.backends.RBuildBackend) can be used for fast incremental builds. Note that this should be a type rather than an instance of a backend.
executable(name: str, sources: List[str], flags: sbuildr.tools.flags.BuildFlags = <sbuildr.tools.flags.BuildFlags object>, libs: List[Union[sbuildr.dependencies.dependency.DependencyLibrary, sbuildr.project.target.ProjectTarget, sbuildr.graph.node.Library]] = [], compiler: sbuildr.tools.compiler.Compiler = <sbuildr.tools.compiler.Compiler object>, include_dirs: List[str] = [], linker: sbuildr.tools.linker.Linker = <sbuildr.tools.linker.Linker object>, depends: List[sbuildr.dependencies.dependency.Dependency] = [], internal=False) → sbuildr.project.target.ProjectTarget

Adds an executable target to all profiles within this project.

Parameters:
  • name – The name of the target. This should NOT include platform-dependent extensions.
  • sources – A list of names or paths of source files to include in this target.
  • flags – Compiler and linker flags. See sbuildr.BuildFlags for details.
  • libs – A list containing either ProjectTarget s, DependencyLibrary s or Library s.
  • compiler – The compiler to use for this target. Defaults to clang.
  • include_dirs – A list of paths for preprocessor include directories. These directories take precedence over automatically deduced include directories.
  • linker – The linker to use for this target. Defaults to clang.
  • depends – Any additional dependencies not already captured in libs. This may include header only packages for example.
  • internal – Whether this target is internal to the project, in which case it will not be installed.
Returns:

sbuildr.project.target.ProjectTarget
find(path) → str

Attemps to locate a path in the project. If no paths were found, or multiple ambiguous paths were found, raises an exception.

Parameters:path – The path to find. This may be an absolute path, partial path, or file/directory name.
Returns:An absolute path to the matching file or directory.
install(targets: List[sbuildr.project.target.ProjectTarget] = None, profile_names: List[str] = None, headers: List[str] = None, header_install_path: str = '/usr/local/include', library_install_path: str = '/usr/local/lib', executable_install_path: str = '/usr/local/bin', dry_run: bool = True)

Install the specified targets for the specified profiles.

Parameters:
  • targets – The targets to install. Defaults to all non-internal project targets.
  • profile_names – The profiles for which to install. Defaults to the “release” profile.
  • headers – The headers to install. Defaults to all headers that are part of the interface as per interfaces() .
  • header_install_path – The path to which to install headers. This defaults to one of the default locations for the host OS.
  • library_install_path – The path to which to install libraries. This defaults to one of the default locations for the host OS.
  • executable_install_path – The path to which to install executables. This defaults to one of the default locations for the host OS.
  • dry_run – Whether to perform a dry-run only, with no file copying. Defaults to True.
install_profile() → str

Returns the name of the profile for which this project will install targets.

install_targets() → List[sbuildr.project.target.ProjectTarget]

Returns all targets that this project can install.

Returns:A list of targets.
interfaces(headers: List[str], depends: List[sbuildr.dependencies.dependency.Dependency] = []) → List[str]

Specifies headers that are part of this project’s public interface. When running the install command on the CLI, the headers specified via this function will be copied to installation directories.

Parameters:headers – A list of paths to a public headers.
Returns:The absolute paths of the discovered headers.
library(name: str, sources: List[str], flags: sbuildr.tools.flags.BuildFlags = <sbuildr.tools.flags.BuildFlags object>, libs: List[Union[sbuildr.dependencies.dependency.DependencyLibrary, sbuildr.project.target.ProjectTarget, sbuildr.graph.node.Library]] = [], compiler: sbuildr.tools.compiler.Compiler = <sbuildr.tools.compiler.Compiler object>, include_dirs: List[str] = [], linker: sbuildr.tools.linker.Linker = <sbuildr.tools.linker.Linker object>, depends: List[sbuildr.dependencies.dependency.Dependency] = [], internal=False) → sbuildr.project.target.ProjectTarget

Adds a library target to all profiles within this project.

Parameters:
  • name – The name of the target. This should NOT include platform-dependent extensions.
  • sources – A list of names or paths of source files to include in this target.
  • flags – Compiler and linker flags. See sbuildr.BuildFlags for details.
  • libs – A list containing either ProjectTarget s, DependencyLibrary s or Library s.
  • compiler – The compiler to use for this target. Defaults to clang.
  • include_dirs – A list of paths for preprocessor include directories. These directories take precedence over automatically deduced include directories.
  • linker – The linker to use for this target. Defaults to clang.
  • depends – Any additional dependencies not already captured in libs. This may include header only packages for example.
  • internal – Whether this target is internal to the project, in which case it will not be installed.
Returns:

sbuildr.project.target.ProjectTarget
run(targets: List[sbuildr.project.target.ProjectTarget], profile_names: List[str] = []) → None

Runs targets from this project.

Parameters:
  • targets – The targets to run.
  • profile_names – The profiles for which to run the targets.
run_tests(targets: List[sbuildr.project.target.ProjectTarget] = None, profile_names: List[str] = None)

Run tests from this project. Runs all tests from the project for all profiles by default.

Parameters:
  • targets – The test targets to run. Raises an exception if the target is not a test target.
  • profile_names – The profiles for which to run the tests. Defaults to all profiles.
test(name: str, sources: List[str], flags: sbuildr.tools.flags.BuildFlags = <sbuildr.tools.flags.BuildFlags object>, libs: List[Union[sbuildr.dependencies.dependency.DependencyLibrary, sbuildr.project.target.ProjectTarget, sbuildr.graph.node.Library]] = [], compiler: sbuildr.tools.compiler.Compiler = <sbuildr.tools.compiler.Compiler object>, include_dirs: List[str] = [], linker: sbuildr.tools.linker.Linker = <sbuildr.tools.linker.Linker object>, depends: List[sbuildr.dependencies.dependency.Dependency] = []) → sbuildr.project.target.ProjectTarget

Adds an executable target to all profiles within this project. Test targets can be automatically built and run by using the test command on the CLI.

Parameters:
  • name – The name of the target. This should NOT include platform-dependent extensions.
  • sources – A list of names or paths of source files to include in this target.
  • flags – Compiler and linker flags. See sbuildr.BuildFlags for details.
  • libs – A list containing either ProjectTarget s, DependencyLibrary s or Library s.
  • compiler – The compiler to use for this target. Defaults to clang.
  • include_dirs – A list of paths for preprocessor include directories. These directories take precedence over automatically deduced include directories.
  • linker – The linker to use for this target. Defaults to clang.
  • depends – Any additional dependencies not already captured in libs. This may include header only packages for example.
Returns:

sbuildr.project.target.ProjectTarget
test_targets() → List[sbuildr.project.target.ProjectTarget]

Returns all targets in this project that are tests.

Returns:A list of targets.
uninstall(targets: List[sbuildr.project.target.ProjectTarget] = None, profile_names: List[str] = None, headers: List[str] = None, header_install_path: str = '/usr/local/include', library_install_path: str = '/usr/local/lib', executable_install_path: str = '/usr/local/bin', dry_run: bool = True)

Uninstall the specified targets for the specified profiles.

Parameters:
  • targets – The targets to uninstall. Defaults to all non-internal project targets.
  • profile_names – The profiles for which to uninstall. Defaults to the “release” profile.
  • headers – The headers to uninstall. Defaults to all headers that are part of the interface as per interfaces() .
  • header_install_path – The path from which to uninstall headers. This defaults to one of the default locations for the host OS.
  • library_install_path – The path from which to uninstall libraries. This defaults to one of the default locations for the host OS.
  • executable_install_path – The path from which to uninstall executables. This defaults to one of the default locations for the host OS.
  • dry_run – Whether to perform a dry-run only, with no file copying. Defaults to True.