checkout_add()

def checkout_add(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_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_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_home_assets()

def checkout_add_home_assets(name, assets)

Adds home assets to the workspace.

Each entry in assets is a path relative to $HOME. The file is copied into the spaces store under .spaces/store/home/$USER/ and hard-linked into the workspace at the same relative path.

Args

• name: string: Name of the checkout rule
• assets: list: list of paths relative to $HOME (e.g. [".ssh/config"])

checkout_add_home_store_env()

def checkout_add_home_store_env(name)

Assigns HOME to a user specific location in the spaces store.

Args

• name: string: Name of the checkout rule

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.

For clone=checkout_clone_default(), the repo is cloned first to the store as a bare repo and then cloned 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_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_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_modify_value()

def checkout_modify_value(name, modifier, path)

Modifies a stored value by applying a callback to the current value.

The callback receives the current stored value for name (or None if it does not exist yet). The callback return value is then stored.

Args

• name: string: The key to update.
• modifier: A function/lambda taking one argument (current value).
• path: Optional path to store under. When omitted, the member path for the calling module is used.

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

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.
• path: Optional path to store under. When omitted, the member path for the calling module is used.

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_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)