d1h, the Devuan packaging helper

In this guide we will show how d1h can be used to speed-up package maintenance in Devuan. After having read this document, the reader should be able to import a Debian package in Devuan, and have their package included in the Devuan building workflow.

Before you start, you need the following packages installed in your system:

• debhelper and all the usual stuff needed to build Debian packages
  • (lintian, build-essential, cdbs, dh-make, fakeroot, and so on…)
• git
• git-buildpackage
• gpg (for package signing)

On top of that, you should also have:

• a working account on git.devuan.org
• the environment variables DEBEMAIL and DEBFULLNAME set, respectively, to your email and to your full name, e.g.:

  DEBEMAIL=fred.bloggs@example.com
  DEBFULLNAME="Fred Bloggs"
  export DEBEMAIL DEBFULLNAME

• a working Internet connection

The package d1h is currently in experimental. In order to install it, you should add the following line to your /etc/apt/sources.list:

  deb http://packages.devuan.org/devuan/ experimental main

then run:

  # apt-get update

and finally:

  # apt-get install -t experimental d1h 

As an example, we assume in this guide that we want to import the package “adduser” to Devuan Jessie. Actually, there is no need at all to import this package, since it does not depend on systemd (so far). But this is a relatively small and self-contained package to start with.

Create a new project on your git.devuan.org account, called “adduser”. This new project will be associated to a git URL in the form:

  git@git.devuan.org:USERNAME/adduser

where USERNAME is your username on git.devuan.org. In the following, we will denote by DEVUAN_REPO the URL associated to your project on git.devuan.org.

Create the d1h repository cache:

  $ d1h cache

This will download the full list of repos hosted at https://anonscm.debian.org, parse it, and save a cache in ~/.d1h/cache.

It is not necessary to create the cache every time you use d1h, but it is recommended to run “d1h cache” every now and then.

Search the upstream git repo of “adduser”. Here d1h comes in handy:

  $ d1h search adduser
  ##########################
  #### cache last updated on  Fri  7 Apr 21:19:30 BST 2017 
  ##########################
  adduser/adduser: https://anonscm.debian.org/cgit/adduser/adduser.git/
  $ 

Notice that d1h has found only one repository matching our query “adduser”. Note down the corresponding URL

https://anonscm.debian.org/cgit/adduser/adduser.git/

The “search” function accepts multiple strings (separated by spaces). If more than one string is provided, “search” will look for a repo matching all of them.

Enter the folder where you would like to keep the package repo, and import the “adduser” repo:

  $ d1h import https://anonscm.debian.org/cgit/adduser/adduser.git/

You can alternatively provide to “import” a destination folder as second argument:

  $ d1h import https://anonscm.debian.org/cgit/adduser/adduser.git/ ./pkg_adduser

In this case, the repo “adduser” will be imported under the folder “./pkg_adduser”.

When “import” has finished, you will find the repo “adduser” under the destination folder (or in the current directory, if no destination folder was provided).

(*) For the git-savvies: “import” corresponds to a “clone”.

Now we need to link our new “adduser” repository with the DEVUAN_REPO we have created on git.devuan.org. Just chdir to the folder where your repo has been imported, and give the command:

  $ d1h link DEVUAN_REPO

where DEVUAN_REPO is the git URL of your project on git.devuan.org, e.g. something like

  git@git.devuan.org:KatolaZ/adduser

This URL will be indicated in the home page of your project on git.devuan.org.

(*) For the git savvies: “link” resets the origin of your repo, to let it point to, e.g., DEVUAN_REPO. After “link” has finished, DEVUAN_REPO will be the origin of your local “adduser” repo.

Now we should prepare the suite for which we would like to build the package. We assume that we want to build the package for “jessie”. However, new packages never go directly into a release main repository (with the only exception of the “experimental”). Instead, a new package for “jessie” is normally added to “jessie-proposed”. So we need to prepare the suite “jessie-proposed”:

  $ d1h prepare jessie-proposed

This step should be done only once.

(*) For the git-savvies: the “prepare” action creates a new branch, in this case named “suites/jessie-proposed”, and adds the appropriate “debian/gbp.conf” file to it.

Before we start working on modifying the package for jessie-proposed, we must first “switch” to the corresponding suite:

  $ d1h switch jessie-proposed

(*) For the git-savvies: “switch” is simply a checkout to the corresponding branch.

Now that we have switched into the suite “jessie-proposed”, we must reset the repo to the correct version of the package. Since we want to package for jessie, we MUST ensure to work on EXACTLY the same version of the package available in jessie. In this case, the version of “adduser” available in jessie is 3.113+nmu3. You can easily check using:

  $ apt-cache policy adduser

Luckily, the repo we have imported from Debian keeps track of this information through a tag. In order to retrieve the correct version of the package for jessie, we can run:

  $ git reset --hard tags/3.113+nmu3

You can now make all the changes you need to the package. In this specific case, we don't have to do anything in particular, since the package does not depend on systemd. We will just edit the “debian/control” file with our preferred editor, and put our name and email in the “Maintainer:” field. We will also remove the field “Uploaders:”, and save the file.

When we are done with the changes, we just commit everything:

  $ git add --all
  $ git commit

The “commit” command will open an editor asking to insert a message for the commit. In this case, we can just insert “Devaun version of adduser”, save the file, and quit the editor.

It is time to build the package. This can be done through the command:

  $ d1h testbuild

This command will start building the package. If it complains about a missing package, just “apt-get install…” the missing dependencies as needed, and run it again. If you have all the needed dependencies installed, the build will proceed and create the following files:

  adduser_3.113+nmu3_all.deb
  adduser_3.113+nmu3_amd64.changes
  adduser_3.113+nmu3.tar.gz
  adduser_3.113+nmu3_amd64.build
  adduser_3.113+nmu3.dsc

in the parent folder of the repo. This time the command “testbuild” will complain about not being able to sign the package, and it will terminate with a “testbuild error”. You can safely ignore this error: it is due to the fact that you have not yet edited the file “debian/changelog”. This is what we will do in a moment.

You should now test the .deb package you have just created, e.g. by installing it:

  # dpkg -i adduser_3.113+nmu3_all.deb

When you are sure that the package works as expected, it is time to assign a version number to it, using the command:

  $ d1h stage 3.113+nmu3+devuan1.1

where 3.113+nmu3+devuan1.1 is the new version number. It is warmly recommended for Devuan-ised packages to retain the same version number of the corresponding Debian package, with a “+devuanX.Y” label appended, where “X” and “Y” indicate the Devuan major/minor version of the package.

(*) For the git-savvies: the command “stage” will run “gbp dch” to assign a new version to the package. It will also create a tag for the new version, push the repo to origin (well, to DEVUAN_REPO), and push the tags.

At this point, your package might be ready to be added to the Continuous Integration (CI) server at ci.devuan.org. In order to do that, you should contact a Devuan developer on the #devuan-dev IRC channel (freenode network), who will guide you through the process. This will usually involve moving your DEVUAN_REPO under the group “devuan-packages”.

After your package has been revised from other developers and added to the CI server, you will be able to request a build. This is done by opening a new special “Issue” on the gitlab page of the repository. This issue should have title equal to “build”. It is very important to specify a label as well, since the label determines which branch will be built and where the resulting packages will be put. In our example, the package “adduser” should go in jessie-proposed, so we will use the label “jessie-proposed”. The issue must be assigned to “autobuild”.

You can check the status and health of your builds on

  http://ci.devuan.org

Moreover, messages about build successes and failures are also reported on the IRC channel #devuan-dev in real-time.

Source: https://dev1galaxy.org/viewtopic.php?pid=1110#p3563

For situations where one is starting from an existing Devuan project, there are some alternate and/or additional steps. These steps begin partway down the d1h workflow.

* Make a directory to work in

  $ cd
  $ mkdir -p Devuan/reportbug8
  $ cd Devuan/reportbug8

Get a copy of the repository

  $ gbp clone https://git.devuan.org/devuan-packages/reportbug.git

or, equivalently:

  $ git clone https://git.devuan.org/devuan-packages/reportbug.git reportbug

Then, dive down into the directory which contains the repository

  $ cd reportbug

KatolaZ has suggested I put my repo in 'suites/ascii-proposed'.

  $ d1h prepare ascii-proposed

  $ d1h switch ascii-proposed

Here I had a problem. My system is at version 'jessie'. Apt-cache policy reportbug shows:

  reportbug:
    Installed: 6.6.3+devuan1.3
    Candidate: 6.6.3+devuan1.3
    Version table:
  *** 6.6.3+devuan1.3 0
          500 http://ca.mirror.devuan.org/merged/ jessie/main amd64 Packages
          100 /var/lib/dpkg/status

But I want to continue on from the version in ascii.

The solution is/was: take a look at ascii to find a version number or tag

  $ d1h switch ascii

'gitk' shows the head is tagged '7.1.6+devuan2.1', so switch back to the branch I will be using, and do the 'git reset':

  $ d1h switch ascii-proposed
  $ git reset --hard tags/7.1.6+devuan2.1

There is some clean-up required. The 'git reset –hard' changes 'debian/gbp.conf'; so

  $ (edit debian/gbp.conf; change it back to 'ascii-proposed')

In debian/control:

• added myself to the 'Uploaders:' line.

In reportbug/init.py:

• set a new version (7.1.6+devuan2.2)

Commit all outstanding changes.

Update the changelog file:

  $ d1h bump 7.1.6+devuan2.2

commit the modified changelog

Do the test build

  $ d1h testbuild

gpg key

You will need to have created a gpg key set

  $ gpg --gen-key

Upload the public key

  $ gpg --send-keys --keyserver hkp://keys.gnupg.net <key id, or fingerprint>

gitk gitk is great. fire it up as soon as you have changed to the repository directory. Use it to start git-gui, git-gui makes 'commits' easy.