Core Package Building

Some components are built by the Continuous Integration (CI) system as Debian packages to enable convenient distribution, installation and upgrade. This requires that the components have Debian packaging files that can be used by the CI system to build packages.

See Debian’s advice on Packaging Your Product and the Debian New Maintainers’ Guide if you need advice on creating packaging files.

Build Jobs and Packages

Information about the components to be packaged is held in the deb-build-jobs repository, where the jobs.yml file contains metadata for each of them. This is extracted and passed to a script that runs the git-buildpackage tool to perform the package build.

The packages built by the CI system are published on the Debian Package Builds for the Librem 5 page and most of them are also published in the Librem 5 scratch package repository.

Build reports for packages processed by the CI system are published on the librem5-builds mailing list.

Metadata Format

The metadata takes the following form:

<component_name>:
   url: <URL of git repository>
   archs: <list of target architectures>
   branch: <git branch name>
   dists: <list of distributions to build for>

Only the url parameter is required, but the branch parameter should also be set. Defaults for the other parameters will be used if they are not specified. The following example shows metadata for the phosh component:

phosh:
  url: https://source.puri.sm/Librem5/debs/pkg-phosh
  dists: ['buster+ci']
  branch: 'master'
  deb_build_options: ['nocheck']

Parameters other than url, archs, branch and dists can also be used to configure the build process for a component. The following list describes some of the parameters currently in use:

archs
The architectures the component will be built for, specified as a Python-style list. It is useful to restrict this choice if building a component that is only suitable for a particular architecture.
Default value: ['aarch64', 'armhf', 'amd64']
branch
The branch in the git repository to use when building. The default value is based on the operating system and distribution being built for. It is better to explicitly specify a branch such as master than to rely on the default value.
deb_build_options
Options for the DEB_BUILD_OPTIONS environment variable, specified as a Python-style list. These are passed to the gdp tool when a package is built.
No default value.
deb_build_profiles
Options for the DEB_BUILD_PROFILES environment variable, specified as a Python-style list. These are passed to the gdp tool when a package is built.
No default value.
dists
The distributions to build the package for, specified as a Python-style list. Generally, you should choose the same distribution as the core components.
Default value: ['buster']
repo
Name of the aptly repository used to host the build artifacts.
Default value: scratch
submodule_update
Whether the repository’s submodules are updated before building.
Default value: true

A full, up-to-date list of parameters and their default values can be found in the script used to process the jobs.yml file.

It can also be useful to look at previous merge requests to get an idea of which values are most suitable for a given component.

Testing a New Component Locally

Before submitting a merge request to add a new component for the CI infrastructure to build, it is best to ensure that packages for the component can be built correctly. This is typically done on the developer’s workstation by following the usual steps to build a Debian package.

For software hosted in Purism’s GitLab infrastructure, it can also be helpful to use CI pipelines to build packages automatically. See the librem5-user-docs repository for an example CI recipe.

Adding a New Component

To add a new component, follow these steps:

  • Fork the deb-build-jobs repository into your own space on the server.
  • Clone your new fork locally.
    • Make a feature branch that is a pristine copy of the default branch that is checked out after cloning; e.g. with git checkout -b add-component-name
    • Add metadata to the jobs.yml file for the new component, including the relevant fields described in the previous section. Note that the components are listed in alphabetical order, so ensure that the new component maintains the correct order.
    • Commit the changes to your branch.
    • Test the changes locally – see Testing a New Component Locally.
  • When you are ready for the changes to be merged back into the production repository, push your branch back to your fork on the server.

When pushing your changes, you should be automatically prompted to make a merge request and given a URL that you can visit to do this. Otherwise, you can manually create a merge request for your branch from the web interface on the server.