Ichthyostega
651cf144a5
- comb through the Website, starting at the frontpage - add a **news** entry to confirm this major upgrade step (C++23) - improve the wording in various overview pages - adapt the ''release checklist'' to align it with **git-flow** - reorganise the image folder(s) on the website - the animated beating heart is back ;-)
251 lines
10 KiB
Text
251 lines
10 KiB
Text
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]
|
|
|