The Lumiera Debian Package ========================== :Author: Hermann Voßeler deb@ichthyostega.de :Date: 11/2011 //Menu: label Debian Package Since several of the Lumiera core developers run a Debian flavour as their primary development platform, it seems natural to care for the debian packaging of Lumiera ourselves. Moreover, we've declared Debian/Stable to be our *reference platform* -- we'll provide any additionally required, more recent packages through our own link:http://Lumiera.org/debian[Debian Apt-Repository] (Debian depot). TIP: readers new to Debian packages may want to have a look into our link:{ldoc}/user/tutorials/DebianBuilding.html[Debian build tutorial], where we describe the commands for building and explain the structure of a Debian (source) package in general Package build process --------------------- As our whole infrastructure relies heavily on the Git version management tool, it's only natural also to organise the (debian) packaging with the help of Git. Fortunately, there is a nifty tool called link:https://honk.sigxcpu.org/piki/projects/git-buildpackage/[git-buildpackage], written by Guido Günther exactly for this purpose: It treats the _debianisation_ as a branch in the Git repository, forking off the mainline at the release point. For Lumiera, this _debianisation branch_ is called 'deb' and can be found in the link:http://git.lumiera.org/gitweb?p=debian/lumiera;a=summary[git:/git.lumiera.org/debian/lumiera] repository. Installing Lumiera ~~~~~~~~~~~~~~~~~~ The link:SCons.html[SCons build] generates a relocatable distribution directory structure, holding the main executable, additional tools and utilities, plus the core libraries and resources. Here _relocatable_ means that this subtree can be moved and placed anywhere on the system. As long as the relative directory layout remains intact, the executables will be able to find and load the accompanying libraries and resources. By invoking the `scons install` target, this directory structure is placed into the installation target directory. Actually, this lookup process at application startup is performed in two phases - in the first phase the main application locates the explicitly linked shared libraries. footnote:[generally speaking, we have to distinguish between dynamic libraries explicitly linked as part of the application, libraries linked as direct library dependencies, other transitive library dependencies, and finally shared objects, which are loaded at runtime through the `dlopen()` call.] Especially those libraries belonging first class to the Lumiera application are built with a relative search path ('rpath' with `$ORIGIN` token). These libraries are placed into the +modules/+ subfolder - after successfully launching the executable, the second phase performs a lookup programmatically, starting from the path location of the executable. The goal is to find a +setup.ini+ which defines additional plug-ins and resources to load. Notably, the GUI to launch is loaded as a plug-in through this mechanism. Moreover, this *bootstrap configuration* defines the additional platform and user configuration to load for further outfitting of the system. LSB Installation Layout ~~~~~~~~~~~~~~~~~~~~~~~ This organisation is used as foundation for packaging and installing. The primary application distribution structure will be located into a subfolder below +/usr/lib/+. Only the main application executable will be symlinked into +/usr/bin/+. The LSB explicitly allows for such a layout, which is typically used by large application bundles (OpenOffice, Gimp, Eclipse). Since the application startup encompasses two phases, loading the extended configuration programmatically after launching the application, extended resources from the application bundle can easily be relocated into a separate folder below `/usr/share/`, as required by LSB. Releases, Branches and Conventions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Official releases are marked by a tag on the master branch. At that point, master should be in good shape, release documentation is polished; experimental features are removed or disabled. Usually, we'll also fork a *release branch* at that point, featuring bugfixes only. From here we'll merge to the **debian branch**footnote:[the 'release' branch will be merged back at times, while the 'debian' branch won't. This 'debian' branch is published through a separate link:git://git.lumiera.org/debian/lumiera[debian/lumiera git repository] and not merged back, since all tweaks here are strictly for debian packaging. There might be other packaging related repositories in the future. Yet still, the 'debian' branch is based on the same common tree and can in therory kept in the same git repository. Contrast this to the branch 'depot', which is also published through our 'debian/lumiera' git repository. This latter branch corresponds to a completely separate tree and holds the administrative part of our link:http://Lumiera.org/debian[Debian package depot] (Repository) on Lumiera.org.] Typically the release will lead to the discovery of more or less serious bugs, which are fixed on the release branch and backported to master. The result is a sequence of point releases. At the end of a stable release series, the release branch will be upgraded with a single merge commit to the level of the next major release. Package build commands ~~~~~~~~~~~~~~~~~~~~~~ To (re)build the debian package . +git clone git:/git.lumiera.org/lumiera/debian+ . +mkdir pack.deb+ . +cd debian+ . +git-buildpackage --git-upstream-branch=+ _RELEASE-TAG_ -- here _RELEASE-TAG_ denotes the point in the Git history, which should become the reference source and be packaged into the *.orig.tar.gz. Usually, it's just sufficient to use branch 'release' for that purpose. Debian-Depot for installation via Apt ------------------------------------- In addition to the packaging, we maintain a dedicated Apt-Repository for automated installation and upgrades. We try to build the package for several Debian derived distributions (like Ubuntu). -> link:../infra/debianDepot.html[more on the repository organisation]