T2 package creation tutorial

This is a short introduction how package descriptions in T2 are created. We try to give a good overview and focus on examples. For detailed and complete information read the corresponding sections in the handbook.

All examples are extracted from real T2 packages and linked to the corresponding files in our T2 Subversion trunk. However, since T2 development is steadily going on, it may happen that code sniplets actually differ from the linked content. We try to keep this tutorial up to date, though you may even encounter some dead links in case a package has been (re)moved.

Last tutorial update: T2 revision r25075 (2007-07-19)

Introduction

In T2 packages consist of as least code as possible. This does not only save time while creating a package, it also saves time while updating a packages as not much code has to be reviewed during each update. Additionally it also allows T2 targets the flexibility to build packages differently, with other options, patches or only install a sub-set of the files the packages installs by default.

The packages are located in the package/ directory grouped into several repository such as base/, xorg/ and so on.

A T2 package consists of at least a .desc file - holding the package's meta data, an optional .conf file - holding the script code (if any), and a .cache file - containing the deteccted dependencies, buildtime and size. The .cache file is automatically generated by the T2 build system and only needs to be copied by the initial package creator after a successful test from /var/adm/cache/ to the package directory. As the .cache file also holds the dependencies, the build system will fill the dependencies as detected by the used .h, .a, .so and simillar files during the build in the T2 sandbox.

A simple package example

Let's take a look into a package's .desc, for example: package/develop/libsigc++/libsigc++.desc

[I] Typesafe Signal Framework for C++

[T] This library implements a full callback system for use in widget libraries,
[T] abstract interfaces, and general programming. Originally part of the Gtkmm
[T] widget set, Libsigc++ is now a seperate library to provide for more general
[T] use ... (truncated)

[U] http://libsigc.sourceforge.net/

[A] Karl E. Nelson <kenelson@ece.ucdavis.edu>
[A] Tero Pulkinen <terop@students.cc.tut.fi>
[M] Rene Rebe <rene@exactcode.de>

[C] extra/development

[L] LGPL
[S] Stable
[V] 2.0.1
[P] X -----5---9 122.000

[D] 1262812507 libsigc++-2.0.1.tar.bz2 http://dl.sourceforge.net/sourceforge/libsigc/

As noted earlier the file consists of key's ([A], [D], [V], ...) and values for the keys. It looks a little like if an array is filled in a programming language

The keys used are abbreviations for Author, Download, Version and in fact the long versions could have been used such as:

[AUTHOR] Karl E. Nelson <kenelson@ece.ucdavis.edu>
[DOWNLOAD] 1262812507 libsigc++-2.0.1.tar.bz2 http://dl.sourceforge.net/sourceforge/libsigc/

But most developers prefer the short form as that's less to type :-). A comprehensive descriptions is available in the handbook.

Most of the tags are just of informal character for either the developers or the end-user installer, the nearly only important tags for the build system are the Priority tag ([P]) as well as the Download tag ([D]).

The easiest way to create a new package is to just copy a simillar existing package and update the tags. Additionally a tiny helper scripts is available to obtain the meta-data from Freshmeat.net and must be called with the location to store the T2 meta data and the freshmeat project name, for example:

./misc/archive/fmnewpackage.sh package/develop/boost boost

The fmnewpackage.sh scripts tries to do it's best to fill out as much tags as possible, but depending on the Freshmeat.net data some tags might be left with a TODO note.

Testing the new package

As soon as the package's .desc was create the package can be tested using the normal T2 way to build a single package:

scripts/Emerge-Pkg boost

Which, depending on the type and nature of the package most often alread succeeds at the first try (due T2's automatic build system)!

Fixing a package to build

As noted earlier the automatic build system of T2 recognizes quite some different build systems of packages, including but not limitted to normal Makefiles, GNU/Autoconf, Perl and Pyton modules and uses sane defaults (depending on the actual build configuration) to build the package. Only if the package is not modelled after a recognized build style, or does not build with the compiler used in T2 further coding is required.

If the package does just not build, or crosss build the patch resuling from fixing the package's source can just be dropped with the extension .patch into the package directory. The T2 build system just applies all .patch files, automatically.

Other packages might require special arguments for the configure scripts, make, make install which can be added to the .conf file in the following way:

var_append confopt ' ' '--with-threads'
var_append makeopt ' ' 'utils'
var_append makeinstopt ' ' 'install-utils'
and if a package has no install target, the make install step can be disabled and the files installed manually with:
makeinstopt=''
hook_add postmake 5 'install some-file $root$bindir/'

For further documentation about the (endless) possibilities in .conf file the the handbook or the T2 mailing list.

Adding the cache file

Once the package built and was verified to work, the generated cache file can be copied into the package directory:

cp /var/adm/cache/boost package/develop/boost/boost.cache

so that the dependencies are also available to other people building the package.

Sending in the new package

To share your work with all the other T2 developers and users it's best to send the newly created files to the T2 mailing list.