1. Building packages
    1. Adding packages
      1. Packaging methods
        1. 1. Meta-package
        2. 2. External repository
        3. 3. Within hackable:1 SVN repository
        4. 4. Third-party tarball
      2. About the patch file
    2. Building from SVN
      1. 1. Installing dependencies
      2. 2. Get fresh sources
      3. 3. Create source packages
      4. 4. Build binary packages
    3. Building from Debian
    4. Cross-compiling packages
      1. 1. The easy way
      2. 2. Manually
    5. Patching packages
      1. Using the bump.sh helper
      2. Using the mkdiff.sh helper
      3. Patching manually
    6. package.sh internals
    7. TODO

Building packages

Pierre wrote on 2009-01-06: Dear developers, I finally managed to patch, package and automate builds of most of the software used on hackable:1. (see this email)

Adding packages

The packages are currently listed in trunk/packages/packages.txt. Each line refers to a package, with the values aligned to fit nicely inside a 80 columns terminal.

The values are separated with tabs, the first ones being always the same:

method package name version revision additional arguments...

The interpretation of the additional arguments is up to the packaging method.

Packaging methods

1. Meta-package

Meta packages are found in trunk/src/meta, and do not contain any code: they only depend on a set of other packages.

They do not require any additional arguments, the definition being as follows:

meta package name version revision

2. External repository

Packages can be obtained from given revisions of other SVN repositories, making it easy to track the latest versions of popular packages not directly maintained by the hackable:1 team.

The package definition is as follows:

svn package name version revision repository tag

The repository must match a svn:externals entry in the SVN root. The tag can be either a revision number of the name of an actual tag.

3. Within hackable:1 SVN repository

Some packages are maintained by the hackable:1 developers.

src package name version revision path to the sources tag

The path to the sources is relative from the trunk/src directory. The tag can be either a revision number or the name of an actual tag.

4. Third-party tarball

Packages can be downloaded from an external website, for inclusion in hackable:1.

The package definition is as follows:

tar package name version revision URL of a tarball directory to the sources in the tarball (optional)

About the patch file

Each package supported has a corresponding trunk/packages/package_name/package_name.diff file, containing the packaging meta-data.

This patch is automatically applied to the sources when generating the actual Debian source package. It is the equivalent to Debian's diff.gz files, just stored in the SVN to track changes.

Creation of the patch file is documented below.

Building from SVN

It is possible to build all the packages at once, or select a particular package to build directly from the SVN repository.

1. Installing dependencies

You'll need at least the following packages installed:

  • automake1.9
  • bison
  • dpkg-dev
  • gtk-doc-tools
  • libapm-dev
  • libasound2-dev
  • libdb-dev
  • libdbus-glib-1-dev
  • libgconf2-dev
  • libglade2-dev
  • libmatchbox-dev
  • libmrss0-dev
  • libnotify-dev
  • libpulse-dev
  • libsoup2.2-dev
  • libstartup-notification0-dev
  • libwebkit-dev

Batch builds install the packages as they are generated.

2. Get fresh sources

Make sure you are in the right directory, and using the latest version of the repository: 

$ cd /path/to/hackable1/trunk/packages
$ svn up

3. Create source packages

To batch build, simply run the package.sh script with no arguments: 

$ ./package.sh

To build one package in particular, mention its name as the only argument to the same script: 

$ ./package.sh package_name

4. Build binary packages

You should have obtained a dists/wip/main/source folder from the previous step, which is directly suitable for upload.

Binary packages were also created in the process, however there was no way to make sure they would build correctly under any circumstance (eg with a correct Build-Depends field). Therefore, a special script was created to batch build the source packages: 

$ ./pbuilder.sh

Warning: among other things, this script assumes the sources can be obtained via apt-get source.

You should now have a dists/wip/main/binary-arch folder, also directly suitable for upload.

Building from Debian

The source packages are there:

...meaning for /etc/apt/sources.list: 

deb-src http://build.hackable1.org/debian wip main

The binary packages are there:

...again for /etc/apt/sources.list: 

deb http://build.hackable1.org/debian wip main

Cross-compiling packages

1. The easy way

First, make sure you have installed the cross-compiler.

You simply need to add one argument to the script, like this: 

$ ./package.sh DEBIAN_ARCH=armel

for a batch build, or: 

$ ./package.sh DEBIAN_ARCH ''package_name''

to cross-compile a package in particular.

2. Manually

Either obtain the source package with ./package.sh package_name or apt-get source package_name.

You need these variables set: 

$ export CPATH="/usr/arm-linux-gnueabi/usr/include"
$ export PKG_CONFIG_LIBDIR="/usr/arm-linux-gnueabi/usr/lib/pkgconfig:/usr/arm-linux-gnueabi/usr/share/pkgconfig"
$ export PKG_CONFIG_SYSROOT_DIR="/usr/arm-linux-gnueabi"

(this is done automatically when using package.sh with the DEBIAN_ARCH option)

Then change directory to the uncompressed sources and run: 

$ dpkg-buildpackage -rfakeroot -us -uc -aarmel

(-us -uc means to not sign the package, and change armel with your target architecture)

This should be working for all packages maintained within the hackable:1 project. If not, please file a bug.

Patching packages

Using the bump.sh helper

A step-by-step script was added, to help with the process of bumping revisions of software already packaged in hackable:1.

Position yourself in the trunk/packages directory, and run: 

$ ./bump.sh package_name full_version new_revision

The full_version has to include the SVN revision if relevant (eg 0.1+svn1234), but not the packaging revision.

You will then be prompted for a number of actions.

Using the mkdiff.sh helper

Once your package is satisfying, it is time to commit the changes for inclusion in the next daily build.

Position yourself in the trunk/packages directory, and run: 

$ ./mkdiff.sh package_name

Check the changes using: 

$ svn diff package_name

And if all is well: 

$ svn ci package_name

Beware that you need to either bump the package version or packaging revision to get it built. The trunk/packages/packages.txt database also has to be updated; using the ./package.sh helper ensures it is already the case.

Patching manually

Quick and dirty howto to get patches integrated to hackable:1's SVN easily, with neod as an example: 

$ cd packages/neod
neod$ tar xzvf neod_0.1+svn4878.orig.tar.gz
neod$ cd neod-0.1+svn4878
neod-0.1+svn4878$ patch -p1 < ../neod.diff
neod-0.1+svn4878$ chmod 755 debian/rules

[you can now work on the package using:
"fakeroot debian/rules binary"
and when it works:
"dpkg-buildpackage -us -uc -rfakeroot"]

neod-0.1+svn4878$ cd ..
neod$ dpkg-source -b neod-0.1+svn4878

[this will have regenerated a .diff.gz file]

neod$ gunzip -c neod_0.1+svn4878-1.diff.gz > neod.diff
neod$ svn diff neod.diff > patch-neod_my_changes.diff

Check if your changes look good! You can then either mail us the .diff.gz file, the .diff file, or the patch for our SVN repository]

Re-running ./package.sh detects the changed .diff, performs some sanity checks, and places the resulting .diff.gz file to "dists/wip/main/source". Beware, it will erase your modified sources in the process, so make sure you updated "neod/neod.diff" as shown here.

If you change the packaging revision in "debian/changelog", you also want to change it inside "package.sh".

package.sh internals

The package.sh script uses a number of variables internally, most of which can be overridden by the end-user:

Variable Description
BINARIES Path to the "Packages" file to update
BINARIESGZ Path to the "Packages.gz" file to update
CPATH Helps the C compiler locate include files when cross-compiling
CROSS_TARGET Description of the cross-compilation environment (eg "arm-linux-gnueabi", set automatically from DEBIAN_ARCH)
DEBIAN_ARCH The name of the Debian architecture to cross-compile for (eg "armel")
DEBIAN_DIST Name of the Debian release being created
DEBUG When set, enables debugging mode (the commands called are printed out, and their output is hidden except for errors)
MIRROR Path to the local Debian repository to be mirrored online
OVERRIDE Path to the override file
PACKAGES Content of the packages.txt database
PKG_CONFIG_SYSROOT_DIR When cross-compiling, tells pkg-config to prepend the path to libraries and include files (set automatically)
PKG_CONFIG_LIBDIR When cross-compiling, tells pkg-config where the definition files are (set automatically)
REPORT When set, the format of additional reporting information to generate (eg "html")
REPORT_FILE When set, the file where additional reporting information should be collected
SOURCES Path to the "Sources" file to update
SOURCESGZ Path to the "Sources.gz" file to update

TODO

Not everything is perfect yet, this needs more work:

  • testing the upgrade path;
  • testing the daily images;
  • testing more and over again...