get_cpu_architecture

get_cpu_architecture()

Return the architecture string for the currently configured CPU architecture, e.g., aarch64, ppc64le, or x86_64.

get_cpu_optimization_flags

get_cpu_optimization_flags(compiler, version='9999')

Return the CPU optimization flags for the target and compiler combination.

Arguments

• compiler: A compiler family string recognized by archspec.

• version: The version of the compiler. The default version is 9999, i.e., assume the compiler supports the latest optimization flags.

get_format

get_format()

Return the container format string for the currently configured format, e.g., bash, docker, or singularity.

set_container_format

set_container_format(ctype)

Set the container format

Arguments

• ctype (string): 'docker' to specify the Dockerfile format, or 'singularity' to specify the Singularity definition file format

Raises

• RuntimeError: invalid container type argument

set_cpu_architecture

set_cpu_architecture(arch)

Set the CPU architecture

In most cases, the baseimage primitive should be relied upon to set the CPU architecture. Only use this function if you really know what you are doing.

Arguments

• arch (string): Value values are aarch64, ppc64le, and x86_64. arm and arm64v8 are aliases for aarch64, power is an alias for ppc64le, and amd64 and x86 are aliases for x86_64.

set_cpu_target

set_cpu_target(target)

Set the CPU optimization target

Arguments

• target (string): A CPU microarchitecture string recognized by archspec.

set_linux_distro

set_linux_distro(distro)

Set the Linux distribution and version

In most cases, the baseimage primitive should be relied upon to set the Linux distribution. Only use this function if you really know what you are doing.

Arguments

• distro (string): Valid values are centos7, centos8, rhel7, rhel8, rockylinux8, rockylinux9, rockylinux10, ubuntu16, ubuntu18, ubuntu20, ubuntu22, ubuntu24, and ubuntu26. ubuntu is an alias for ubuntu16, centos is an alias for centos7, and rhel is an alias for rhel7.

set_singularity_version

set_singularity_version(ver)

Set the Singularity definition file format version

The Singularity definition file format was extended in version 3.2 to enable multi-stage builds. However, these changes are not backwards compatible.

Arguments

• ver (string): Singularity definition file format version.

set_working_directory

set_working_directory(wd)

Set the working directory to use for staging inside the container

Arguments

• wd (string): working directory path

set_singularity_tmp_fallback

set_singularity_tmp_fallback(enable=True)

Enable or disable the automatic %setup fallback for /tmp and /var/tmp destinations on Singularity >= 3.6.

Arguments

• enable (bool): True to enable the fallback (default), False to disable.

test_cpu_feature_flag

test_cpu_feature_flag(flag)

Return True or False depending on whether the CPU supports the given feature flag

Arguments

• flag: A CPU feature flag, e.g., avx.

recipe

recipe(recipe_file, cpu_target=None, ctype=<container_type.DOCKER: 1>, raise_exceptions=False, single_stage=False, singularity_version=u'2.6', userarg=None, working_directory=u'/var/tmp', singularity_tmp_fallback=True)

Recipe builder

Arguments

• recipe_file: path to a recipe file (required).

• cpu_target: A CPU microarchitecture string recognized by archspec.

• ctype: Enum representing the container specification format. The default is container_type.DOCKER.

• raise_exceptions: If False, do not print stack traces when an exception is raised. The default value is False.

• single_stage: If True, only print the first stage of a multi-stage recipe. The default is False.

• singularity_version: Version of the Singularity definition file format to use. Multi-stage support was added in version 3.2, but the changes are incompatible with earlier versions of Singularity. The default is '2.6'.

• userarg: A dictionary of key / value pairs provided to the recipe as the USERARG dictionary.

• working_directory: path to use as the working directory in the container specification

• singularity_tmp_fallback: If True (default), automatically handle copy destinations under /tmp or /var/tmp using a %setup block when targeting Singularity >= 3.6. If False, such copy operations are rejected and will raise an error, requiring the user to modify the recipe.

Stage

Stage(self, **kwargs)

Class for container stages.

Docker may have one or more stages, Singularity will always have a single stage.

Parameters

• name: Name to use when refering to the stage (Docker specific). The default is an empty string.

• separator: Separator to insert between stages. The default is '\n\n'.

baseimage

Stage.baseimage(self, image, _distro=u'')

Insert the baseimage as the first layer

Arguments

• image (string): The image identifier to use as the base image. The value is passed to the baseimage primitive.

• _distro: The underlying Linux distribution of the base image. The value is passed to the baseimage primitive.

runtime

Stage.runtime(self, _from=None, exclude=[])

Generate the set of instructions to install the runtime specific components from a previous stage.

This method invokes the runtime() method for every layer in the stage. If a layer does not have a runtime() method, then it is skipped.

Arguments

• _from: The name of the stage from which to copy the runtime. The default is 0.

• exclude: List of building blocks to exclude when generating the runtime. The default is an empty list.

Examples

Stage0 += baseimage(image='nvidia/cuda:9.0-devel')
Stage0 += gnu()
Stage0 += boost()
Stage0 += ofed()
Stage0 += openmpi()
...
Stage1 += baseimage(image='nvidia/cuda:9.0-base')
Stage1 += Stage0.runtime(exclude=['boost'])