checkout_add_any_assets()

def checkout_add_any_assets(name, assets, deps, type, platforms, visibility)

Adds a list of any assets to the workspace as a single rule.

assets should be a list of dicts. Use asset.star: asset_hard_link(), asset_soft_link(), etc to create the entries.

Args

• name: string: The name of the rule.
• assets: list: A list of dict’s that define assets to add.
• deps: list: List of dependencies for the rule.
• type: use checkout_type_optional() to skip rule checkout
• platforms: List of platforms rule applies to.
• visibility: Rule visibility: Public|Private|Rules[]. See visbility.star for more info.

checkout_add_archive()

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

Adds an archive to the workspace.

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

Args

• name: string: The name of the rule.
• url: string: The URL of the archive to download.
• sha256: string: The SHA256 checksum of the archive.
• link: string: Hard | None
• includes: List of globs to include.
• excludes: List of globs to exclude.
• strip_prefix: Prefix to strip from the archive.
• add_prefix: string: Prefix to add to the archive.
• filename: The filename if it isn’t the last part of the URL
• platforms: List of platforms to add the archive to.
• type: use checkout_type_optional() to skip rule checkout
• headers: key-value pairs of headers to use when downloading the archive.
• deps: list: List of dependencies for the rule.
• visibility: Rule visibility: Public|Private|Rules[]. See visbility.star for more info.

checkout_add_asset()

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

Adds an asset to the workspace.

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

Args

• name: string: The name of the rule.
• content: string: The content of the file to create.
• destination: string: The destination path for the file.
• deps: list: List of dependencies for the rule.
• type: use checkout_type_optional() to skip rule checkout
• platforms: List of platforms to add the archive to.
• visibility: Rule visibility: Public|Private|Rules[]. See visbility.star for more info.

checkout_add_cargo_bin()

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

Adds a cargo binary to the workspace.

Args

• name: string: The name of the rule.
• crate: string: The name of the crate.
• version: string: The version of the crate.
• bins: list: List of binaries to add.
• deps: list: List of dependencies for the rule.
• type: use checkout_type_optional() to skip rule checkout
• platforms: List of platforms to add the archive to.
• visibility: Rule visibility: Public|Private|Rules[]. See visbility.star for more info.

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: string: The name of the checkout rule.
• path: string: The path to the build directory where compile_commands.json will be found.
• rule: string: The name of the rule that is associated with creating the compile_command.json file.

checkout_add_env_vars()

def checkout_add_env_vars(name, vars, deps, type, platforms, visibility)

Adds environment variables to the workspace.

Args

• name: string: Name of the checkout rule
• vars: list: list of env objects from env.star
• deps: list: List of dependencies for the rule.
• type: use checkout_type_optional() to skip rule checkout
• platforms: List of platforms rule applies to.
• visibility: Rule visibility: Public|Private|Rules[]. See visbility.star for more info.

checkout_add_exec()

def checkout_add_exec(name, command, help, args, env, deps, working_directory, platforms, log_level, redirect_stdout, timeout, visibility, expect)

Adds a command to the run dependency graph

Args

• name: string: The name of the rule.
• command: string: The command to execute.
• help: The help message for the rule.
• args: list: The arguments to pass to the command.
• env: dict: key value pairs of environment variables
• deps: list: The rule dependencies that must be run before this command
• working_directory: The directory to run the command (default is workspace root).
• platforms: Platforms to run on (default is all).
• log_level: The log level to use None|App|Passthrough
• redirect_stdout: The file to redirect stdout to (prefer to parse the log file).
• timeout: Number of seconds to run before sending a kill signal.
• visibility: Rule visibility: Public|Private|Rules[]. See visbility.star for more info.
• expect: string: The expected result of the command Success|Failure|Any. (default is Success)

checkout_add_hard_link_asset()

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

Adds a hard link asset to the workspace.

Args

• name: string: The name of the rule.
• source: string: The source path of the asset.
• destination: string: The destination path for the asset.
• deps: list: List of dependencies for the asset.
• type: use checkout_type_optional() to skip rule checkout
• platforms: List of platforms to add the archive to.
• visibility: Rule visibility: Public|Private|Rules[]. See visbility.star for more info.

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, visibility)

Adds an oras archive to the workspace.

Args

• name: string: The name of the rule.
• url: string: The URL of the oras archive to download.
• artifact: string: The artifact name of the oras archive.
• tag: string: The tag of the oras archive.
• add_prefix: string: The prefix to add to the archive.
• manifest_digest_path: string: The path to the manifest digest in the oras archive.
• manifest_artifact_path: string: The path to the manifest artifact in the oras archive.
• globs: List of globs to include/exclude.
• deps: list: List of dependencies for the rule.
• type: use checkout_type_optional() to skip rule checkout
• platforms: List of platforms to add the archive to.
• visibility: Rule visibility: Public|Private|Rules[]. See visbility.star for more info.

checkout_add_platform_archive()

def checkout_add_platform_archive(name, platforms, deps, type, visibility)

Adds a platform archive to the checkout.

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

Args

• name: string: The name of the rule.
• platforms: dict: List of platforms to add the archive to.
• deps: list: List of dependencies for the rule.
• type: use checkout_type_optional() to skip rule checkout
• visibility: Rule visibility: Public|Private|Rules[]. See visbility.star for more info.

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, visibility)

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: string: The name of the rule. This is also the location of the new repo in the workspace.
• url: string: The git repository URL to clone
• rev: string: The branch or commit hash to checkout
• checkout_type: string: Revision
• clone: string: checkout_clone_default() | checkout_clone_blobless() | checkout_clone_worktree()
• is_evaluate_spaces_modules: Whether to evaluate spaces.star files in the repo (default is True).
• sparse_mode: Cone | NoCone
• sparse_list: List of paths to include/exclude
• working_directory: The working directory to clone the repository into.
• platforms: List of platforms to add the repo to.
• type: use checkout_type_optional() to skip rule checkout
• deps: list: List of dependencies for the rule.
• visibility: Rule visibility: Public|Private|Rules[]. See visbility.star for more info.

checkout_add_soft_link_asset()

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

Adds a soft link asset to the workspace.

Args

• name: string: The name of the rule.
• source: string: The source path of the soft link.
• destination: string: The relative workspace path of the soft link destination.
• deps: list: List of dependencies for the asset.
• type: use checkout_type_optional() to skip rule checkout
• platforms: List of platforms to add the archive to.
• visibility: Rule visibility: Public|Private|Rules[]. See visbility.star for more info.

checkout_add_target()

def checkout_add_target(name, deps, type, platforms, visibility)

Adds a target to the workspace.

Args

• name: string: The name of the rule.
• deps: list: List of dependencies for the target.
• type: use checkout_type_optional() to skip rule checkout
• platforms: List of platforms to add the archive to.
• visibility: Rule visibility: Public|Private|Rules[]. See visbility.star for more info.

checkout_add_which_asset()

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

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: string: The name of the rule.
• which: string: The name of the asset to add.
• destination: string: The destination path for the asset.
• deps: list: List of dependencies for the asset.
• platforms: List of platforms to add the archive to.
• type: use checkout_type_optional() to skip rule checkout
• visibility: Rule visibility: Public|Private|Rules[]. See visbility.star for more info.

checkout_clone_blobless()

def checkout_clone_blobless() -> string

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() -> string

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() -> string

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() -> string

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() -> string

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() -> string

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() -> string

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_store_value()

def checkout_store_value(name, value)

Stores a value that can be retrieved using workspace_load_value().

Values are persisted across checkout and run phases, allowing data computed during checkout to be accessed later. The value can be any serializable type (dict, list, string, int, float, bool, or None).

Args

• name: string: The key to store the value under.
• value: The value to store. Can be any type.

checkout_type_default()

def checkout_type_default() -> NoneType

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() -> string

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, visibility)

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: string: The name of the rule.
• destination: string: 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: list: List of dependencies for the asset.
• type: use checkout_type_optional() to skip rule checkout
• platforms: List of platforms to add the archive to.
• visibility: Rule visibility: Public|Private|Rules[]. See visbility.star for more info.

checkout_update_env()

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

Updates the environment with the given variables and paths.

Variables other than PATH are added as key/value pairs. 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.

All vars are fixed at checkout time except vars specified in run_inherited_vars. Checkout vars are stored in the new workspace in env.spaces.star. run_inherited_vars are inherited when executing spaces run. secret_inherited_vars are inherited when executing spaces checkout or run. The values of the secrets are masked in the logs and terminal.

Args

• name: string: The name of the rule.
• vars: dict: Dictionary of variables to store in env.spaces.star.
• paths: list: List of paths to add to the PATH.
• system_paths: The path to add to the system PATH.
• inherited_vars: List of variables to inherit from the calling environment and store in env.spaces.star.
• optional_inherited_vars: List of variables to inherit from the calling environment if they exist and store in env.spaces.star (requires spaces >v0.15.1)
• run_inherited_vars: List of variables inherited when executing spaces run.
• secret_inherited_vars: List of variables inherited when executing spaces checkout/run. Values will be masked in the logs and terminal.
• deps: list: List of dependencies for the rule.
• type: use checkout_type_optional() to skip rule checkout
• platforms: List of platforms to add the archive to.
• visibility: Rule visibility: Public|Private|Rules[]. See visbility.star for more info.

checkout_update_shell()

def checkout_update_shell(name, shell_path, args, deps, visibility)

Updates the workspace shell configuration that is used with spaces shell

Args

• name: string: The name of the rule.
• shell_path: string: 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)
• visibility: The visibility of the rule.

checkout_update_shell_shortcuts()

def checkout_update_shell_shortcuts(name, shortcuts, deps, visibility)

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

Args

• name: string: 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.
• visibility: The visibility of the rule (allows controlling who can see the rule)

checkout_update_shell_startup()

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

Updates the workspace shell configuration that is used with spaces shell

Args

• name: string: The name of the rule.
• script_name: string: The name of the startup file to generate and store at .spaces/shell/<script_name> in the workspace.
• contents: string: The contents of the startup file.
• env_name: 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)
• visibility: The visibility of the rule (allows controlling who can see the rule)

update_platforms_prefix()

def update_platforms_prefix(platforms, add_prefix) -> dict

Updates the prefix of the platforms.

Args

• platforms: dict: List of platforms to add the archive to.
• add_prefix: string: The prefix to set.

Returns

An updated list of platforms.