Lumiera
The new emerging NLE for GNU/Linux

Building Lumiera becomes much simpler if you are using a Debian-based Linux system (e.g. Mint, Ubuntu…). Instead of having to build Lumiera and further required libraries step by step from source the classical (hard) way, you might prefer building from the Debian source packages.

Why so — what are the benefits?

  • let the Debian/Ubuntu package manager sort out the build dependencies

  • have a controlled environment where the build is already known to work

  • have a single common interface for starting any build process

  • install Lumiera as a first-class package, like all the other software you’re using regularly. So that the package manager “knows” about all the library dependencies and handles conflicts at next system upgrade.

Sometimes these very benefits might be a drawback; if you need more flexibility, you can treat the Debian tooling like a construction kit, where you can choose which part of the automation you want to employ…

There are various variants to consider:

  • Bootstrap into a newer distro version, by using only the source packages provided for another roughly similar platform

  • Use the prerequisite libraries from the DEB depot at Lumiera.org and only use our Debian source package to setup the build of Lumiera itself.

  • Avoid to add any (custom) Apt repository source: only download the source pacakge(s) and build them directly

Building from a Debian source package

A Debian source package is the complete “upstream” source tree plus a debian subdirectory with build configuration. This is a very controlled setup which allows the Debian build tooling to automate most of the build process.

Note Generally speaking, operations which modify the installation/configuration of your Linux system require root permissions. To the contrary, just building a package should not be done as root.
Prerequisites for building

For performing any compiling and packaging tasks, you need some additional software, which by default isn’t installed on a desktop system — most notably the GNU C compiler. On any Debian based system, you get this basic tooling by

sudo apt-get install build-essential devscripts equivs

The Lumiera DEB depot

At Lumiera.org/debian we provide the Debian packages maintained by the project in a setup that can be added as package source with your Apt package manager. If you trust us to do our work properly (are you really ready to trust us?), then installation and upgrades of the packages provided this way can be handled automatically

  1. add a suitable source spec to your Apt configuration

    (/etc/apt/sources.list.d/lumiera.sources)

    Types: deb deb-src
URIs: https://lumiera.org/debian/
Suites: trixie
Components: experimental
Signed-By: /etc/apt/keyrings/lumiera-keyring.gpg

  2. get and install Ichthyo’s GPG signing public key

    • This key has GPG key fingerprint 11FD F5D2 DBD7 BBD7 F4D9 D9C4 2CF2 5392 6238 2557

    • It can be found on many public keyservers, like Ubuntu or Openpgp.org.

      Important
      Apt requires a signing key installed into the system in binary format

      After fetching this public key, you need to store it in binary format at a suitable location (typically /etc/apt/keyrings), and owned by root (not writable by ordinary users). This location can then be referred to from the source configuration lumiera.sources — as showed above

      gpg --keyserver keyserver.ubuntu.com --recv 62382557
gpg --export 62382557 > lumiera-keyring.gpg

  3. you should be able now to refresh the package lists without any error… 

    sudo apt update

💡Tip: for added protection against unintended package upgrades, you may mark the Lumiera Apt source configuration with a lowered priority in the file /etc/apt/preferences

Package: *
Explanation: Lumiera-Repository
Pin: release o=Lumiera.org
Pin-Priority: 60

The default priority here is 500, and priorities < 100 will never be updated automatically.

How to build from a Debian source package

You need a work directory where to download, store and expand the DEB packages.
Over time, you will accumulate a lot of packages and sub directories there… 😀

Build dependencies

Install all build dependencies for a package
sudo apt-get build-dep <PKGNAME>

Complete build

Retrieve and immediately build from a source package
apt-get source --compile <PKGNAME>

Retrieve

Download and unpack source package from the Repositories
apt-get source <PKGNAME>

Unpack

Unpack a source package which you have downloaded manually
dpkg-source --extract <PKGNAME.dsc> [target-dir]

Build

Build DEBs from an already extracted source package
cd <package-subdir>; debuild -b

Tip

  • Obviously, all the package names, versions and architecture will vary, depending on your situation.

  • After building went through without error, it might happen that you’re be prompted for signing with your GPG key. But because you’re not going to upload the created binary packages anywhere, this step can be considered optional.

    Install created packages

    After a successful build, you’ll find several new *.deb packages in the directory above the source package tree. If you want to use those packages as prerequisites for the next package, you need to install these packages into your system using the basic Debian package manager dpkg 

    sudo dpkg -i <PCKGNAME.deb> [...]
    Clean up

    You can delete the source tree used for compiling. If you never intend to re-install the package, you could also delete the created package and source package components after installing it. But especially when trying out development versions it might be a good idea to stash those packages somewhere, as we’re not keeping every package in the online Lumiera Debian depot. While any package could be reproduced exactly with a bit of Git knowledge, just keeping the *.deb might be more convenient.

Bootstrap Lumiera starting from a source package

The following section describes the complete build sequence, where you start with the Lumiera source package repository, possibly even for another distribution. So, for example, you might be on Ubuntu/Resolute, but start from the source package entry in the Lumiera repository for Debian/Trixie.

  1. Add the source repository to your Apt configuration, as described above. Use the proper “Suites” entry; if this is anoter distro than you are currently on, you might want to use only the Types: deb-src (source packages, but not the binary packages)

  2. build and install NoBug

    • apt-get build-dep nobug

    • apt-get source --compile nobug

    • install with:
      sudo dpkg -i libnobug2_201008.1-4~trixie_amd64.deb nobug-dev_201008.1-4~trixie_amd64.deb

  3. build and install libGDL

    • apt-get build-dep gdl

    • apt-get source --compile gdl

    • install the libgdl-3-5*deb and libgdl-3-common*deb and libgdl-3-dev*deb packages

  4. build and install the C++ bindings GDLmm

    • apt-get build-dep gdlmm3

    • apt-get source --compile gdlmm3

    • install the libgdlmm-3.0*deb and libgdlmm-3-dev*deb

  5. now you are ready for Lumiera…

    • apt-get build-dep lumiera

    • apt-get source --compile lumiera

    If all went well, you can launch it right away as lumiera-0.pre.04/target/lumiera

That’s it — building the Debian way is convenient, isn’t it?

Building from Debian source package without Apt repo

This is a variation of the procedure and can be used when you can not (or do not want to) rely on the Lumiera DEB depot configured into your system. Instead, we somehow get / download and extract the respective source packages and then use the mk-build-deps helper from the devscripts to create a pseudo-package on the fly, which depends on all the build dependencies of a package.

  1. For this to work we somehow need to get the source package downloaded into the local system. There are several ways to achieve that

    • You may use Git to check out our Debian packaging repositories: 

      git clone git://git.lumiera.org/debian/nobug -b deb
git clone git://git.lumiera.org/debian/gdl   -b deb
git clone git://git.lumiera.org/debian/gdlmm -b deb
git clone git://git.lumiera.org/debian/lumiera -b deb

    • Alternatively, you may browse the package pool and download the packages with your web browser; note that for each source package, you need to download three components

      • the <PKGNAME>.orig.tar.xz (or .gz or whatever…)

      • the debianisation called <PKGNAME-VER>.debian.tar.xz

      • the source package descriptor <PKGNAME-VER>.dsc

      After downloading those components, you need to extract them manually:

      dpkg-source -x <PKGNAME.dsc>

  2. Next we need to install the build dependencies

    • step into the root of the extracted package tree

    • invoke sudo mk-build-deps --install --remove

      • if all works well, this will result in Apt proposing to download and install a huge load of further packages; confirm this with ‘y’ …

      • but it might happen that some dependency can not be satisfied, in which case mk-build-deps aborts and removes already installed parts. You need to figure out from the printed messages then what was the reason why the dependencies can not be satisfied (💡 in the case of Lumiera, typically the reason lies in the fact that nobug-dev, libgdl-3-dev and libgdlmm3-dev are not available from the official package repositories; you may need to build and install them yourselves…)

  3. Then, finally we can build the package itself:
    step into the package tree and invoke: debuild -b

Tip The mk-build-deps tool reads the package manifest and fabricates a pseudo-package, which is called <PKGNAME>-build-deps, (e.g. lumiera-build-deps). This package gets installed into your system and thereby “pulls in” all the required build dependencies. This setup remains in place even when you update your system, and thus ensures that the ability to build this package is not lost. Once you do no longer need this special configuration, you can manually remove this package (e.g. sudo apt remove lumiera-build-deps), and then clean-up by invoking sudo apt autoremove to get rid of all packages which are no longer required…

What follows is background information and configuration for advanced users.
💡 You can safely skip and ignore the remainder of this page if in doubt.

​
​
​
​

More about Debian source packages

Building packages from Git

This tutorial describes the classic way of building a Debian package, which also is the foundation for any shortcuts and convenience scripts. In practice, people maintaining Debian packages happen to use various shortcuts and helper scripts to automate repetitive tasks. One such helper especially worth mentioning is the tool git-buildpackage. With a little bit of configuration, this cleverly made tool is able to create a full Debian package just form a Git checkout in a single shot. At Lumiera.org, we maintain all our Debian packages this way, so the necessary configuration debian/gbp.conf is already in place.

To use the NoBug package for illustration, the procedure to build a package is:

  1. git clone git://git.lumiera.org/debian/nobug -b deb

  2. cd nobug; sudo mk-build-deps --install --remove

  3. gbp buildpackage --git-tag

→ more about our DEB depot at Lumiera.org

Required and recommended Debian packages

The Debian package manager stores for each package not only the required prerequisites, but also some additional recommended packages: This is software likely to make using the given package more convenient or improve the usage in some way. In addition, it also stores a list of suggested additional things to try. Now, since some time, the Apt package management tool by default automatically installs also the recommended software, not only the bare required prerequisites.

While this is certainly fine for users not interested in the details of package management, this setup has the downside of installing sometimes a lot of additional software no one ever asked about. Plus, all these installed packages are upgraded from time to time. An impressive example of this kind of bloat is the asciidoc package, which recommends to install Dockbook, a complete XML toolchain plus a Teχ distribution, giving you an average of additional 500MB to download and install.

Of course, this behaviour can be changed. Just add the following line to your Apt configuration

APT::Install-Recommends "false";

⚠Disclaimer: please be sure you understand the consequences…

Anatomy of a source package

Debian source packages provide a standardised way of compiling software. These packages are not intended to be installed on your system; rather you just download them and use them to build the software.

Each Debian source package is based on an original upstream tarball. In addition to this *.orig.tar.gz, there is a *.debian.tar.gz which contains all the modifications done to the original upstream sources in order to compile it with Debian. Especially, this so called “debianisation patch” adds a debian/ subdirectory to the source tree, which then holds all the control files used by Debian package management. Finally, the third part of each Debian source package is a manifest file (*.dsc), which states that this is a Debian package and contains the primary control informations, the name and version number. Of course, these three files are named with a common name prefix, which matches the “official” package name and version.

Quite frequently, a given source package generates several binary packages, e.g. the main program, maybe a library and a documentation bundle. Because of this, often the source package is named slightly different then the binary package, which can be a problem sometimes. If in doubt, use the Debian package search or the equivalent for Ubuntu to locate packages, versions, even individual files, or to get at the bug tracker for a package.

interesting files in the debian subdirectory

Most of the files in that subdirectory are relevant only for the people maintaining the package. With the exception of the following:

  • the debian/control file defines the properties and metadata of the package. Here you’ll find the definition of the prerequisites, the name of the packager, the explanatory text.

  • the top entry in the debian/changelog defines the actual package name and version

  • the actual build process is conducted by invoking several pre defined targets in the debian/rules makefile.

  • However, Debian packages typically rely on the Debhelper Sequencer to perform all the steps necessary for building a package.

    • see the Manpage and Debian-Policy §4.9

    • every step in that sequence can invoke a pre- or post- target and can also be overridden altogether in the debian/rules

Library development packages

When building software linked against some library, we need additional header files provided together with the library. Conventionally, these headers are packaged separately from the library and shipped as a package with a name like LIBNAME-dev. You can safely deinstall these development packages when done with building.