Building Lumiera from source ============================ :Date: 2025 :toc: At the moment you can build Lumiera, start the standard Lumiera GUI and run the Lumiera test suite. The GUI you start might look like a mockup, but in fact is _is_ the real application; just there isn't much wiring between GUI, model and core yet. This will remain the state of affairs for the foreseeable future, since we're developing core components against a test suite with unit and integration tests. Thus, the growth of our test suite is the only visible indication of progress. This tutorial outlines the fundamental steps required to compile Lumiera on Linux (or a comparable) system. We'll assume that you have a certain familiarity with _commandline survival skills_ on your system. To help you getting started, this tutorial lists all the necessary commands explicitly. footnote:[there are some minor differences between the various Debian based distributions, thus the exact version numbers and package names appearing in our example commands might be slightly different on your system] There are two distinct methods to build: - use the Debian source code package of Lumiera (the »Debian way«) - use Git to retrieve all source code and build the »classical way« NOTE: just compiling Lumiera on a _Debian-based_ system (e.g. Mint, Ubuntu...) is much simpler when using the Debian source package. See the separate link:DebianBuilding.html[tutorial page] for this footnote:[besides, there is a separate page with general link:/debian/[instructions for installing on Debian/Ubuntu]).] The purpose of this tutorial here is to show you the elementary and generic steps to compile Lumiera from source. Requirements ------------ To build Lumiera, you'll need a _build environment_ together with the _development packages_ of the libraries Lumiera depends on. footnote:[there is a separate documentation page listing the link:{ldoc}/technical/build/BuildDependencies.html[build dependencies] explicitly. We'll try to keep that information up to date -- but in the end, the really authoritative information about the build dependencies is encoded into the link:{ldoc}/technical/build/SCons.html[build system]. Thus, when the build system aborts, indicating that a never version of some library is required, then usually the build system is right...] More specifically, you'll need the GNU C/C\++ compiler with C++23 support (Version >= 14) in addition to the following tools and libraries: * https://git-scm.com/[Git] (version management system) * https://www.scons.org/[SCons build system] * https://www.boost.org/[Boost libraries] * https://github.com/bplaum/gavl[GAVL library] * https://nobug.pipapo.org/[NoBug] ~([purple]#⚠ see below#)~ * Lumiera https://git.lumiera.org/?p=LUMIERA;a=summary[source code] The GUI depends on the following: * https://gtkmm.gnome.org/en/[gtkmm] * https://cgit.freedesktop.org/xorg/lib/libXv[libXv] * https://wiki.gnome.org/Projects/LibRsvg[lib rSVG] * https://gitlab.gnome.org/Archive/gdl.git[lib GDL] ~([purple]#⚠ see below#)~ TIP: Generally speaking, when you want to build software, you'll need the _development_ version of the packages that contain the headers and pre-built libraries to link against. These packages are usually named `-devel` or `-dev`. For Debian based systems, e.g. Ubuntu, Mint... you can install these packages as follows: ------------------------------------------------------------------------------------- sudo apt-get install build-essential g++ git pkgconf scons intltool \ libboost-dev libboost-program-options-dev libasound2-dev libgavl-dev \ libgtkmm-3.0-dev librsvg2-dev libxv-dev ------------------------------------------------------------------------------------- Build Directory --------------- You'll need to check out the source code in some directory or other. You'll also have to use this directory to build Lumiera. This could be a temporary directory, or some "workspace" directory below your home directory. We'll refer to this directory as _workspace directory_ . Lumiera Specific Libraries -------------------------- Now that you have your basic build environment prepared, the next step is to care for some special libraries required by Lumiera that are not directly part of the Lumiera project itself, but aren't readily available through the usual package manager of the common distributions either.footnote:[ We maintain our own link:/debian/[Debian package depot at Lumiera.org] and provide binary Debian packages for a range of distributions; yet this tutorial strives at showing the basic and generic method for building. Thus we'll show you here how to build these libraries from source yourself -- however, in many cases it can be more convenient to use the DEB packages we provide, if applicable, for these extra library dependencies of Lumiera and just care for building the Lumiera main tree on your system. ] Thus, we'll have to get the source code for these support libraries, build and install them before we're able to compile Lumiera. WARNING: Note that the following procedures will try to install files into your base system below '/usr/local'. + To do so, you'll need [red]#administrative permission# for the machine you're working on. These additions might interfere with other libraries installed by your package manager (if you get into trouble updating your system later on, you might have to manually remove these libraries). NoBug: building and installing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ link:http://nobug.pipapo.org/[NoBug] is an instrumentation and diagnostics library. + Enter _workspace direcory_ as explained above. Get the NoBug source code: ------------------------------------------------------------ git clone git://git.lumiera.org/debian/nobug ------------------------------------------------------------ This will create a (sub)directory called nobug that contains source code. + Compile and install NoBug with the following commands: ------------------------------------------------------------ cd nobug autoreconf -i mkdir build cd build ../configure make sudo make install ------------------------------------------------------------ GDL-mm: building and installing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The *GNOME Docking library* was maintained, outside of the Gnome project, until 2021, mostly by the Anjuta people. It has dropped out of most distributions meanwhile, but is compatible with GTK-3 and can be built for the time being. We retain a copy of the repository and maintain a Debian package at Lumiera.org. Additionally we need the C++ bindings, which were created by _Fabien Parent_ and maintained 2009-2013; we likewise provide a repository and Debian package for these at Lumiera.org. These prerequisite libraries can be rebuilt with the steps described below. There is a dependency on `xmlto`, which is an xml converter. To install on Debian: ------------------------------------------------------------ apt-get install xmlto ------------------------------------------------------------ .building GDL ------------------------------------------------------------ git clone git://git.lumiera.org/debian/gdl cd gdl git checkout master ./autogen.sh make sudo make install ------------------------------------------------------------ .building GDL-mm ------------------------------------------------------------ git clone git://git.lumiera.org/debian/gdlmm cd gdlmm git checkout master ./autogen.sh make sudo make install ------------------------------------------------------------ verify library linkage ~~~~~~~~~~~~~~~~~~~~~~ The compile might warn you to add various directories to `/etc/ld.so.conf` and then to run `ldconfig`. This will allow your dynamic linker to pick up the newly built libraries later when you try to start Lumiera. If you don't want to reconfigure your system and add `/usr/local/lib` to the linker configuration, you may alternatively just add the directories to your `LD_LIBRARY_PATH` environment variable. Either way, check that all libraries are accessible and OK: ------------------------------------------------------------ sudo ldconfig -v | grep 'nobug' ------------------------------------------------------------ and you should get a list of the libraries, part of which should look like this: ------------------------------------------------------------ libnobug.so.0 -> /usr/local/lib/libnobug.so.0.0.0 libnobugmt.so.0 -> /usr/local/lib/libnobugmt.so.0.0.0 libgdl-lum.so.0 -> /usr/local/lib/libgdl-lum.so.0.0.0 ------------------------------------------------------------ or similar. The same applies to other custom libraries you needed to build explicitly for your system. If any of these libraries are not listed, you'll have to see why before you can continue. Building Lumiera ---------------- Next, after having built and installed the external libraries, go into the _workspace directory_ and retrieve the Lumiera source code. Thereafter, build Lumiera by invoking the *scons* build footnote:[more options for building with scons can be found via: `scons -h` ] ----------------- git clone git://git.lumiera.org/LUMIERA cd LUMIERA scons -j# ----------------- The build process will take some time, so sit back and relax. You can use for `#` (at least) the number of cores available on your system to speed up the build -- but it will take several minutes even for a debug build and significantly more for an optimised release build + (-> see `scons -h` for build options you can change) And if you feel like waiting even more, you might build and run the test suite by issuing `scons -j# check`... NOTE: you do not need to _install_ Lumiera. It will find all files it requires relative to the directory structure it generates, which is freely relocatable as a whole. Just invoke the 'target/lumiera' executable. The current working directory is not particularly relevant. After the build has finished successfully, you should be able to start Lumiera. Currently, this will bring up the GUI, _without much further functionality_ (!) You should see something like this: image:{imgg}/lumiera20250823.png["Current Lumiera GUI Screenshot",width=650] -> 💡 see link:{ldoc}/user/manual.html#_ui_experiments[here] for some demo features available... What's next? ------------ If you're a coder, maybe you have found something to improve...? + Contributing to Lumiera is easy, thanks to *Git* -> Tutorial link:contributing.html[Contributing to Lumiera coding]