Sandbox - The build sandbox

Element plugins which want to interface with the sandbox need only understand this interface, while it may be given a different sandbox implementation, any sandbox implementation it is given will conform to this interface.

See also: Sandboxing.

class SandboxFlags

Bases: object

Flags indicating how the sandbox should be run.

NONE = 0

Use default sandbox configuration.

ROOT_READ_ONLY = 1

The root filesystem is read only.

This is normally true except when running integration commands on staged dependencies, where we have to update caches and run things such as ldconfig.

NETWORK_ENABLED = 2

Whether to expose host network.

This should not be set when running builds, but can be allowed for running a shell in a sandbox.

INTERACTIVE = 4

Whether to run the sandbox interactively

This determines if the sandbox should attempt to connect the terminal through to the calling process, or detach the terminal entirely.

INHERIT_UID = 8

Whether to use the user id and group id from the host environment

This determines if processes in the sandbox should run with the same user id and group id as BuildStream itself. By default, processes run with user id and group id 0, protected by a user namespace where available.

exception SandboxCommandError(message, *, detail=None, collect=None, reason='command-failed')

Bases: buildstream._exceptions.SandboxError

Raised by Sandbox implementations when a command fails.

Parameters

  • message (str) – The error message to report to the user

  • detail (str) – The detailed error string

  • collect (str) – An optional directory containing partial install contents

  • reason (str) – An optional reason string (defaults to ‘command-failed’)

class Sandbox

Bases: object

Sandbox programming interface for Element plugins.

DEVICES = ['/dev/urandom', '/dev/random', '/dev/zero', '/dev/null']
get_virtual_directory() → buildstream.storage.directory.Directory

Fetches the sandbox root directory as a virtual Directory.

The root directory is where artifacts for the base runtime environment should be staged.

Returns

The sandbox root directory

set_environment(environment: Dict[str, str]) → None

Sets the environment variables for the sandbox

Parameters

environment – The environment variables to use in the sandbox

set_work_directory(directory: str) → None

Sets the work directory for commands run in the sandbox

Parameters

directory – An absolute path within the sandbox

set_output_directory(directory: str) → None

Sets the output directory - the directory which is preserved as an artifact after assembly.

Parameters

directory – An absolute path within the sandbox

mark_directory(directory: str, *, artifact: bool = False) → None

Marks a sandbox directory and ensures it will exist

Parameters

  • directory – An absolute path within the sandbox to mark

  • artifact – Whether the content staged at this location contains artifacts

Note

Any marked directories will be read-write in the sandboxed environment, only the root directory is allowed to be readonly.

run(command: List[str], flags: int, *, cwd: Optional[str] = None, env: Optional[Dict[str, str]] = None, label: str = None) → Optional[int]

Run a command in the sandbox.

If this is called outside a batch context, the command is immediately executed.

If this is called in a batch context, the command is added to the batch for later execution. If the command fails, later commands will not be executed. Command flags must match batch flags.

Parameters

  • command – The command to run in the sandboxed environment, as a list of strings starting with the binary to run.

  • flags (SandboxFlags) – The flags for running this command.

  • cwd – The sandbox relative working directory in which to run the command.

  • env – A dictionary of string key, value pairs to set as environment variables inside the sandbox environment.

  • label – An optional label for the command, used for logging.

Returns

The program exit code, or None if running in batch context.

:raises (ProgramNotFoundError): If a host tool which the given sandbox implementation requires is not found.

Note

The optional cwd argument will default to the value set with set_work_directory() and this function must make sure the directory will be created if it does not exist yet, even if a workspace is being used.

batch(flags: int, *, label: str = None, collect: str = None) → Generator[None, None, None]

Context manager for command batching

This provides a batch context that defers execution of commands until the end of the context. If a command fails, the batch will be aborted and subsequent commands will not be executed.

Command batches may be nested. Execution will start only when the top level batch context ends.

Parameters

  • flags (SandboxFlags) – The flags for this command batch.

  • label – An optional label for the batch group, used for logging.

  • collect – An optional directory containing partial install contents on command failure.

:raises (SandboxCommandError): If a command fails.