Ichthyostega
797174ef19
On the Website, there is a set of interconnected pages related to compiling from source, the Debian package and our DEB depot. Although these pages have always been superficially kept up-to-date, the overall presentation feels dated and generally not well organized. During the last weeks, I have almost entirely rewritten all those pages, added information about the (now reworked) DEB package, explained the alternate ways to build from a Debian source package (notably the `mk-build-deps` for handling the build dependencies, which effectively the only method which always worked during the last years, since our DEB package was totally outdated) Furthermore, I have tested most of the build steps with the current source trees, repositories and package definition, and finally I have also updated and polished the front-page of our DEB-Depot (-> see commit on the depot-Branch) Wheew ... quite some work done!
151 lines
8.5 KiB
Text
151 lines
8.5 KiB
Text
The Lumiera Debian Package
|
|
==========================
|
|
:Author: Hermann Voßeler deb@ichthyostega.de
|
|
:Date: 11/2011 · 11/2025
|
|
|
|
//Menu: label Debian Package
|
|
|
|
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 link:/debian[Debian DEB depot] (for the Apt package manager).
|
|
|
|
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 seems natural
|
|
to organise also 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.
|
|
~ -> see also https://wiki.debian.org/PackagingWithGit[Debian packaging with Git (Debian Wiki)]~
|
|
|
|
For Lumiera, this _debianisation branch_ is called 'deb' and can be found in the Repository
|
|
https://git.lumiera.org/gitweb?p=debian/lumiera;a=summary[git://git.lumiera.org/debian/lumiera].
|
|
|
|
Installing Lumiera
|
|
~~~~~~~~~~~~~~~~~~
|
|
The link:SCons.html[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.footnote:[
|
|
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
|
|
https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard[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 link:{ldoc}/technical/build/SCons.html[SCons build system],
|
|
as this helps to keep the Debian packaging as simple as possible. Please have a look at the
|
|
-> https://git.lumiera.org/?p=debian/lumiera;a=blob;hb=refs/heads/deb;f=debian/control[control file]
|
|
· https://git.lumiera.org/?p=debian/lumiera;a=blob;hb=refs/heads/deb;f=debian/rules[debian/rules]
|
|
|
|
- we rely on the _Debhelper Sequencer_ "`dh_*`" in our 'debian/rules' +
|
|
-> https://manpages.debian.org/trixie/debhelper/dh.1.en.html[Manpage]
|
|
· https://www.debian.org/doc/debian-policy/ch-source.html#s-debianrules[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 link:{ldoc}/technical/code/GitBranching.html[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**.footnote:[
|
|
This _debian branch_ is called `deb` by convention. As mentioned above, it is published through
|
|
a separate https://git.lumiera.org/?p=debian/lumiera;a=summary[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 https://git.lumiera.org/?p=debian/lumiera;a=shortlog;h=refs/heads/depot[depot]
|
|
and is related to our link:/debian[DEB package depot] on Lumiera.org. This branch carries a completely
|
|
different directory structure, since it is used with the
|
|
https://wiki.debian.org/DebianRepository/SetupWithReprepro[»reprepro« tool from Debian]
|
|
to manage the contents of that depot.
|
|
|
|
|
|
Package build commands
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
To (re)build the debian package
|
|
|
|
. step into a packaging work directory
|
|
. `git clone git://git.lumiera.org/debian/lumiera -b deb`
|
|
. `cd lumiera`
|
|
. `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).
|
|
-> link:{ldoc}/technical/infra/debianDepot.html[more on the repository organisation]
|
|
|