checkout_add_archive()

def checkout_add_archive(name, url, sha256, link, includes, excludes, strip_prefix, add_prefix, filename, platforms, type, headers, custom_headers, deps)

Adds an archive to the workspace.

The archive is downloaded to the spaces store and hard-linked to the workspace.

Args

• name - str The name of the rule.
• url - str The URL of the archive to download.
• sha256 - str The SHA256 checksum of the archive.
• link - Hard | None
• includes - [str] List of globs to include.
• excludes - [str] List of globs to exclude.
• strip_prefix - str Prefix to strip from the archive.
• add_prefix - str Prefix to add to the archive.
• filename - str The filename if it isn’t the last part of the URL
• platforms - [str] List of platforms to add the archive to.
• type - str use checkout_type_optional() to skip rule checkout
• headers - dict key-value pairs of headers to use when downloading the archive.
• custom_headers -
• deps - [str] List of dependencies for the rule.

checkout_add_asset()

def checkout_add_asset(name, content, destination, deps, type, platforms)

Adds an asset to the workspace.

This will create a file in the workspace with the given content as string value.

Args

• name - str The name of the rule.
• content - str The content of the file to create.
• destination - str The destination path for the file.
• deps - [str] List of dependencies for the rule.
• type - str use checkout_type_optional() to skip rule checkout
• platforms - [str] List of platforms to add the archive to.

checkout_add_cargo_bin()

def checkout_add_cargo_bin(name, crate, version, bins, deps, type, platforms)

Adds a cargo binary to the workspace.

Args

• name - The name of the rule.
• crate - The name of the crate.
• version - The version of the crate.
• bins - List of binaries to add.
• deps - [str] List of dependencies for the rule.
• type - str use checkout_type_optional() to skip rule checkout
• platforms - [str] List of platforms to add the archive to.

checkout_add_compile_commands_dir()

def checkout_add_compile_commands_dir(name, path, rule)

Registers a build directory in the compile_commands.spaces.json file.

Args

• name - str The name of the rule.
• path - str The path to the build directory where compile_commands.json will be found.
• rule -

checkout_add_hard_link_asset()

def checkout_add_hard_link_asset(name, source, destination, deps, type, platforms)

Adds a hard link asset to the workspace.

Args

• name - The name of the rule.
• source - The source path of the asset.
• destination - The destination path for the asset.
• deps - [str] List of dependencies for the asset.
• type - str use checkout_type_optional() to skip rule checkout
• platforms - [str] List of platforms to add the archive to.

checkout_add_oras_archive()

def checkout_add_oras_archive(name, url, artifact, tag, add_prefix, manifest_digest_path, manifest_artifact_path, globs, deps, type, platforms)

Adds an oras archive to the workspace.

Args

• name - str The name of the rule.
• url - str The URL of the oras archive to download.
• artifact - str The artifact name of the oras archive.
• tag - str The tag of the oras archive.
• add_prefix - str The prefix to add to the archive.
• manifest_digest_path - str The path to the manifest digest in the oras archive.
• manifest_artifact_path - str The path to the manifest artifact in the oras archive.
• globs - List of globs to include/exclude.
• deps - [str] List of dependencies for the rule.
• type - str use checkout_type_optional() to skip rule checkout
• platforms - [str] List of platforms to add the archive to.

checkout_add_platform_archive()

def checkout_add_platform_archive(name, platforms, deps, type)

Adds a platform archive to the checkout.

Platform archives are used to add binary tools based on the host platform.

Args

• name - str The name of the rule.
• platforms - [str] List of platforms to add the archive to.
• deps - [str] List of dependencies for the rule.
• type - str use checkout_type_optional() to skip rule checkout

checkout_add_repo()

def checkout_add_repo(name, url, rev, checkout_type, clone, is_evaluate_spaces_modules, sparse_mode, sparse_list, working_directory, platforms, type, deps)

Clones a repository and checks it out at a specific revision.

The for clone=checkout_clone_default() | checkout_clone_blobless(), the repo is cloned first to the store and then copied to the workspace. If the filesystem supports copy-on-write (COW) semantics, COW semantics are used to copy from the store to the workspace.

Example:

checkout_add_repo(
    "spaces",
    url = "https://github.com/work-spaces/spaces",
    rev = "main"
)

Args

• name - str The name of the rule. This is also the location of the new repo in the workspace.
• url - str The git repository URL to clone
• rev - str The branch or commit hash to checkout
• checkout_type - enum Revision
• clone - enum checkout_clone_default() | checkout_clone_blobless() | checkout_clone_worktree()
• is_evaluate_spaces_modules - bool Whether to evaluate spaces.star files in the repo (default is True).
• sparse_mode - enum Cone | NoCone
• sparse_list - [str] List of paths to include/exclude
• working_directory - str The working directory to clone the repository into.
• platforms - [str] List of platforms to add the repo to.
• type - str use checkout_type_optional() to skip rule checkout
• deps - [str] List of dependencies for the rule.

checkout_add_soft_link_asset()

def checkout_add_soft_link_asset(name, source, destination, deps, type, platforms)

Adds a soft link asset to the workspace.

Args

• name - str The name of the rule.
• source - str The source path of the soft link.
• destination - str The relative workspace path of the soft link destination.
• deps - [str] List of dependencies for the asset.
• type - str use checkout_type_optional() to skip rule checkout
• platforms - [str] List of platforms to add the archive to.

checkout_add_target()

def checkout_add_target(name, deps, type, platforms)

Adds a target to the workspace.

Args

• name - str The name of the rule.
• deps - [str] List of dependencies for the target.
• type - str use checkout_type_optional() to skip rule checkout
• platforms - [str] List of platforms to add the archive to.

checkout_add_which_asset()

def checkout_add_which_asset(name, which, destination, deps, platforms, type)

Adds an asset to the destintion based on the which command.

Using this function creates system dependencies that may not be reproducible across different systems.

Args

• name - The name of the rule.
• which - The name of the asset to add.
• destination - The destination path for the asset.
• deps - [str] List of dependencies for the asset.
• platforms - [str] List of platforms to add the archive to.
• type - str use checkout_type_optional() to skip rule checkout

checkout_clone_blobless()

def checkout_clone_blobless()

Use checkout_add_repo(clone = checkout_clone_blobless()) to filter unused files from the repository history.

Returns

str: CHECKOUT_CLONE_BLOBLESS

checkout_clone_default()

def checkout_clone_default()

Use checkout_add_repo(clone = checkout_clone_default()) for a normal git clone.

Returns

str: CHECKOUT_CLONE_DEFAULT

checkout_clone_shallow()

def checkout_clone_shallow()

Use checkout_add_repo(clone = checkout_clone_shallow()) for a shallow clone. Note: The rev must be a branch, not a tag or commit.

Returns

str: CHECKOUT_CLONE_SHALLOW

checkout_clone_worktree()

def checkout_clone_worktree()

Use checkout_add_repo(clone = checkout_clone_worktree()) to store the bare repository in the spaces store.

Returns

str: CHECKOUT_CLONE_WORKTREE

checkout_get_compile_commands_spaces_name()

def checkout_get_compile_commands_spaces_name()

Returns the name of the file used with checkout_add_compile_commands_dir().

This is used internally between the checkout rule and compile_commands_merge()

checkout_sparse_mode_cone()

def checkout_sparse_mode_cone()

Use checkout_add_repo(sparse_mode = checkout_sparse_mode_cone()) for sparse cone mode.

Returns

str: CHECKOUT_SPARSE_MODE_CONE

checkout_sparse_mode_no_cone()

def checkout_sparse_mode_no_cone()

Use checkout_add_repo(sparse_mode = checkout_sparse_mode_no_cone()) for sparse no-cone mode. This mode uses gitignore-like expressions for sparse checkout.

Returns

str: CHECKOUT_SPARSE_MODE_NO_CONE

checkout_type_default()

def checkout_type_default()

Use checkout_add_repo(type = checkout_type_default()) to use default checkout behavior

Returns

None: CHECKOUT_TYPE_DEFAULT

checkout_type_optional()

def checkout_type_optional()

Use checkout_add_repo(type = checkout_type_optional()) to skip checkout

Returns

str: CHECKOUT_TYPE_OPTIONAL

checkout_update_asset()

def checkout_update_asset(name, destination, value, format, deps, type, platforms)

Updates an asset in the workspace.

This rule will merge the data of an existing JSON, TOML, or YAML file with the given value.

Args

• name - The name of the rule.
• destination - The destination path for the asset.
• value - The value of the asset as a dict to merge with the existing file.
• format - The format of the asset (json | toml | yaml). Default will get extension from destination.
• deps - [str] List of dependencies for the asset.
• type - str use checkout_type_optional() to skip rule checkout
• platforms - [str] List of platforms to add the archive to.

checkout_update_env()

def checkout_update_env(name, vars, paths, system_paths, inherited_vars, optional_inherited_vars, deps, type, platforms)

Updates the environment with the given variables and paths.

Variables other than PATH are added as a hash map. PATH is added as a list of values. The order of the PATHS is based on execution order which can be controlled using deps. The system_paths are added after the paths values.

Args

• name - str The name of the rule.
• vars - dict Dictionary of environment variables to set.
• paths - [str] List of paths to add to the PATH.
• system_paths - [str] The path to add to the system PATH.
• inherited_vars - List of environment variables to inherit from the calling environment.
• optional_inherited_vars - List of environment variables to inherit from the calling environment if they are not already set (requires spaces >v0.15.1)
• deps - [str] List of dependencies for the rule.
• type - str use checkout_type_optional() to skip rule checkout
• platforms - [str] List of platforms to add the archive to.

checkout_update_shell()

def checkout_update_shell(name, shell_path, args, deps)

Updates the workspace shell configuration that is used with spaces shell

Args

• name - str The name of the rule.
• shell_path - str The path to the shell executable.
• args - list The arguments to pass to the shell.
• deps - list The dependencies of the rule (allows controlling order of updating the file)

checkout_update_shell_shortcuts()

def checkout_update_shell_shortcuts(name, shortcuts, deps)

Updates the .spaces/shell/shortcuts.sh file with shell functions. This file can be source when starting the shell.

Args

• name - str The name of the rule.
• shortcuts - dict A dictionary of function names (key) and shell commands to execute (values).
• deps - list A list of dependencies that allows override of shortcuts.

checkout_update_shell_startup()

def checkout_update_shell_startup(name, script_name, contents, env_name, deps)

Updates the workspace shell configuration that is used with spaces shell

Args

• name - str The name of the rule.
• script_name - str The name of the startup file to generate and store at .spaces/shell/<script_name> in the workspace.
• contents - str The contents of the startup file.
• env_name - str If not None, this will be set to point to the workspace shell startup directory .spaces/shell.
• deps - list The dependencies of the rule (allows controlling order of updating the file)

update_platforms_prefix()

def update_platforms_prefix(platforms, add_prefix)

Updates the prefix of the platforms.

Args

• platforms - [str] List of platforms to add the archive to.
• add_prefix - The prefix to set.

Returns

An updated list of platforms.