datalad.api.deb_configure_builder

datalad.api.deb_configure_builder(*, dataset=None, force=False, template='default', spec=None)

Configure a package build environment

A builder is a (containerized) build environment used to build binary Debian packages from Debian source packages. This command is typically run on the builder dataset in a distribution dataset and configures a builder recipe based on a template and user-specified values for the template's placeholders. The resulting recipe will be placed in the 'recipes/' directory of the builder dataset.

The following directory tree illustrates this. The configured builder takes the form of a Singularity recipe here.

bullseye <- distribution dataset
├── builder <- builder subdataset
│ ├── envs
│ │   └── README.md
│ └── recipes
│ ├── README.md
│ └── singularity-any <- builder configuration

Currently supported templates are

Template 'default'

This is a Singularity recipe with the following configuration items:

  • dockerbase (required): name of a Docker base image for the container, i.e. 'debian:bullseye'

  • 'debian_archive_sections (optional): which sections of the Debian package archive to enable for APT in the build environment. To enable all sections set to 'main contrib non-free'. Default: 'main'

Examples

Configure the default Singularity recipe in the builder subdataset, executed from a distribution superdataset:

> deb_configure_builder(dataset='builder', spec={'dockerbase':'debian:bullseye'})
Parameters

  • dataset (Dataset or None, optional) -- Specify a builder dataset in which an environment will be defined. [Default: None]

  • force (bool, optional) -- enforce creation of a package dataset in a non-empty directory. [Default: False]

  • template (str or None, optional) -- Builder recipe template. This is a text file for placeholders in Python string formating syntax. [Default: 'default']

  • spec -- Values to replace placeholders in the specified template. [Default: None]

  • on_failure ({'ignore', 'continue', 'stop'}, optional) -- behavior to perform on failure: 'ignore' any failure is reported, but does not cause an exception; 'continue' if any failure occurs an exception will be raised at the end, but processing other actions will continue for as long as possible; 'stop': processing will stop on first failure and an exception is raised. A failure is any result with status 'impossible' or 'error'. Raised exception is an IncompleteResultsError that carries the result dictionaries of the failures in its failed attribute. [Default: 'continue']

  • result_filter (callable or None, optional) -- if given, each to-be-returned status dictionary is passed to this callable, and is only returned if the callable's return value does not evaluate to False or a ValueError exception is raised. If the given callable supports **kwargs it will additionally be passed the keyword arguments of the original API call. [Default: None]

  • result_renderer -- select rendering mode command results. 'tailored' enables a command- specific rendering style that is typically tailored to human consumption, if there is one for a specific command, or otherwise falls back on the the 'generic' result renderer; 'generic' renders each result in one line with key info like action, status, path, and an optional message); 'json' a complete JSON line serialization of the full result record; 'json_pp' like 'json', but pretty-printed spanning multiple lines; 'disabled' turns off result rendering entirely; '<template>' reports any value(s) of any result properties in any format indicated by the template (e.g. '{path}', compare with JSON output for all key-value choices). The template syntax follows the Python "format() language". It is possible to report individual dictionary values, e.g. '{metadata[name]}'. If a 2nd-level key contains a colon, e.g. 'music:Genre', ':' must be substituted by '#' in the template, like so: '{metadata[music#Genre]}'. [Default: 'tailored']

  • result_xfm ({'datasets', 'successdatasets-or-none', 'paths', 'relpaths', 'metadata'} or callable or None, optional) -- if given, each to-be-returned result status dictionary is passed to this callable, and its return value becomes the result instead. This is different from result_filter, as it can perform arbitrary transformation of the result value. This is mostly useful for top- level command invocations that need to provide the results in a particular format. Instead of a callable, a label for a pre-crafted result transformation can be given. [Default: None]

  • return_type ({'generator', 'list', 'item-or-list'}, optional) -- return value behavior switch. If 'item-or-list' a single value is returned instead of a one-item return value list, or a list in case of multiple return values. None is return in case of an empty list. [Default: 'list']