Skip to content

Runtime Library

The TuxMake runtime library supports running commands in a way that makes whether those commands are running on the host system or, say, inside a container, transparent to the caller. It's what TuxMake itself uses to drive its builds, but starting at TuxMake 1.0, it is completely independent of the TuxMake build machinery and can be used for other purposes.

Using the runtime machinery looks like this:

from tuxmake.runtime import Runtime

runtime = Runtime.get(os.environ.get("RUNTIME", "podman")
runtime.set_image(os.environ.get("IMAGE", "debian"))
runtime.prepare()
runtime.run_cmd(["date"])
runtime.cleanup()

The Runtime class

class tuxmake.runtime.Runtime()

This class encapsulates running commands against the local host system or a container, in a way that is transparent to the caller.

You should usually not need to instantiate this class directly. Instead, you can get objects of this class by calling Runtime.get() (see below).

After obtaining a runtime objects, you might set the following attributes on it to control its behavior:

  • basename: base name to use when creating file (e.g. log files). Files will be named "{basename}.log" and "{basename}-debug.log". Type: str; defaults to "run".
  • quiet: whether to run a quietly or not. Type: bool; defaults to False.
  • source_dir: directory where commands are run. For container runtimes, this directory is bind mounted inside the container under the same location. Type: Path; defaults to the current working directory.
  • output_dir: directory where to save logs of the execution. For container runtimes, this directory is bind mounted inside the container under the same location. Type: Optional[Path]; defaults to None (meaning, no logs are saved).
  • environment: extra environment variables to be used for all commands ran by this runtime. Type: dict with str keys and values; defaults to an empty dict.
  • caps: additional capabilities needed by the container ran by this runtime. Type: list with str; defaults to an empty list.
  • network: name of the network created by the runtime(docker|podman) to be used in the container.
  • allow_user_opts: flag to enable/disable user options for container runtime. Type: bool; defaults to False.
get(name)

Creates and returns a new Runtime object.The returned objects will be of a subclass of Runtime, depending on the name argument. Supported runtimes are:

  • null: runs commands on the host system.
  • docker: runs commands on a Docker container. All commands ran by the same runtime instance are executed in the same container (i.e. state between calls is persisted).
  • docker-local: the same as docker, but will only use local images (i.e. it will never pull remote images).
  • podman: run commands on a Podman container.
  • podman-local: like docker-local, but with Podman.
set_image(self, image)

Sets the container image to use. This has effect only on container runtimes.

set_user(self, user)

Sets the user (inside the container) that the container will be started as. This has effect only on Docker runtimes.

set_group(self, group)

Sets the group (inside the container) that the container will be started as. This has effect only on Docker runtimes, and only if set_user is also used.

add_volume(self, source, dest=None, ro=False, device=False)

Ensures that the directory or file source is available for commands run as dest. For container runtimes, this means bind-mounting source as dest inside the container. All volumes must be added before prepare() is called. * ro: bind-mount with read only. Type: bool; defaults to False. * device: flag to bind-mount volume as device. Type: bool; defaults to False.

This is a noop for non-container runtimes.

prepare(self)

Initializes the runtime object. Must be called before actually running any commands with run_cmd.

run_cmd(self, cmd, interactive=False, offline=True, expect_failure=False, stdout=None, echo=True, logger=None)

Runs a command in the desired runtime. Returns True if the command succeeds (i.e. exits with a status code of 0); False otherwise. Parameters:

  • cmd: The command to run. must be a list of strings (like with the subprocess functions, e.g. check_call).
  • interactive: whether this commands needs user interaction.
  • offline: whether this commands should run offline, i.e. with no access to non-loopback network interfaces.
  • expect_failure: whether a failure, i.e. a non-zero return status, is to be expected. Reverses the logic of the return value of this method, i.e. returns True if the command fails, False if it succeeds.
  • stdout: a TextIO object to where the stdout of the called command will be directed.
  • echo: flag to log the command which is being run. Type: bool. Defaults to True.
  • logger: Optional callable function to be called for each line of command output.

If the command in interrupted in some way (by a TERM signal, or by the user typing control-C), an instance of Terminated is raised.

cleanup(self)

Cleans up and returns resources used during execution. You must call this methods after you are done with the runtime object.

log(self, *stuff)

Logs stuff to both the console and to any log files in use.

get_metadata(self)

Extracts metadata about the runtime (e.g. docker version, image name and sha256sum, etc).

The Terminated class

class tuxmake.runtime.Terminated(msg)

This is an exception class raised by Runtime.run_cmd in the case the currently running command gets terminated (via kill, or by the user typing control-C).