hpccm.primitives

source package hpccm.primitives

Classes

  • blob — 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.

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

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

  • environment — 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.

  • label — The label primitive sets container metadata.

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

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

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

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

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

class blob(**kwargs)

Bases : object

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).

Examples 

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

class comment(*args, **kwargs)

Bases : object

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')

Methods

  • merge — Merge one or more instances of the primitive into a single instance. Due to conflicts or option differences the merged primitive may not be exact merger.

method comment.merge(lst, _app=None)

Merge one or more instances of the primitive into a single instance. Due to conflicts or option differences the merged primitive may not be exact merger.

Raises

  • RuntimeError

class copy(**kwargs)

Bases : object

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)

  • _exclude_from — String or list of strings. One or more filenames containing rsync-style exclude patterns (e.g., .apptainerignore). Only used when building for Singularity or Apptainer. If specified, the copy operation is emitted in the %setup section using rsync --exclude-from=<file> rather than the standard %files copy directive. This enables selective exclusion of files and directories during the image build, for example to omit large data files, caches, or temporary artifacts. Multiple exclusion files may be provided as a list or tuple. The default is an empty list (Singularity specific).

  • 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'})

copy(src='.', dest='/opt/app', _exclude_from='.apptainerignore')

Methods

  • merge — Merge one or more instances of the primitive into a single instance. Due to conflicts or option differences the merged primitive may not be exact merger.

method copy.merge(lst, _app=None)

Merge one or more instances of the primitive into a single instance. Due to conflicts or option differences the merged primitive may not be exact merger.

Raises

  • RuntimeError

class environment(**kwargs)

Bases : object

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'})

Methods

  • merge — Merge one or more instances of the primitive into a single instance. Due to conflicts or option differences the merged primitive may not be exact merger.

method environment.merge(lst, _app=None)

Merge one or more instances of the primitive into a single instance. Due to conflicts or option differences the merged primitive may not be exact merger.

Raises

  • RuntimeError

class label(**kwargs)

Bases : object

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'})

Methods

  • merge — Merge one or more instances of the primitive into a single instance. Due to conflicts or option differences the merged primitive may not be exact.

method label.merge(lst, _app=None)

Merge one or more instances of the primitive into a single instance. Due to conflicts or option differences the merged primitive may not be exact.

Raises

  • RuntimeError

class raw(**kwargs)

Bases : object

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.

Raw primitive

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')

class runscript(**kwargs)

Bases : object

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'])

Methods

  • merge — Merge one or more instances of the primitive into a single instance. Due to conflicts or option differences the merged primitive may not be exact.

method runscript.merge(lst, _app=None)

Merge one or more instances of the primitive into a single instance. Due to conflicts or option differences the merged primitive may not be exact.

Raises

  • RuntimeError

class shell(**kwargs)

Bases : object

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'])

Methods

  • merge — Merge one or more instances of the primitive into a single instance. Due to conflicts or option differences the merged primitive may not be exact merger.

method shell.merge(lst, _app=None, _appenv=False, _test=False)

Merge one or more instances of the primitive into a single instance. Due to conflicts or option differences the merged primitive may not be exact merger.

Raises

  • RuntimeError

class user(**kwargs)

Bases : object

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')

class workdir(**kwargs)

Bases : object

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')