lumiera_/doc/user/tutorials/building.txt

Building Lumiera from source
============================
:Date: 2013
: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 any 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 Lumieara 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/Dependencies.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++14 support (Version >= 4.9)
in addition to the following tools and libraries:

 * link:http://git-scm.com/[Git VCS]
 * link:http://www.scons.org/[SCons build system]
 * link:http://www.boost.org/[Boost libraries]
 * link:http://gmerlin.sourceforge.net/[GAVL library]
 * link:http://nobug.pipapo.org/[NoBug] (see below)
 * Lumiera source code 

The GUI depends on the following:

 * link:http://www.gtkmm.org/en/[gtkmm]
 * link:http://cgit.freedesktop.org/xorg/lib/libXv[libXv]
 * link:https://wiki.gnome.org/LibRsvg[lib R SVG]
 * link:https://git.gnome.org/browse/gdl[lib GDL]
 

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. Mint, Ubuntu..., you can install these packages as follows:

-------------------------------------------------------------------------------------
sudo apt-get install build-essential scons git-core valgrind intltool \
libboost-dev libboost-program-options-dev libboost-regex-dev libboost-filesystem-dev \
libgavl-dev libgtkmm-3.0-dev libgdl-3-dev librsvg2-dev libxv-dev
-------------------------------------------------------------------------------------

Optionally, you may also want to install the `gtk2-engines` package.


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 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] 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 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:
footnote:[this will try to install the NoBug library in `/usr/lib`,
so you will require root privileges to do so!]
------------------------------------------------------------
cd nobug
autoreconf -i
mkdir build
cd build
../configure
make
sudo make install
------------------------------------------------------------

GDL: building and installing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

NOTE: 8/2015 the information in this paragraph is outdated!
      We have switched to GTK-3 recently. Now we're able just to use the
      official GDL from upstream (or your distribution). But we have also
      switched to C++ bindings, and thus need a gdlmm installation, which
      is not yet provided through the offial repositories on most distributions.
      Thus, instead of shipping our own libGDL, now we're providing a DEB package
      of gdlmm through our repository...

The *GNOME Docking library* is sometimes available through your package manager,
but we provide a suitable custom package as well; the following shows how to
build the latter

Version limitation::
  we contributed some improvements to GDL, which are only available in upstream
  versions since 2.27. Moreover, the GDL development switched meanwhile to GNOME-3
  and GTK-3. Since we haven't upgraded GTK yet, we need to stick to a version prior
  to this switch. If your distribution provides a 2.27 =< GDL =< 2.30, you're fine.
  Otherwise we've created a special package, which doesn't interfere
  with an existing (older) installation of GDL.

Ubuntu note::
  you need to install the `intltool` package from the standard Ubuntu repository

------------------------------------------------------------
git clone git://git.lumiera.org/debian/gdl
cd gdl
./configure
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 'libgdl-lum.so.0' if you needed to build it
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
-----------------

maybe build and run the test suite by issuing `scons check`

The build process will take some time, so sit back and relax.

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 any further functionality

You should see something like this:

image:{l}/images/lumiera_gui_small.png[Current Lumiera GUI Screenshot]


What's next?
------------
If you're a coder, maybe you've found something to improve...? +
Contributing to Lumiera is easy, thanks to *Git*

-> Tutorial link:contributing.html[Contributing to Lumiera coding]