Lumiera
The new emerging NLE for GNU/Linux

Since several of the Lumiera core developers run a Debian flavour as their primary development platform, it seems obvious also to care for the Debian packaging of Lumiera. Furthermore, we have declared Debian/Stable to be our reference platform — and we will provide any required additional packages through our own Debian DEB depot (for the Apt package manager).

Tip readers new to Debian packages may want to have a look into our 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 seems natural to organise also the (Debian) packaging with the help of Git. Fortunately, there is a nifty tool called 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. → see also Debian packaging with Git (Debian Wiki)

For Lumiera, this debianisation branch is called deb and can be found in the Repository git://git.lumiera.org/debian/lumiera.

Installing Lumiera

The SCons build generates a distribution directory structure, which is relocatable, comprising 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 install target, this directory structure is placed into the target installation directory, with an layout conforming to the Filesystem Hierarchy Standard.

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.
    [ Generally speaking, we have to distinguish between dynamic libraries explicitly linked as part of the application, libraries marked and linked as direct library dependencies, other transitive library dependencies, and finally shared objects, which are loaded at runtime as »plug-in« through the dlopen() call. ]
     Some parts of the Lumiera code are built as shared library, but are non the less considered a mandatory part of the application. Especially those libraries are built with a relative search path (rpath with $ORIGIN token), and will be placed into the modules/ subfolder This implies that the dynamic linker will look for this subfolder in the same directory as the lumiera executable and will fail to launch the application unless all those further mandatory application components can be located.

  • after successfully launching the executable, the second start-up phase performs a programmatic lookup, starting again from the path location of the executable. The goal is to find a file 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.

FHS Installation Layout

So this organisation of the application executables and resources into an installation bundle in a subdirectory tree is used as foundation for packaging and installing. The primary application distribution structure with all the executable code will be placed into a sub-tree below /usr/lib/lumiera. Only the main application executable lumiera will then be symlinked into /usr/bin/. This pattern is in accordance with the Filesystem Hierarchy Standard (FHS), and it is typically used by large application bundles (e.g. Libreoffice, Firefox-esr). Since the application startup of Lumiera encompasses two phases, where loading the extended configuration happens programmatically after launching the main application, all extended (platform-independent) resources from the application bundle can easily be relocated into a separate folder below /usr/share/lumiera, as required by FHS.

How the Lumiera Debian package works

Since we maintain both the Debian package and our build system, we can always try to do the heavy lifting in our SCons build system, as this helps to keep the Debian packaging as simple as possible. Please have a look at the → control file · debian/rules

  • we rely on the Debhelper Sequencer "dh_*" in our debian/rules
    → Manpage · Debian-Policy §4.9

  • but we define three override targets in order to invoke SCons explicitly, so that it is immediately clear what configuration is passed to the build.

  • we configure SCons with INSTALLDIR=debian/lumiera PREFIX=usr, and thus the installation will happen below debian/lumiera, which is the location expected by the following DEB building steps

Releases, Branches and Conventions

Lumiera uses the Git-flow branching pattern to organise releases and patches in the Git history. All official releases are marked by a tag on the master branch. This tag is published in the primary Lumiera repository at git://git.lumiera.org/LUMIERA at the time of the release. Bugfixes are also merged into master and marked with a tag there.

For the actual packaging, we use these release tags as upstream tag and perform a merge from that tag into the debian branch.
[ This debian branch is called deb by convention. As mentioned above, it is published through a separate Git repository git://git.lumiera.org/debian/lumiera, which is kept separate, since packaging is considered a “downstream process”. ]
 This branch carries only the additions and tweaks done for debian packaging. Yet still, this deb branch is based on the common tree of the codebase and could in theory be kept within the same Git repository as the master branch. When the packaging process is complete, the published DEB version is marked with a tag debian/<full_debian_version_spec>

Note however that there is another branch in the aforementioned debian/lumiera repository, which is called depot and is related to our DEB package depot on Lumiera.org. This branch carries a completely different directory structure, since it is used with the »reprepro« tool from Debian to manage the contents of that depot.

Package build commands

To (re)build the debian package

  1. step into a packaging work directory

  2. git clone git://git.lumiera.org/debian/lumiera -b deb

  3. cd lumiera

  4. gbp buildpackage

Typically you will have to install some build dependencies before you can build the package. This can be checked by invoking dpkg-checkbuilddeps from within the package directory (here lumiera). These dependencies can be managed automatically with the Debian tooling, by using one of the following two alternative solutions

  • apt-get build-dep lumiera (requires Lumiera DEB depot in the apt sources)

  • invoking mk-build-deps from within the package directory (requires equivs package)

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). → more on the repository organisation