primitives.md

baseimage

baseimage(self, **kwargs)

The baseimage primitive defines the base image to be used.

Parameters

• _arch: The underlying CPU architecture of the base image. Valid values are aarch64, ppc64le, and x86_64. By default, the primitive attemps to figure out the CPU architecture by inspecting the image identifier, and falls back to x86_64 if unable to determine the CPU architecture automatically.

• _as: Name for the stage. When using Singularity multi-stage recipes, this value must be specified. The default value is empty.

• _bootstrap: The Singularity bootstrap agent. This default value is docker (Singularity specific).

• _distro: The underlying Linux distribution of the base image. Valid values are centos, centos7, centos8, redhat, rhel, rhel7, rhel8, rockylinux8, ubuntu, ubuntu16, ubuntu18, and ubuntu20. By default, the primitive attempts to figure out the Linux distribution by inspecting the image identifier, and falls back to ubuntu if unable to determine the Linux distribution automatically.

• _docker_env: Boolean specifying whether to load the Docker base image environment, i.e., source /.singularity.d/env/10-docker*.sh (Singularity specific). The default value is True.

• image: The image identifier to use as the base image. The default value is ubuntu:18.04.

• AS: Name for the build stage (Docker specific). The default value is empty. This parameter is deprecated; use _as instead.

Examples

baseimage(image='nvidia/cuda:9.1-devel')

blob

blob(self, **kwargs)

The blob primitive inserts a file, without modification, into the corresponding place in the container specification file. If a relative path is specified, the path is relative to current directory.

Generally, the blob should be functionally equivalent for each container format.

Wherever possible, the blob primitive should be avoided and other, more portable, operations should be used instead.

Parameters

• docker: Path to the file containing the Dockerfile blob (Docker specific).

• singularity: Path to the file containing the Singularity blob (Singularity specific).

Example

blob(docker='path/to/foo.docker', singularity='path/to/foo.singularity')

comment

comment(self, *args, **kwargs)

The comment primitive inserts a comment into the corresponding place in the container specification file.

Parameters

• _app: String containing the

• __SCI-F identifier. This also causes the comment to be enclosed in a Singularity block to named %apphelp (Singularity specific).

• reformat: Boolean flag to specify whether the comment string should be wrapped to fit into lines not exceeding 80 characters. The default is True.

Examples

comment('libfoo version X.Y')

copy

copy(self, **kwargs)

The copy primitive copies files from the host to the container image.

Parameters

• _app: String containing the SCI-F identifier. This also causes the Singularity block to named %appfiles rather than %files (Singularity specific).

• _chown: Set the ownership of the file(s) in the container image (Docker specific).

• dest: Path in the container image to copy the file(s)

• files: A dictionary of file pairs, source and destination, to copy into the container image. If specified, has precedence over dest and src.

• _from: Set the source location to a previous build stage rather than the host filesystem (Docker specific).

• _mkdir: Boolean flag specifying that the destination directory should be created in a separate %setup step. This can be used to work around the Singularity limitation that the destination directory must exist in the container image prior to copying files into the image. The default is False (Singularity specific).

• _post: Boolean flag specifying that file(s) should be first copied to / and then moved to the final destination by a %post step. This can be used to work around the Singularity limitation that the destination must exist in the container image prior to copying files into the image. The default is False (Singularity specific).

• src: A file, or a list of files, to copy

Examples

copy(src='component', dest='/opt/component')

copy(src=['a', 'b', 'c'], dest='/tmp')

copy(files={'a': '/tmp/a', 'b': '/opt/b'})

environment

environment(self, **kwargs)

The environment primitive sets the corresponding environment variables. Note, for Singularity, this primitive may set environment variables for the container runtime but not for the container build process (see this rationale). See the _export parameter for more information.

Parameters

• _app: String containing the SCI-F identifier. This also causes the Singularity block to named %appenv rather than %environment (Singularity specific).

• _export: A Boolean flag to specify whether the environment should also be set for the Singularity build context (Singularity specific). Variables defined in the Singularity %environment section are only defined when the container is run and not for subsequent build steps (unlike the analogous Docker ENV instruction). If this flag is true, then in addition to the %environment section, a identical %post section is generated to export the variables for subsequent build steps. The default value is True.

• variables: A dictionary of key / value pairs. The default is an empty dictionary.

Examples

environment(variables={'PATH': '/usr/local/bin:$PATH'})

label

label(self, **kwargs)

The label primitive sets container metadata.

Parameters

• _app: String containing the SCI-F identifier. This also causes the Singularity block to named %applabels rather than %labels (Singularity specific).

• metadata: A dictionary of key / value pairs. The default is an empty dictionary.

Examples

label(metadata={'maintainer': 'jane@doe'})

raw

raw(self, **kwargs)

The raw primitive inserts the specified string, without modification, into the corresponding place in the container specification file.

Generally, the string should be functionally equivalent for each container format.

Wherever possible, the raw primitive should be avoided and other, more portable, primitives should be used instead.

Parameters

• docker: String containing the Dockerfile instruction (Docker specific).

• singularity: String containing the Singularity instruction (Singularity specific).

Examples

raw(docker='COPY --from=0 /usr/local/openmpi /usr/local/openmpi',
    singularity='# no equivalent to --from')

runscript

runscript(self, **kwargs)

The runscript primitive specifies the commands to be invoked when the container starts.

Parameters

• _args: Boolean flag to specify whether "$@" should be appended to the command. If more than one command is specified, nothing is appended regardless of the value of this flag. The default is True (Singularity specific).

• _app: String containing the SCI-F identifier. This also causes the Singularity block to named %apprun rather than %runscript (Singularity specific).

• commands: A list of commands to execute. The default is an empty list.

• _exec: Boolean flag to specify whether exec should be inserted to preface the final command. The default is True (Singularity specific).

Examples

runscript(commands=['cd /workdir', 'source env.sh'])

runscript(commands=['/usr/local/bin/entrypoint.sh'])

shell

shell(self, **kwargs)

The shell primitive specifies a series of shell commands to execute.

Parameters

• _app: String containing the SCI-F identifier. This also causes the Singularity block to named %appinstall rather than %post (Singularity specific).

• _appenv: Boolean flag to specify whether the general container environment should be also be loaded when executing a SCI-F %appinstall block. The default is False.

• _arguments: Specify additional Dockerfile RUN arguments (Docker specific).

• chdir: Boolean flag to specify whether to change the working directory to / before executing any commands. Docker automatically resets the working directory for each RUN instruction. Setting this option to True makes Singularity behave the same. This option is ignored for Docker. The default is True.

• commands: A list of commands to execute. The default is an empty list.

• _test: Boolean flag to specify whether to use %test instead of %post and %apptest instead of %appinstall as the Singularity section headings (Singularity specific).

Examples

shell(commands=['cd /path/to/src', './configure', 'make install'])

# Cache Go packages
shell(_arguments='--mount=type=cache,target=/root/.cache/go-build',
      commands=['cd /path/to/go-src', 'go build'])

user

user(self, **kwargs)

The user primitive sets the user name to use for any subsequent steps.

This primitive is the null operation for Singularity.

Parameters

• user: The user name to use. The default is an empty string.

Examples

user(user='ncognito')

workdir

workdir(self, **kwargs)

The workdir primitive sets the working directory for any subsequent operations. As a side effect, if the directory does not exist, it is created.

Parameters

• directory: The directory path.

Examples

workdir(directory='/path/to/directory')