Revision of Package helpers from Mon, 11/18/2013 - 09:38

There are a set of scripts used to build trisquel packages. They are located in devel.trisquel.info/gitweb/?p=package-helpers.git;a=summary/ , and we call them helpers. We use them to modify and compile those packages coming from Ubuntu upstream which need it. It might be because they contain non-free stuff, references to Ubuntu that need to be changed, or because we want the package to work our way.

This helpers are similar to some of those in the gNewSense builder; we took some ideas and even some lines from them. If you plan to build an Ubuntu derivative of your own, we suggest you use builder instead of these helpers.

All packages in this list are in the appropriate blacklist in the repository updater, so they never enter into the repo from upstream and need to be compiled with this helpers and pushed into reprepro.

These helpers also need to be run by hand (and the results tested) any time the repo watchdog warns about pending updates from upstream.

To add a package to the list, just copy one (make-apache2 is a good template) and rename it to make-sourcePackageName. To send the file back to us, or to include any modification into the current scripts, use "git diff" and send the output as an attachment to trisquel-devel@listas.trisquel.info. You need to join the mailing list to send messages to it.

Some recommendations:

• Take care to use the right sourcePackageName, many source packages produce several binary packages. "apt-cache showsrc binary-package" can help you.
• If possible, use sed to replace chains in the upstream source without the need of external files or patches. If you really need to include a file, place it at the DATA/sourcePackageName directory
• Do not replace *all* references to Ubuntu in the package, just those that would actually be shown to the user. Avoid replacing copyright statements!
• Try to write your replacements in a way they might work in future versions of the upstream package. Well written regexps and sed will help with that.

Compiling packages with the helpers

You should run this in an amd64 computer, otherwise you can only compile i386 packages (after modifying makepackage to remove the amd64 steps).

Prerequisites

To properly compile packages using package helpers you need to install some packages to begin with:

sudo apt-get install git debootstrap devscripts reprepro

You'll need to configure git to have your user details, make the obvious replacements with your own details

git config --global user.name "Your Name"
git config --global user.email your_email_address@example.com

And colored output is helpful

git config --global color.ui auto

Building a package

First, get a copy of the helpers and management scripts using git:

git clone git://devel.trisquel.info/package-helpers.git
cd package-helpers
git checkout toutatis

Changing toutatis for whichever Trisquel release you want to work on. So you can keep track of the the official git head it is better to follow normal git workflow and create a separate branch for each unit of work . So for example if you were working on Issue 1234 then you would do:

git branch issue1234
git checkout issue1234

Then after your edits, builds and tests when you are ready to ship your patch do a

git commit

Then use the git format-patch command to create an email, load it into your mailer by copying it into its local mail folders after removing the 'magic' additional From line and submit it to the trisquel-devel mailing list.

You'll need a copy of the package source as a basis to code and test your sed/awk command for the changes. Doing this within a chroot to avoid cluttering your daily system is outside the scope of this guide. (The best place to start of all such developer techniques is by reading package maint-guide. If it doesn't tell you how it will tell you where the info can be found.) Using the Trisquel package source is good enough for nearly all cases:

sudo apt-get build-dep package-name
sudo apt-get --build source package-name

The --build option on the last command causes a full package build. It's well worth doing this first as upstream FTBFS (Fails To Build From Source) errors are far from unknown. File an upstream bug if you definitely have one.

If you now cd into the package-name-release directory and you're in the same relative place package helper sed scripts are run. Further a dpkg-buildpackage here will test if your changes do actually build. Although testing the debs themselves is best left until after you have a debugged package helper as you will have to test again at this point.

Then when you've turned you sed commands into a package helper in the package-helpers directory of your git repo you can compile the package using the package helper. In the top directory of your git repo run the makepackage command as in this example:

sudo bash makepackage apache2

The makepackage script will create and configure the compilation jails, as well as the output repository.

Writing new helpers

List of available variables inside the helper scripts

CODENAME=toutatis

The codename of the current Trisquel release

REVISION=6.0

The version number for the current Trisquel release

UPSTREAM=precise

The upstream codename for the release

MIRROR=http://archive.ubuntu.com/ubuntu

The upstream mirror from where to get the sources

DEVELMIRROR=http://devel.trisquel.info/trisquel

The development mirror

Useful when a package depends on other that needs to be trisquelized first

LOCALMIRROR=http://archive.trisquel.info/trisquel # The official mirror

EXTERNAL="deb-src http://sample.repo.foo/ current main"

Makes the sources in that repository available for compilation

It will only be used if Ubuntu doesn't provide the package or its version is lower

$DATA/

Directory containing files for the helper

Put the files in helpers/$RELEASE/DATA/$PACKAGE

Usage example: cp $DATA/file.txt debian/patches

VERSION=1

Trisquel version to append (as in 2.4-1ubuntu4+5.0trisquel1)

We append "+6.0trisquel1", which is +${REVISION}trisquel${VERSION}

Increase every time the helper is updated

COMPONENT=main

Tells the build system that the package comes from main, so the translations should be stripped

Use only when the rebranding doesn't affect the locales!

FAKEROOT=true

Tells the build system to use a fakeroot and compile as user "nobody"

PARALLEL=true

Do not compile with -j$NUM_PROCESSORS, required by some packages like samba

More information

• Package helpers: README
• Git Documentation