LUMIERA.clone/doc/technical/howto/backporting.txt

Backporting to older platforms
==============================
:Date: 11/2015
:toc:

GCC-4.9
-------
Currently (as of 8/2015), we require a quite recent compiler and likewise a suitable
C++ standard library for the build. The reason is that we set the language compatibility
level to `-std=gnu++14`. If you're on a platform with an older compiler and standard library,
you need a way to install a recent toolchain in a way, that the standard library includes
like e.g. `#include <functional>` will indeed pick up a suitably modern standard library,
in addition to being compiled with a recent compiler (GCC-4.9 or CLang 3.5). The way to
achieve this is different for every distribution; we'll show the solution for
»Ubuntu Trusty 14.04 LTS« here as an example

GCC and Libstdc++ 4.9 on Ubuntu Trusty
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
While the standard compiler for Unbutu in 2014 was GCC-4.8, the _Ubuntu Toolchain Project_
provides builds and packages for more recent toolchains through an _PPA_. So we'll add that
PPA as an additional package source, install a GCC-4.9 with the accompanying standard
library, and finally switch the system standard for C/C++ compiler to this new version.
All these steps are reversible and can be deactivated when causing problems elsewhere...

* add the https://launchpad.net/~ubuntu-toolchain-r/+archive/ubuntu/test[Ubuntu Toolchain PPA]:
+
----
sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt-get update
----

 * get the compiler and standard library
+
----
sudo apt-get install gcc-4.9 g++-4.9
----

* switch the system standard for ``C compilation'' -- make sure to tie the switch for
  C and C++ compiler, to avoid mixing generated code for incompatible library versions.
+
----
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.9 60 \
                         --slave /usr/bin/g++ g++ /usr/bin/g++-4.9
----

Assuming you've also installed the standard gcc`(4.8)` package, you can arrange matters
such as to be able to switch back and forth between both compilers. For this to work,
we need also to make the (default) gcc-4.8 an option in the choice

----
sudo apt-get install gcc-4.8 g++-4.8
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.8 60 \
                         --slave /usr/bin/g++ g++ /usr/bin/g++-4.8
----

From this point on, we can switch configuration by

----
sudo update-alternatives --config gcc
---- 


Building on Mint 17.2 (Rafaela) -- gcc and Libstdc++ 4.9
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Since Mint is based on Ubuntu LTS, we're facing pretty much the same situation here.
But what makes matters yet more confusing is the fact, that Mint offers even a Clang-3.6
package, which is _unfortunately_ built to rely on the gcc-4.8 libraries; there is a known
header inclusion bug in these libraries, which kicks in as soon as we switch to C++14.

Thus it is _mandatory_ to install the gcc-4.9 from above mentioned Ubuntu-Toolchain PPA,
which is indeed linked against the 4.9 libraries. Stay away from Clang on Mint for now!

Transcript from a build session on a ``pristine'' Mint 17.2 installation:

 * add the following to your `/etc/apt/sources.list`
+   
----
deb https://lumiera.org/debian/ rafaela experimental
deb-src https://lumiera.org/debian/ rafaela experimental
----

 * install _Ichthyo's_ DEB signing key
+
----
gpg --keyserver keyserver.ubuntu.com --recv A1DE94B2
gpg --export -a A1DE94B2 | sudo apt-key add -
----

 * prepare build environment
+
----
sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt-get update
sudo apt-get install build-essential gcc-4.9 g++-4.9 git-core
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.9 60 \
                         --slave /usr/bin/g++ g++ /usr/bin/g++-4.9

sudo apt-get build-dep lumiera
----
+
after that, your system is prepared for building Lumiera

 * now build

   * either by (re)compiling the debian package
+
----
apt-get source lumiera
cd lumiera
dpkg-buildpackage
----

   * or check out the source and hack away...
+
----
git clone git://git.lumiera.org/LUMIERA
cd LUMIERA

scons CC=gcc-4.9 CXX=g++-4.9
----
+
...as usual, from this point on, the compiler setting will be remembered in the file
`optcache`, so no need to repeat it for subsequent `scons` invocations.

TIP: Just run `scons` for standard build or run the testsuite with `scons check`.
     Use the switch `-j#` with # corresponding to the number of your cores.
     Probably you'll need at least 2GB of memory on AMD64, to build with `-j6`