Page MenuHomePureOS Tracker

Packaging Overview
Updated 226 Days AgoPublic

Version 38 of 42: You are viewing an older version of this document, as it appeared on Apr 24 2021, 05:06.

Prerequisites

To build packages, install the devscripts package: sudo apt install devscripts, which contains a lot of useful helpers for building Debian packages. Many build tools for building software in the package can be found in the package build-essential;

apt install build-essential devscripts

Having gbp available is also a good idea: sudo apt install git-buildpackage

Note that installing git-buildpackage (gbp) will pull in pbuilder. You can prevent this by using --no-install-recommends when you install, e.g.;

apt install --no-install-recommends git-buildpackage

This is not necessary but can be helpful if you don't want to install and configure pbuilder.

Building packages with git-buildpackage

PureOS is aiming to standardize around a git based workflow. Please follow this link for building packages with git-buildpackage

Building packages with Debspawn and pbuilder

All packages should be tested and built in a pristine PureOS landing chroot before being uploaded to PureOS repositories. The preferred method to do that is by using debspawn.

Debspawn quickstart

Debspawn uses a systemd-nspawn container to build packaged. It is also the build environment used on the PureOS autobuild servers, so if you want to replicate a build as close as possible to what runs on our build servers, use debspawn.
To install debspawn, run sudo apt install debspawn first.
Then create a new build environment for landing: debspawn create landing.
For packages not managed in git, debspawn can be invoked via

debspawn build landing --sign

For packages using git as the source code management tool, gbp can be instructed to build with Debspawn via gbp buildpackage --git-builder='debspawn b landing --sign'

Don't forget to set your own email address for the Git repository, via git config user.email your.name@puri.sm.

Pbuilder quickstart

There is documentation on setting up a pbuilder environment using PureOS.
For packages not managed in git, pbuilder can be invoked via

DIST=landing pdebuild --auto-debsign

For git-managed packages, gbp provides options to build with pbuilder directly. Alternatively, pdebuild can be passed in like gbp buildpackage --git-builder='DIST=landing pdebuild --auto-debsign'

Don't forget to set your own email address for the git repository, via git config user.email your.name@puri.sm.

Version numbers

Packages which are available on Debian and are changed in PureOS have a pureosX version tag attached to the Debian revision, with X being the PureOS revision number. So, if the package's upstream version is 2.1, it's Debian revision is 2 (creating the Debian version string 2.1-2) and you make a change for PureOS, the resulting package version must be 2.1-2pureos1. The PureOS revsion is incremented with every change, so the next version would be 2.1-2pureos2. This is also true for 3.0 (native) packages that don't have a Debian revision so e.g. 2.1 turns into 2.1pureos1.

If the package isn't in Debian, the Debian revision number is assumed to be zero and all other rules from above still apply. So, an upstream package with version 3.4 which is new in PureOS will get the initial version 3.4-0pureos1.

If you do not do any source changes but just rebuild a package, bX is appended to the revision. So, a package of version 1.0-3 gets the new version 1.0-3b1 if it is rebuilt. The rebuild version is incremented on every subsequent rebuild.

If the archive rejects an upload because a +bX version number exists, then this is because of a binary package sync from Debian where the package was binNMUd before. In this particular case, please upload the package again, but append a + before the PureOS version, so 1.0-1pureos1 becomes 1.0-1+pureos1.

Paying attention to the version numbers is important, because the PureOS archive tools will use the version number to make decisions about the package's state, which includes overriding it with a version from Debian or even removing it. Using the right version number will make the archive do the right thing.

You might be able to use DEBEMAIL=first.last@puri.sm dch --distribution=landing --force-distribution --no-auto-nmu --local=pureos as a starting point.

Validating packages

Use lintian --profile=pureos -IE --pedantic <changes-file> to check a package for compliance with the Debian policy. Ensure it is warning and error-free.

If your Lintian is old and does not support the pureos profile, all warnings related to NMUs and invalid suites can be ignored, as those are different or don't exist in PureOS. (See https://bugs.debian.org/884408)

Mandatory debian/control file changes for PureOS

Maintainer address

Please add the team based maintainer address for PureOS packages;PureOS Maintainers <pureos-project@lists.puri.sm>. This ensures that more than one person will be able to help maintain the package in PureOS and is required.
Example: If the debian/control file had

Maintainer:  Cool Package Maintainers <team-pkg@example.com>

it should be changed to:

Maintainer: PureOS Maintainers <pureos-project@lists.puri.sm>
XSBC-Original-Maintainer: Cool Package Maintainers  <team-pkg@example.com>

Note that there should not be an Uploaders: field, but the original field should be retained as XSBC-Uploaders:.

Version Control System fields

In addition to the maintainer address, please make sure to fill in the Vcs-Browser and Vcs-Git fields. This allows one to correlate releases with source code and is also required.

The original Vcs-* fields should be retained as XSBC-Original-Vcs-*:

Example:

Vcs-Git: https://salsa.debian.org/gnome-team/gnome-control-center.git
Vcs-Browser: https://salsa.debian.org/gnome-team/gnome-control-center

becomes:

Vcs-Git: https://source.puri.sm/pureos/packages/gnome-control-center.git
Vcs-Browser: https://source.puri.sm/pureos/packages/gnome-control-center
XSBC-Original-Vcs-Git: https://salsa.debian.org/gnome-team/gnome-control-center.git
XSBC-Original-Vcs-Browser: https://salsa.debian.org/gnome-team/gnome-control-center

This help to identify the repository where new Debian versions should be pulled from.

Closing bugs

At the moment, the service that automatically closes reports is not active, due to maintenance (the previous implementation had a few bugs and was very slow), so for now you will need to close bugs manually. However, for some packages the bug information is still used to e.g. determine package migration speed. To close bugs in the PureOS tracker with an upload (once it is re-enabled), please use either the PB: #<nnn> or PureOS: #<nnn> syntax in debian/changelog, with <nnn> being replaced with the number of the respective task in Maniphest on tracker.p.n (with the T prefix stripped).

Uploading packages

See the document on Development/Uploading Packages

Common baseline

In order to ease collaboration *new* packages introcued into PureOS should

*Existing* packages can continue to use pureos/byzantium or pureos/master branch naming but should make sure the gitlab UI has the default branch set to the branch that carries most recent development (e.g. pureos/byzantium at the time of writing).

Last Author
evangelos.tzaras
Last Edited
Apr 24 2021, 05:06

Event Timeline

jonas.smedegaard edited the content of this document. (Show Details)Jul 17 2017, 04:27
chris.lamb edited the content of this document. (Show Details)Dec 14 2017, 14:32
chris.lamb edited the content of this document. (Show Details)Dec 14 2017, 14:35
chris.lamb edited the content of this document. (Show Details)Dec 14 2017, 14:43
chris.lamb edited the content of this document. (Show Details)Dec 15 2017, 01:33
chris.lamb edited the content of this document. (Show Details)Feb 23 2018, 13:45
chris.lamb edited the content of this document. (Show Details)Feb 23 2018, 13:50
chris.lamb edited the content of this document. (Show Details)Feb 25 2018, 09:45
chris.lamb edited the content of this document. (Show Details)Mar 8 2018, 09:18
mak edited the content of this document. (Show Details)May 28 2018, 06:35
mak edited the content of this document. (Show Details)Jul 24 2018, 07:11
jeremiah.foster edited the content of this document. (Show Details)Jul 8 2019, 09:22
jeremiah.foster edited the content of this document. (Show Details)
jeremiah.foster edited the content of this document. (Show Details)
jeremiah.foster added a project: Restricted Project.Jul 8 2019, 09:34
jeremiah.foster edited the content of this document. (Show Details)Aug 1 2019, 18:21
jeremiah.foster edited the content of this document. (Show Details)Aug 2 2019, 08:17
jeremiah.foster edited the content of this document. (Show Details)Aug 2 2019, 08:33
jeremiah.foster edited the content of this document. (Show Details)Sep 11 2019, 14:40
jeremiah.foster edited the content of this document. (Show Details)Sep 11 2019, 14:50
jeremiah.foster edited the content of this document. (Show Details)Dec 10 2019, 13:37
mak edited the content of this document. (Show Details)Feb 17 2020, 15:59
jeremiah.foster edited the content of this document. (Show Details)Jun 23 2020, 10:59
jeremiah.foster edited the content of this document. (Show Details)Jun 23 2020, 11:02
jeremiah.foster edited the content of this document. (Show Details)
guido edited the content of this document. (Show Details)Feb 3 2021, 07:00
jeremiah.foster edited the content of this document. (Show Details)Feb 3 2021, 07:20
jeremiah.foster edited the content of this document. (Show Details)Feb 11 2021, 08:53
jeremiah.foster edited the content of this document. (Show Details)Mar 8 2021, 12:37
jeremiah.foster edited the content of this document. (Show Details)Mar 8 2021, 12:45
jeremiah.foster edited the content of this document. (Show Details)Mar 9 2021, 08:01
jeremiah.foster edited projects, added Restricted Project, Restricted Project, Restricted Project; removed Restricted Project.
jeremiah.foster edited the content of this document. (Show Details)Mar 9 2021, 08:05
jeremiah.foster edited the content of this document. (Show Details)Mar 11 2021, 13:30
guido edited the content of this document. (Show Details)Apr 19 2021, 03:28
guido edited the content of this document. (Show Details)Apr 20 2021, 02:06
guido edited the content of this document. (Show Details)Apr 20 2021, 02:16
guido edited the content of this document. (Show Details)Apr 21 2021, 00:53
evangelos.tzaras edited the content of this document. (Show Details)Apr 24 2021, 05:06

Feel free to delete my draft which arouse out of confusion around the Uploaders: field ;)

I would delete it myself, but have no clue how :O

guido edited the content of this document. (Show Details)Apr 26 2021, 03:48
guido published a new version of this document.
guido added a subscriber: guido.

@evangelos.tzaras no idea how one drops drafts but i think i restored the original version.

@guido

the main development branch should be called debian/latest

I believe that should be pureos/latest instead.

So would that be pureos/latest (instead of pureos/byzantium) and pureos/amber or pureos/amber-phone then?
Confusing!

guido edited the content of this document. (Show Details)Apr 28 2021, 02:45

@sebastian.krzyszkowiak , thanks fixed!

Using pureos/byzantium or pureos/amber with or without -phone is somewhat easier for me since it clarifies which branch is destined for which target suite. In my mind, pureos/latest points to the branch that you work from to create pureos/*.

  1. @guido Am I right in this thinking with pureos/latest?
  2. @evangelos.tzaras How can we make this less confusing?

I was mostly confused whether this would imply that we would have both pureos/latest and pureos/byzantium.

Might also have been a case of -ENOCOFFEE, so feel free to disregard the confusion ;)

guido added a comment.Apr 30 2021, 01:11

@evangelos.tzaras you only have *both* `pueros/latest and pureos/byzantium once byzatium is no longer the current development version. See https://dep-team.pages.debian.net/deps/dep14/ . The upside of pureos/latest is that you'd not be constantly busy with switching the repos default branch and name. It's basically the same as we do within DebianOnMobile with debian/master.

jeremiah.foster edited the content of this document. (Show Details)May 8 2021, 21:16
mak edited the content of this document. (Show Details)Nov 4 2021, 15:03