Ontology

For Artifacts

The categorization of artifacts does not enforce anything on the structure of the associated files and key-value data. However, there must be some consistency and rules to be able to a make a meaningful use of the system.

This document presents the various types that we use to manage a Debian-based distribution. For each type, we explain:

• what associated files you can find

• what key-value data you can expect

• what relationships with other artifacts are likely to exist

All the “types” listed on this page are in fact prefixed with “debian” when referenced in the Artifact’s “category” field.

Type source-package

This artifact represents a set of files that can be extracted in some way to provide a file hierarchy containing source code that can be built into binary-packages artifact(s).

• Data:

  • name: the name of the source package

  • version: the version of the source package

  • type: the type of the source package

    • dpkg for a source package that can be extracted with dpkg-source -x on the .dsc file

  • dsc-fields: a parsed version of the fields available in the .dsc file

• Files: for the dpkg type, a .dsc file and all the files referenced in that file

• Relationships: none

Type binary-packages

This artifact represents the set of binary packages (.deb files and similar) produced during the build of a source package for a given architecture.

If the build of a source-package produces binaries of more than one architecture, one binary-packages artifact is created for each architecture, listing only the binary packages for that architecture.

• Data:

  • srcpkg-name: the name of the source package

  • srcpkg-version: the version of the source package

  • version: the version used for the build (can be different from the source version in case of binary-only rebuilds)

  • architecture: the architecture that the packages have been built for. Can be any real Debian architecture or all.

  • packages: the list of binary packages that are part of the build for this architecture.

• Files: one or more .deb files

• Relationships:

  • built-using: the corresponding source-package

  • built-using: other binary-packages (for example in the case of signed packages duplicating the content of an unsigned package)

  • built-using: other source-package (general case of Debian’s Built-Using field)

Type source-upload

• Data:

  • type: the type of the source upload

    • dpkg: for an upload generated out of a .changes file created by dpkg-buildpackage

  • changes-fields: a parsed version of the fields available in the .changes file

• Files:

  • a .changes file

• Relationships:

  • extends: one source-package

Type binary-upload

• Data:

  • type: the type of the binary upload

    • dpkg: for an upload generated out of a .changes file created by dpkg-buildpackage

  • changes-fields: a parsed version of the fields available in the .changes file

• Files:

  • a .changes file

• Relationships:

  • extends: one (or more) binary-packages

  • relates-to: one (or more) binary-packages

Type package-build-log

• Data:

  • source: name of the source package built

  • version: version of the source package built

  • filename: name of the log file

  • maybe other information extracted out of the build log (build time, disk space used, etc.)

• Files:

  • a single file .build file

• Relationships:

  • relates-to: one (or more) binary-packages built

  • relates-to: the corresponding source-package (if built from a source package)

Type work-request-debug-logs

• Files:

  • any number of files containing logs and information to help a debusine user understand the WorkRequest output: commands executed, output of the commands, etc.

• Relationships:

  • relates-to: the corresponding source-package (if built from a source package)

For Tasks

While tasks are unique in theory, we can have different tasks sharing some commonalities. In the Debian context in particular, we have different ways to build Debian packages with different helper programs (sbuild, pbuilder, etc.) and we want those tasks to reuse the same set of parameters so that they can be called interchangeably.

This public interface is materialized by a generic task that can be scheduled by the users and that will run one of the available implementations that can run on one of the available workers.

This section documents those generic tasks and their interface.

Task PackageBuild

A generic task to represent a package build, i.e. the act of transforming a source package (.dsc) into binary packages (.deb).

The task_data associated to this task can contain the following keys:

• input (required): a dictionary of values describing the input data

  • source_package_url (required): an URL pointing to a source package (.dsc file), it is used to retrieve the source package to build, it can be a publicly accessible URL or a debusine artifact (that might be private but accessible with a token).

  • checksums (optional): a dictionary of checksum data.

    • sha256sum: SHA256 checksum of the file at source_package_url.

• distribution (required): name of the target distribution

• extra_repositories (optional): a list of extra repositories to enable. Each repository is described by a dictionary with the following possible keys:

  • sources_list: a single-line for an APT’s sources.list file

  • authentication_key (optional): the ascii-armored public key used to authenticate the repository

• host_architecture (required): the architecture that we want to build for, it defines the architecture of the resulting architecture-specific .deb (if any)

• build_architecture (optional, defaults to the host architecture): the architecture on which we want to build the package (implies cross-compilation if different from the host architecture). Can be explicitly set to the undefined value (Python’s None or javascript’s null) if we want to allow cross-compilation with any build architecture.

• build_components (optional, defaults to any): list that can contain the following 3 words (cf dpkg-buildpackage --build=any,all,source):

  • any: enables build of architecture-specific .deb

  • all: enables build of architecture-independent .deb

  • source: enables build of the source package (.dsc)

• build_profiles: list of build profiles to enable during package build (cf dpkg-buildpackage --build-profiles)

• build_options: value of DEB_BUILD_OPTIONS during build

• build_path (optional, default unset): forces the build to happen through a path named according to the passed value. When this value is not set, there’s no restriction on the name of the path.