DOC: update and polish the building tutorial

doc/technical/build/Dependencies.txt

@@ -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,
+   We contributed to the improvement of this library in the past. These improvements went upstream
-   for now we're forced to use a _really ancient version_, which isn't available from the official
+   with GDL-2.27. Since we're still using GTK-2, for now we're forced to use a _really ancient version_,
-   repositories -- you can find the original tarball and several Debian/Ubuntu packages in our
+   which isn't available from the official repositories -- you can find the original tarball and several
-   link:http://lumiera.org/debian/pool/experimental/g/gdl/[Lumiera package repository] though.]
+   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]
 
 

doc/user/tutorials/DebianBuilding.txt

@@ -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
+In case you're using a Debian-based system (e.g. Mint, Ubuntu...), there
-Lumiera from source in the classical (hard) way, you might prefer building
+is a simple alternative to the manaual compiling and installing of library
-from the Debian source package.
+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._
+No problem -- basically it is always possible to run Lumiera _without installation._
-It is deliberately made such as to find its components actively, within the standard
+We deliberately constructed the application such as to find its components actively,
-directory structure created by the buildsystem. While, thus, Lumiera can be just
+within the standard directory structure created by the buildsystem. However, while,
-run directly from such a folder tree, the software still relies on some other
+Lumiera itself can be just run directly from such a folder tree, the software still
-libraries, which somehow need to be installed on your system.
+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_
+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 every package could be reproduced
+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.
+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'
+  debian build system'' link:http://build-common.alioth.debian.org/cdbs-doc.html[CDBS] --
-  in a very short and concise fashion
+  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'
 

doc/user/tutorials/building.txt

@@ -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
+with _commandline survival skills_ on your system. To help you getting started,
-you do not use the Debian package, we'll explicitly provide all giot commands.
+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 the Debian source code package of Lumiera (the »Debian way«)
-- use Git to retrieve all source code
+- use Git to retrieve all source code and build the »classical way«
 
 
-NOTE: just compiling Lumieara on a _Debian-based_ system (e.g. Ubuntu)
+NOTE: just compiling Lumieara on a _Debian-based_ system (e.g. Mint, Ubuntu...)
-      is much simpler using the Debian source package. See the separate
+      is much simpler when using the Debian source package. See the separate
-      link:DebianBuilding.html[tutorial page] for this (or the general
+      link:DebianBuilding.html[tutorial page] for this footnote:[besides, there
-      link:/debian/[instructions for installing on Debian/Ubuntu]).
+      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
+To build Lumiera, you'll need a _build environment_ together with the
-the following:
+_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]
+ * link:http://www.gtkmm.org/en/[gtkmm]
- * http://cgit.freedesktop.org/xorg/lib/libXv[libXv]
+ * 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 environment prepared, the next step is to care
-Now that you have your basic build system setup, you'll next have obtain support
+for some special libraries required by Lumiera that are not directly part of the
-libraries required by Lumiera that are not directly part of the Lumiera project
+Lumiera project itself, but aren't readily available through the usual package
-itself. At the moment, you'll have to get the source code for the support
+manager of the common distributions either. footnote:[we maintain our own Debian
-libraries at build them from source. We do not have them pre-packaged at the
+package depot at Lumiera.org and provide binary Debian packages for a range of
-moment, but this will hopefully change over time. However, it is not too
+distributions; yet this tutorial strives at showing the basic and generic method
-difficult to build the support libraries and the instructions following here
+for building. Thus we'll show you here how to build these libraries from source
-should not be too difficult.
+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
+Compile and install NoBug with the following commands:
-the NoBug library in /usr/lib, so you will require root privilages to do so!)
+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,
+The *GNOME Docking library* is sometimes available through your package manager,
-but we contributed some improvements, which are only available in the very
+but we provide a suitable custom package as well; the following shows how to
-recent development versions of GDL. If your distribution provides a GDL >= 2.27,
+build the latter
-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::
+Version limitation::
-  intltool-update is not patched, you must add +/usr/share/intltool-debian/+
+  we contributed some improvements to GDL, which are only available in upstream
-  to get the gdl-package to configure correctly (JSC).
+  versions since 2.27. Moreover, the GDL development switched meanwhile to GNOME-3
-Ubuntu 10.10 note::
+  and GTK-3. Since we haven't upgraded GTK yet, we need to stick to a version prior
-  you need to install the +intltool+ package from the standard ubuntu repository
+  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
@@ -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
+The compile might 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
+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. 
+Lumiera by invoking the *scons* build
-
+footnote:[more options for building with scons can be found via:`scons -h` ]
-
- * 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` )
-+
 -----------------
 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.
 

doc/user/tutorials/contributing.txt

@@ -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