DOC: update and polish the building tutorial
This commit is contained in:
parent
9652c7ec5e
commit
2c4ed4ca91
4 changed files with 118 additions and 112 deletions
|
|
@ -93,9 +93,11 @@ Libraries
|
|||
- libxv-dev
|
||||
- librsvg-2.0 and librsvg2-dev for rendering Icons
|
||||
- libgdl-1-dev -- old version of the Gnome Docking Library footnote:[GDL isn't directly related to GNOME any more.
|
||||
We contributed to the improvement of this library in the past. Since we're still using GTK-2,
|
||||
for now we're forced to use a _really ancient version_, which isn't available from the official
|
||||
repositories -- you can find the original tarball and several Debian/Ubuntu packages in our
|
||||
link:http://lumiera.org/debian/pool/experimental/g/gdl/[Lumiera package repository] though.]
|
||||
We contributed to the improvement of this library in the past. These improvements went upstream
|
||||
with GDL-2.27. Since we're still using GTK-2, for now we're forced to use a _really ancient version_,
|
||||
which isn't available from the official repositories -- you can find the original tarball and several
|
||||
Debian/Ubuntu packages in our
|
||||
link:http://lumiera.org/debian/pool/experimental/g/gdl/[Lumiera package repository] though.
|
||||
Basically we need 2.27 =< GDL =< 2.30]
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,11 +1,13 @@
|
|||
building from source -- the Debian Way
|
||||
======================================
|
||||
building from source -- the »Debian Way«
|
||||
========================================
|
||||
:Author: Ichthyostega
|
||||
:Date: 3/2011
|
||||
:toc:
|
||||
|
||||
When you're using a Debian-based system (e.g. Ubuntu), instead of compiling
|
||||
Lumiera from source in the classical (hard) way, you might prefer building
|
||||
from the Debian source package.
|
||||
In case you're using a Debian-based system (e.g. Mint, Ubuntu...), there
|
||||
is a simple alternative to the manaual compiling and installing of library
|
||||
dependencies. Instead of building Lumiera from source in the classical (hard)
|
||||
way, you might prefer *building from the Debian source packages*.
|
||||
|
||||
Why -- what are the benefits?
|
||||
|
||||
|
|
@ -19,23 +21,23 @@ Under some circumstances, these very benefits might be a drawback, though.
|
|||
Sometimes you don't want to install; or you might have a version of Lumiera
|
||||
installed, but want to try out a (maybe newer / development) version...
|
||||
|
||||
No problem -- basically it's always possible to run Lumiera _without installation._
|
||||
It is deliberately made such as to find its components actively, within the standard
|
||||
directory structure created by the buildsystem. While, thus, Lumiera can be just
|
||||
run directly from such a folder tree, the software still relies on some other
|
||||
libraries, which somehow need to be installed on your system.
|
||||
No problem -- basically it is always possible to run Lumiera _without installation._
|
||||
We deliberately constructed the application such as to find its components actively,
|
||||
within the standard directory structure created by the buildsystem. However, while,
|
||||
Lumiera itself can be just run directly from such a folder tree, the software still
|
||||
relies on some other libraries, which somehow need to be installed on your system.
|
||||
|
||||
|
||||
building from source package
|
||||
----------------------------
|
||||
Generally speaking, operations which _modify_ the installation/configuration of your
|
||||
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.
|
||||
|
||||
. add a suitable source line to your *Apt configuration* ('/etc/apt/sources.lst')
|
||||
+
|
||||
----
|
||||
deb-src http://lumiera.org/debian/ squeeze experimental
|
||||
deb-src http://lumiera.org/debian/ wheezy experimental
|
||||
----
|
||||
. get all the *build dependencies*
|
||||
+
|
||||
|
|
@ -58,7 +60,7 @@ apt-get source --compile nobug-dev
|
|||
+
|
||||
Finally, you'll find several new +*.deb+ packages in the directory where you started
|
||||
the build. You need to _install_ these packages then using the basic debian package
|
||||
manager 'dpkg'
|
||||
manager `dpkg`
|
||||
+
|
||||
----
|
||||
sudo dpkg -i libnobug2_201008.1-1_i386.deb nobug-dev_201008.1-1_i386.deb
|
||||
|
|
@ -75,15 +77,17 @@ situation.
|
|||
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 file those packages somewhere, as we're not keeping _every_
|
||||
package in the online Lumiera debian depot. While every package could be reproduced
|
||||
exactly with a bit of Git knowledge, just keeping the +*.deb+ might be more convenient.
|
||||
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.
|
||||
|
||||
*That's it* -- you're done! Debian building is convenient, isn't it?
|
||||
|
||||
NOTE: What follows is a background information and configuration for advanced users. +
|
||||
You can safely skip and ignore the remainder of this page if in doubt.
|
||||
|
||||
Required and recommended Debian packages
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
What follows is a note about configuration for advanced users. You can safely skip and
|
||||
ignore this section if in doubt.
|
||||
|
||||
The Debian package manager stores for each package not only the required prerequisites,
|
||||
but also some additional _recommended_ packages: Software likely to make using the given
|
||||
|
|
@ -106,8 +110,8 @@ APT::Install-Recommends "false";
|
|||
^_Disclaimer:_ please be sure you understand the consequences...^
|
||||
|
||||
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
What follows are some more in-depth explanations and background informations
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
The rest of this tutorial contains some more in-depth explanations for the curious
|
||||
|
||||
|
||||
anatomy of a debian source package
|
||||
|
|
@ -144,8 +148,8 @@ the package. With the exception of the following:
|
|||
- 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*. But modern debian packages often make use of the ``common
|
||||
debian build system'' -- basically a set of macros allowing to write these 'rules'
|
||||
in a very short and concise fashion
|
||||
debian build system'' link:http://build-common.alioth.debian.org/cdbs-doc.html[CDBS] --
|
||||
basically a set of macros allowing to write these _rules_ in a very short and concise fashion
|
||||
|
||||
|
||||
commands for handling source packages
|
||||
|
|
@ -174,7 +178,7 @@ modify parts.
|
|||
- 'dpkg-checkbuilddeps' checks that all the requirements of the package are satisfied.
|
||||
It just prints out what is missing; this is especially useful if the fully automated
|
||||
install did not work entirely, so you have to fix / reinstall parts manually
|
||||
- 'dpkg-buildpackage -rfakeroot' starts the full build. This includes re-generating
|
||||
- 'dpkg-buildpackage' starts the full build. This includes re-generating
|
||||
the source package (and especially the diff). If you only want to build the binary
|
||||
package, you can skip the diff- / source-package generation with '-b'
|
||||
|
||||
|
|
|
|||
|
|
@ -1,24 +1,35 @@
|
|||
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.
|
||||
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. Although Git is required if
|
||||
you do not use the Debian package, we'll explicitly provide all giot commands.
|
||||
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
|
||||
- use Git to retrieve all source code
|
||||
- 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. Ubuntu)
|
||||
is much simpler using the Debian source package. See the separate
|
||||
link:DebianBuilding.html[tutorial page] for this (or the general
|
||||
link:/debian/[instructions for installing on Debian/Ubuntu]).
|
||||
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.
|
||||
|
||||
|
|
@ -26,26 +37,38 @@ NOTE: just compiling Lumieara on a _Debian-based_ system (e.g. Ubuntu)
|
|||
Requirements
|
||||
------------
|
||||
|
||||
To build Lumiera, you'll require GNU C/C++ compiler (Version 4.X) in addition to
|
||||
the following:
|
||||
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 (Version 4.X)
|
||||
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]
|
||||
* *NoBug* (see below)
|
||||
* link:http://nobug.pipapo.org/[NoBug] (see below)
|
||||
* Lumiera source code
|
||||
|
||||
The GUI depends on the following:
|
||||
|
||||
* http://www.gtkmm.org/en/[gtkmm]
|
||||
* http://cgit.freedesktop.org/xorg/lib/libXv[libXv]
|
||||
* 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 ususally named `-devel` or `-dev`.
|
||||
libraries to link against. These packages are usually named `-devel` or `-dev`.
|
||||
|
||||
For Debian based systems, e.g. Ubuntu, you can install these packages as follows:
|
||||
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 \
|
||||
|
|
@ -53,7 +76,7 @@ libboost-dev libboost-program-options-dev libboost-regex-dev libboost-filesystem
|
|||
libgavl-dev libgtkmm-2.4-dev librsvg2-dev libxv-dev
|
||||
-------------------------------------------------------------------------------------
|
||||
|
||||
Optionally, you may also want to install the *gtk2-engines* package.
|
||||
Optionally, you may also want to install the `gtk2-engines` package.
|
||||
|
||||
|
||||
Build Directory
|
||||
|
|
@ -64,29 +87,31 @@ 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 system setup, you'll next have obtain support
|
||||
libraries required by Lumiera that are not directly part of the Lumiera project
|
||||
itself. At the moment, you'll have to get the source code for the support
|
||||
libraries at build them from source. We do not have them pre-packaged at the
|
||||
moment, but this will hopefully change over time. However, it is not too
|
||||
difficult to build the support libraries and the instructions following here
|
||||
should not be too difficult.
|
||||
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`.
|
||||
|
||||
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: obtaining, building and installing
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
*NoBug* is an instrumentation and diagnostics library. +
|
||||
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:
|
||||
|
||||
|
|
@ -95,9 +120,9 @@ 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: (this will try to install
|
||||
the NoBug library in /usr/lib, so you will require root privilages to do so!)
|
||||
|
||||
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
|
||||
|
|
@ -108,20 +133,23 @@ make
|
|||
sudo make install
|
||||
------------------------------------------------------------
|
||||
|
||||
GDL: obtaining, building and installing
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
GDL: building and installing
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The *GNOME Docking library* is generally available through your package manager,
|
||||
but we contributed some improvements, which are only available in the very
|
||||
recent development versions of GDL. If your distribution provides a GDL >= 2.27,
|
||||
you're fine. Otherwise we've created a special package, which doesn't interfere
|
||||
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 9.04 note::
|
||||
intltool-update is not patched, you must add +/usr/share/intltool-debian/+
|
||||
to get the gdl-package to configure correctly (JSC).
|
||||
Ubuntu 10.10 note::
|
||||
you need to install the +intltool+ package from the standard ubuntu repository
|
||||
Ubuntu note::
|
||||
you need to install the `intltool` package from the standard Ubuntu repository
|
||||
|
||||
------------------------------------------------------------
|
||||
git clone git://git.lumiera.org/debian/gdl
|
||||
|
|
@ -131,20 +159,16 @@ make
|
|||
sudo make install
|
||||
------------------------------------------------------------
|
||||
|
||||
For more detailed instructions on how to build GDL (also how to build it into a
|
||||
Debian package) see
|
||||
http://lists.lumiera.org/pipermail/lumiera/2009-April/000891.html[this message +
|
||||
on the Lumiera mailing list].
|
||||
|
||||
|
||||
check library linkage
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
verify library linkage
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The compile will warn you to add various directories to /etc/ld.so.conf and then
|
||||
run ldconfig. This will allow your dynamic liker to pick up the newly built
|
||||
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
|
||||
alternatively just add the directories to your `LD_LIBRARY_PATH` environment
|
||||
variable.
|
||||
|
||||
Either way, check that all libraries are accessible and OK:
|
||||
|
|
@ -169,44 +193,17 @@ have to see why before you can continue.
|
|||
Building Lumiera
|
||||
----------------
|
||||
|
||||
Up to now, Lumiera has had (and equivalent) build systems: *scons* and
|
||||
*autotools*. (Note 3/2011: At the moment, the autotools build system is
|
||||
broken; only the scons build mechanism is working. It is always a good idea to
|
||||
check the current build stats from our *builddrone*, which automatically builds
|
||||
the latest version from the master repository. Please have a look at this
|
||||
http://lumiera.org/builddrone/table.html[current build stats]-page.)
|
||||
|
||||
Next, after having built and installed the external libraries, go into the
|
||||
_workspace directory_ and retrieve the Lumiera source code. Thereafter, build
|
||||
Lumiera.
|
||||
|
||||
|
||||
* Issue the following command to retireve the Lumiera source code and,
|
||||
thereafter, build Lumiera using *scons*:
|
||||
+
|
||||
(more options for building with scons can be found via:`scons -h` )
|
||||
+
|
||||
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
|
||||
-----------------
|
||||
+
|
||||
|
||||
* Alternatively, if you'd prefer to build using *autotools* _(not working
|
||||
currently 3/11)_, issue the following commands:
|
||||
+
|
||||
-----------------
|
||||
git clone git://git.lumiera.org/LUMIERA
|
||||
cd LUMIERA
|
||||
autoreconf -fi
|
||||
mkdir build
|
||||
cd build
|
||||
../configure
|
||||
make
|
||||
-----------------
|
||||
|
||||
maybe build and run the test suite by issuing `scons check` or `make check`
|
||||
maybe build and run the test suite by issuing `scons check`
|
||||
|
||||
The build process will take some time, so sit back and relax.
|
||||
|
||||
|
|
|
|||
|
|
@ -111,7 +111,10 @@ mkdir build && cd build
|
|||
make
|
||||
sudo make install
|
||||
------------------------------------------------------------
|
||||
- *GDL* -- a window docking library
|
||||
- *GDL* -- a window docking library footnote:[GDL _is_ usually available
|
||||
through the standard package manager, albeit in a GTK-3 based version;
|
||||
since we haven't managed to port our GUI to GTK-3, we're sticking to a
|
||||
rather ancient version of the Gnome Docking Library for now]
|
||||
+
|
||||
------------------------------------------------------------
|
||||
git clone git://git.lumiera.org/debian/gdl
|
||||
|
|
|
|||
Loading…
Reference in a new issue