From b1b89c168ea6f88d18198978a9bcf41194292939 Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Mon, 2 Nov 2015 19:38:43 +0100 Subject: [PATCH] release prep: clean-up obsolete information --- .../{ExternalTreeDescription.txt => ETD.txt} | 2 +- doc/technical/build/Dependencies.txt | 10 ++-- doc/technical/build/LumieraDebianPackage.txt | 18 +++++-- doc/user/tutorials/DebianBuilding.txt | 33 ++++++++---- doc/user/tutorials/building.txt | 54 +++++++------------ doc/user/tutorials/contributing.txt | 25 ++++----- 6 files changed, 72 insertions(+), 70 deletions(-) rename doc/design/architecture/{ExternalTreeDescription.txt => ETD.txt} (99%) diff --git a/doc/design/architecture/ExternalTreeDescription.txt b/doc/design/architecture/ETD.txt similarity index 99% rename from doc/design/architecture/ExternalTreeDescription.txt rename to doc/design/architecture/ETD.txt index c71c85dc3..ecdaa23b3 100644 --- a/doc/design/architecture/ExternalTreeDescription.txt +++ b/doc/design/architecture/ETD.txt @@ -3,7 +3,7 @@ External Tree Description :Author: Ichthyostega :Date: Fall 2015 -//Menu: label ETD + **************** _to symbolically represent hierarchically structured elements, without actually implementing them._ diff --git a/doc/technical/build/Dependencies.txt b/doc/technical/build/Dependencies.txt index eade18bb7..f9d48494a 100644 --- a/doc/technical/build/Dependencies.txt +++ b/doc/technical/build/Dependencies.txt @@ -1,7 +1,7 @@ Dependencies ============ :Author: core-devs -:Date: 5/2015 +:Date: 11/2015 :toc: @@ -12,7 +12,7 @@ Lumiera shall scale with the provided Hardware, the more RAM and the more/faster CPU's you have the better. Nevertheless lower end 32bit machines are supported too. -Secondary targets will be other free operating systems which offer a decent Posix API. + +Secondary targets will be other free operating systems which offer a decent Posix API. Porting to other more or less similar platforms will be possible, if -- by coincidence -- Someone(TM) helps with porting. @@ -90,9 +90,11 @@ Libraries - libxv-dev footnote:[for the XV viewer widget `gui/output/xvdisplayer.cpp` -- currently obsolete as of [yellow-background]#5/2015#][yellow-background]#TODO 5/2015# and X-lib - librsvg-2.0 and librsvg2-dev for rendering Icons - - libgdl-3-0 or better through libgdlmm-3.0-2 -- the »Gnome Docking Library«footnote:[GDL isn't directly related to GNOME any more. + - libgdl-3 (3.12 or better) through libgdlmm-3 -- 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. These improvements went upstream with GDL-2.27. At times, we used to ship our own GDL package. Right now, a recent upstream version - together with the corresponding *mm-bindings will do] + together with the corresponding *mm-bindings will do. We provide a debian package for the latter, + until they will be available in the official Debian/Ubuntu/Mint repos. But we don't have any + special requirements on these `gdlmm` bindings.] diff --git a/doc/technical/build/LumieraDebianPackage.txt b/doc/technical/build/LumieraDebianPackage.txt index a5f19c1c4..db29923e3 100644 --- a/doc/technical/build/LumieraDebianPackage.txt +++ b/doc/technical/build/LumieraDebianPackage.txt @@ -12,8 +12,8 @@ packages through our own link:http://Lumiera.org/debian[Debian Apt-Repository] ( TIP: readers new to Debian packages may want to have a look into our link:{ldoc}/user/tutorials/DebianBuilding.html[Debian build tutorial], - describing the commands for building and the structure of a Debian - (source) package in general + where we describe the commands for building and explain the structure + of a Debian (source) package in general Package build process @@ -44,7 +44,7 @@ Actually, this lookup process at application startup is performed in two phases transitive library dependencies, and finally shared objects, which are loaded at runtime through the `dlopen()` call.] Especially those libraries belonging first class to the Lumiera application are built - with a relative search path ('rpath' with $ORIGIN token). These libraries are placed + with a relative search path ('rpath' with `$ORIGIN` token). These libraries are placed into the +modules/+ subfolder - after successfully launching the executable, the second phase performs a lookup programmatically, @@ -69,7 +69,15 @@ Releases, Branches and Conventions Official releases are marked by a tag on the master branch. At that point, master should be in good shape, release documentation is polished; experimental features are removed or disabled. Usually, we'll also fork a *release branch* at that point, featuring bugfixes only. -From here we'll merge to the *debian branch* +From here we'll merge to the **debian branch**footnote:[the 'release' branch will be merged back at +times, while the 'debian' branch won't. This 'debian' branch is published through a separate +link:git://git.lumiera.org/debian/lumiera[debian/lumiera git repository] and not merged back, +since all tweaks here are strictly for debian packaging. There might be other packaging related +repositories in the future. Yet still, the 'debian' branch is based on the same common tree +and can in therory kept in the same git repository. Contrast this to the branch 'depot', which +is also published through our 'debian/lumiera' git repository. This latter branch corresponds +to a completely separate tree and holds the administrative part of our +link:http://Lumiera.org/debian[Debian package depot] (Repository) on Lumiera.org.] Typically the release will lead to the discovery of more or less serious bugs, which are fixed on the release branch and backported to master. The result is a sequence of point @@ -88,7 +96,7 @@ To (re)build the debian package -- here _RELEASE-TAG_ denotes the point in the Git history, which should become the reference source and be packaged into the *.orig.tar.gz. Usually, it's just -sufficient to use 'master' for that purpose. +sufficient to use branch 'release' for that purpose. Debian-Depot for installation via Apt diff --git a/doc/user/tutorials/DebianBuilding.txt b/doc/user/tutorials/DebianBuilding.txt index be21a8841..62f816329 100644 --- a/doc/user/tutorials/DebianBuilding.txt +++ b/doc/user/tutorials/DebianBuilding.txt @@ -5,7 +5,7 @@ building from source -- the »Debian Way« :toc: 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 +is a simple alternative to the manual 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*. @@ -14,7 +14,7 @@ Why -- what are the benefits? * rely on the Debian/Ubuntu package manager for sorting out the library and build dependencies * install Lumiera as a first-class package, like all the other software - you're using regularily. This way, the package manager ``knows'' about + you're using regularly. This way, the package manager ``knows'' about the library dependencies and can't mix up things due to a system upgrade. Under some circumstances, these very benefits might be a drawback, though. @@ -43,7 +43,7 @@ deb-src http://lumiera.org/debian/ jessie experimental + ---- sudo apt-get build-dep nobug-dev -sudo apt-get build-dep libgdl-lum-dev +sudo apt-get build-dep gdlmm-3 sudo apt-get build-dep lumiera ---- . *build* using the source package. @@ -56,10 +56,10 @@ apt-get source --compile nobug-dev prompted for signing with your GPG key. But because you're not going to upload the created binary packages anywhere, this step can be considered optional. - * installing the created package. + * install the created package. + 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 +the build. You need to _install_ these packages then using the basic Debian package manager `dpkg` + ---- @@ -70,7 +70,7 @@ of course, the package names, versions and architecture will vary, depending on situation. * repeat those steps to work your way up to the +lumiera+ package; build and install - Nobug, maybe build and install libgdl-lum and finally build and install Lumiera + Nobug, maybe build and install the GDL mm-bindings and finally build and install Lumiera . clean up. + @@ -78,17 +78,17 @@ 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 stash those packages somewhere, as we're not keeping _every_ -package in the online Lumiera debian depot. While any 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. *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. + +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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 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 package more convenient or improve the usage in some way. In addition, it also stores @@ -110,11 +110,22 @@ APT::Install-Recommends "false"; ^_Disclaimer:_ please be sure you understand the consequences...^ +Building packages from git +~~~~~~~~~~~~~~~~~~~~~~~~~~ +This tutorial describes the classic way of building a Debian package, which also is the +foundation for any shortcuts and convenience scripts. In practice, people maintaining +Debian packages happen to use various shortcuts and helper scripts to automate repetitive +tasks. One such helper especially worth mentioning is **git-buildpackage**. With a little bit +of configuration, this nifty script is able to create a full Debian package just form a +git checkout in a single shot. At Lumiera.org, we maintain all our Debian packages this +way, so the necessary configuration +debian/gbp.conf* is already in place. + + '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' The rest of this tutorial contains some more in-depth explanations for the curious -anatomy of a debian source package +anatomy of a Debian source package ---------------------------------- Debian source packages provide a standardised way of compiling software. These @@ -171,7 +182,7 @@ It is recommended to build with normal user permissions (not as root). Note, if several packages depend on each other, you need to give them all as list in a single command invocation. -After having prepared the sources thusly, you need to step into the root of the +After having prepared the sources this way, you need to step into the root of the source tree, if you want to build the whole package, or even want to tweak and modify parts. diff --git a/doc/user/tutorials/building.txt b/doc/user/tutorials/building.txt index c7550270f..c6544b3de 100644 --- a/doc/user/tutorials/building.txt +++ b/doc/user/tutorials/building.txt @@ -25,7 +25,7 @@ There are two distinct methods to build: - 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...) +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 @@ -46,10 +46,10 @@ 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) +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://git-scm.com/[Git] (version management system) * link:http://www.scons.org/[SCons build system] * link:http://www.boost.org/[Boost libraries] * link:http://gmerlin.sourceforge.net/[GAVL library] @@ -60,7 +60,7 @@ 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://wiki.gnome.org/LibRsvg[lib rSVG] * link:https://git.gnome.org/browse/gdl[lib GDL] @@ -76,7 +76,9 @@ libboost-dev libboost-program-options-dev libboost-regex-dev libboost-filesystem libgavl-dev libgtkmm-3.0-dev libgdl-3-dev librsvg2-dev libxv-dev ------------------------------------------------------------------------------------- -Optionally, you may also want to install the `gtk2-engines` package. +Ubuntu note:: + some people reported you need to install the `intltool` package from the standard + Ubuntu repository (for this reason it is included in the above collection) Build Directory @@ -121,8 +123,6 @@ 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 @@ -133,35 +133,21 @@ make sudo make install ------------------------------------------------------------ -GDL: building and installing -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +GDL-mm: 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 +The *GNOME Docking library* is available through your your package manager, +but we additionally need the C++ bindings. Since these haven't made it into the +standard repositories yet, we provide a suitable custom package here; +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. + we rely on GTK-3 and thus need a compatible GDL-3. -Ubuntu note:: - you need to install the `intltool` package from the standard Ubuntu repository ------------------------------------------------------------ -git clone git://git.lumiera.org/debian/gdl -cd gdl +git clone git://git.lumiera.org/debian/gdlmm +cd gdlmm ./configure make sudo make install @@ -193,7 +179,7 @@ and you should get a list of the libraries, part of which should look like this: 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 +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. @@ -204,7 +190,7 @@ 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` ] +footnote:[more options for building with scons can be found via: `scons -h` ] ----------------- git clone git://git.lumiera.org/LUMIERA cd LUMIERA @@ -221,7 +207,7 @@ 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 +Currently, this will bring up the GUI, _without any further functionality_ (!) You should see something like this: @@ -230,7 +216,7 @@ 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...? + +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] diff --git a/doc/user/tutorials/contributing.txt b/doc/user/tutorials/contributing.txt index 549707586..8eafb1910 100644 --- a/doc/user/tutorials/contributing.txt +++ b/doc/user/tutorials/contributing.txt @@ -5,9 +5,7 @@ Contributing to Lumiera :toc: -This document is aimed at helping newcomers to contribute quickly to the -project. - +This document is aimed at helping newcomers to contribute. + There are two major obstacles faced by people new to Lumiera: - _how_ can I contribute to Lumiera @@ -90,11 +88,11 @@ Packages normally available with your distribution:: for a Debian based system (including Mint, Ubuntu and similar flavours), you should be able to install the necessary dependencies with the command + ------------------------------------------------------------- +------------------------------------------------------------------------------------- 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-2.4-dev librsvg2-dev libxv-dev ------------------------------------------------------------- +libgavl-dev libgtkmm-3.0-dev libgdl-3-dev librsvg2-dev libxv-dev +------------------------------------------------------------------------------------- Packages not normally part of your distribution:: there are two packages most likely not available with your operating system distribution, so you'll need to obtain the source code for these packages @@ -111,14 +109,13 @@ mkdir build && cd build make sudo make install ------------------------------------------------------------ - - *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] + - **mm**-bindings for *GDL* -- a window docking library footnote:[GDL itself _is_ + available through the standard package manager, in a version compatible to GTK-3. + What is not yet available are the corresponding C++ bindings `gdlmm-3`] + ------------------------------------------------------------ -git clone git://git.lumiera.org/debian/gdl -cd gdl +git clone git://git.lumiera.org/debian/gdlmm +cd gdlmm ./configure make sudo make install @@ -239,11 +236,9 @@ fact, many user interfaces should be possible. - The initial GUI on which considerable work has already been done has been implemented using the GTK toolkit. However, considerable more work needs to be done on this present GUI. -- One immediate task that needs attention is to port the current GUI from - GTK2 to GTK 3. Especially, our custom style sheet needs to be ported - we urgently need conceptual (non-coding) contributions - * work out a coherent handling concept, in accordance with model and core + * work out a coherent UI handling concept, in accordance with model and core * we need a concept for key bindings and focus * we need a concept for integration with control surfaces * we need a concept for pen based handling