mate.build.common module

Functionality common to various parts of the MATE build pipeline.

mate.build.common.docker_bind(dir_: pathlib.Path, *, mode: str = 'rw') → Dict[str, str]

Return a Docker SDK-style dictionary for binding a volume to the given directory.

Parameters

  • dir_ (pathlib.Path) –

  • mode (str) –

Return type

Dict[str, str]

mate.build.common.docker_compose_project(client: docker.client.DockerClient) → Optional[DockerComposeProject]

If possible, attempt to get the name for the Docker Compose project we’re executing within.

Parameters

client (docker.client.DockerClient) –

Return type

Optional[DockerComposeProject]

mate.build.common.docker_container_id() → Optional[DockerContainerId]

If possible, get the Docker container ID we are currently executing within.

This function uses two techniques to attempt to discover the container ID:

  1. First, we check whether HOSTNAME environment variable looks like a container ID. If it does, we use it and finish our search.

  2. If the HOSTNAME looks wrong, we search /proc/self/cpuset for a pseudo-path that looks like a container ID. This is our fallback technique, since neither Linux nor Docker guarantees the stability of this pseudo-file’s contents.

Return type

Optional[DockerContainerId]

mate.build.common.docker_image(client: docker.client.DockerClient, name: str) → docker.models.images.Image

Return an image handle for the given Docker image name, pulling it if necessary.

Raises various Docker client errors on failure.

Parameters

  • client (docker.client.DockerClient) –

  • name (str) –

Return type

docker.models.images.Image

mate.build.common.docker_volume_by_label(client: docker.client.DockerClient, label: str) → Optional[docker.models.volumes.Volume]

Given an active Docker client, locate exactly one Docker volume with the given metadata label.

Asserts if more than one volume is found, and returns None if none are found.

Parameters

  • client (docker.client.DockerClient) –

  • label (str) –

Return type

Optional[docker.models.volumes.Volume]

mate.build.common.format_run_log(result: subprocess.CompletedProcess) → str

Given a subprocess.CompletedProcess, return a pretty-ish printed representation of the process’s standard output, error, and exit code.

Parameters

result (subprocess.CompletedProcess) –

Return type

str

mate.build.common.gllvm_environment(level: Literal['ERROR', 'WARNING', 'INFO', 'DEBUG'] = 'DEBUG') → Environment

Returns a mapping suitable for loading into the environment of any process that needs to interactive with GLLVM CLI tools (gclang, get-bc, etc.).

Parameters

level (Literal['ERROR', 'WARNING', 'INFO', 'DEBUG']) –

Return type

Environment

mate.build.common.llvm_wedlock_environment() → Environment

Returns a mapping suitable for loading into the environment of any process that needs to interact with LLVM tools or, more specifically, the Wedlock builds of LLVM tools.

Return type

Environment

mate.build.common.mate_environment(llvm_wedlock: bool = False) → Environment

Returns a mapping suitable for loading into the environment of any container that needs to invoke MATE functionality and/or any tools included with the MATE bdist.

llvm_wedlock indicates whether to include the Wedlock LLVM toolchain in the PATH.

This function assumes that the targeted container has the MATE bdist mounted into it at the same root as MATE_BDIST_ROOT.

Parameters

llvm_wedlock (bool) –

Return type

Environment

mate.build.common.run(args: Sequence[Union[str, os.PathLike]], **kwargs: Any) → subprocess.CompletedProcess

A very thin wrapper for subprocess.run that logs the invocation before execution.

Parameters

  • args (Sequence[Union[str, os.PathLike]]) –

  • kwargs (Any) –

Return type

subprocess.CompletedProcess