Merge documentation / RfC regarding application installation
This commit is contained in:
commit
802831a8b8
16 changed files with 575 additions and 31 deletions
|
|
@ -316,7 +316,7 @@ function change_state()
|
|||
local state="$2"
|
||||
|
||||
local nl=$'\n'
|
||||
local comment="$state$nl//add reason$nl $(date +%c) $(git config --get user.name) <$(git config --get user.email)>$nl"
|
||||
local comment=".State -> $state$nl//add reason$nl $(date +%c) $(git config --get user.name) <$(git config --get user.email)>$nl"
|
||||
edit_state "$name" "$state" "$comment"
|
||||
edit "$name" -4 "endof_comments"
|
||||
process "$name"
|
||||
|
|
|
|||
|
|
@ -1,2 +1,2 @@
|
|||
documentation
|
||||
source for documentation and on some cases generated documentation in its own subdirs
|
||||
source for documentation and in some cases generated documentation in its own subdirs
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ GUI Brainstorming Reviewed
|
|||
|
||||
State of the GUI
|
||||
----------------
|
||||
image::images/screenshot090124-resources.jpg
|
||||
image:{l}/media/img/design.gui/screenshot090124-resources.jpg[Screenshot 090124]
|
||||
|
||||
Updated 18/01/09
|
||||
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ GUI concepts and -features and proposals.
|
|||
* link:Proposal.RichardSpindler.html[Richard Spindler]
|
||||
* link:Workspaces.html[about Workspace organsiation]
|
||||
* link:scrolling.html[about scrolling..]
|
||||
* link:MenuAndShortcuts.html[Ideas for menues and shortcuts]
|
||||
* link:MenuAndShortcuts.html[Ideas for menus and shortcuts]
|
||||
- link:TimelineDiscussion.html[Conclusions by Joel Holdsworth]
|
||||
|
||||
[icon="warning.png"]
|
||||
|
|
|
|||
|
|
@ -3,7 +3,9 @@ Design Documents: GUI
|
|||
|
||||
In the early stages of the project, there was a lot of debate regarding
|
||||
GUI concepts and -features and proposals.
|
||||
link:GuiDiscussion/index.html[here] is a collection of documents from these discussions.
|
||||
|
||||
link:GuiDiscussion/index.html[Here] is a collection of documents from these early
|
||||
discussions.
|
||||
|
||||
In our discussions, *Workflow* denotes all considerations how certain tasks
|
||||
can be achieved within the application in the most suitable and stringent fashion.
|
||||
|
|
|
|||
|
|
@ -32,11 +32,11 @@ The Processing layer (or proc) is where the elements from the Session are assemb
|
|||
==== link:backend/index.html[The Backend]
|
||||
|
||||
The backend uses the Low-level model. It allows the rendering and makes a heavy use of the Input/Output System to the screen or to external monitors.
|
||||
//link:workflow/index.html[The Workflow]
|
||||
|
||||
Extra components
|
||||
----------------
|
||||
|
||||
|
||||
link:application/index.html[The Application]
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,22 @@
|
|||
Design Process
|
||||
==============
|
||||
|
||||
*TODO* describe how the design process works and what we denote by *RfC*
|
||||
How it Works
|
||||
------------
|
||||
|
||||
* Every proposal starts out as _*Idea*_, allowing other people to review and comment on it, while still working out details.
|
||||
* When the _Idea_ is in a proper shape and worked out in most details it becomes a _*Draft*_. This _Draft_ need to be carefully reviewed, commented, perhaps corrected and rated by the other Developers.
|
||||
* We decide on some proposals to talk about that another time, these get a _*Parked*_ state.
|
||||
* At some point we may decide that a _Draft_ becomes a _*Final*_. Usually, this happens in our link:MonthlyMeetings[]. _Final_ Documents will be imported into the git repository (currently to the tiddlywiki).
|
||||
* Sometimes proposals will become dropped for some reason, this is indicated by changing their state to _*Dropped*_, they still stay in the system for further reference.
|
||||
|
||||
Generally you should refrain from editing someone others proposals (except for typo and gramatic fixes) when this is not acknowleded with the original author. Rather only add comments to the pages and end them with `@SIG@` to make it easier to find out who is the contact person for some note.
|
||||
|
||||
.Add a new Proposal:
|
||||
. Check if there is no similar proprosal below! If yes, contact it's author and contribute to that one.
|
||||
. Think of a good/descriptive *WikiName* for the Proposal. It will be used to create a RfC subpage.
|
||||
. Read the instructions and add your proposed text.
|
||||
|
||||
|
||||
* link:rfc[RfC accepted]
|
||||
* link:rfc_pending[RfC pending]
|
||||
|
|
|
|||
225
doc/devel/rfc_pending/ApplicationInstall.txt
Normal file
225
doc/devel/rfc_pending/ApplicationInstall.txt
Normal file
|
|
@ -0,0 +1,225 @@
|
|||
ApplicationInstall
|
||||
==================
|
||||
|
||||
// please don't remove the //word: comments
|
||||
|
||||
[grid="all"]
|
||||
`------------`-----------------------
|
||||
*State* _Draft_
|
||||
*Date* _Di 11 Jan 2011 17:00:55 CET_
|
||||
*Proposed by* Ichthyostega <prg@ichthyostega.de>
|
||||
-------------------------------------
|
||||
|
||||
[abstract]
|
||||
*********************************************************************************
|
||||
Lumiera should be a _freely relocatable_ application bundle.
|
||||
Relying only on the relative folder structure within this bundle, the application
|
||||
will be fully functional at any location, provided that the external library
|
||||
dependencies are resolvable using the standard mechanisms of the platform.
|
||||
The setup mechanism must be obvious, self-explanatory and must not rely
|
||||
on compiled in magic or buildsystem trickery. Yet packaging into a FSH conforming
|
||||
installation location should be supported by the same mechanisms.
|
||||
*********************************************************************************
|
||||
|
||||
Description
|
||||
-----------
|
||||
//description: add a detailed description:
|
||||
Lumiera is planned to become a large professional application bundle, relying
|
||||
on several external resources for proper operation. An installed Lumiera
|
||||
application will be more like Gimp, Blender, OpenOffice or Eclipse,
|
||||
not like bash, autotools or emcas.
|
||||
|
||||
Besides that, it can be expected that Lumiera frequently will be used in a
|
||||
project or studio like setup, where the application isn't installed, but just
|
||||
unZIPped / unTARed and used as-is. Thus, it should be sufficient to unpack
|
||||
the application bundle and point it to the session file and maybe the
|
||||
media storage.
|
||||
|
||||
The Eclipse platform can serve as a model for the setup of an modern
|
||||
application of that style: It can be just unpacked, and when looking
|
||||
into the folder structure, the meaning of the parts is obvious, and the
|
||||
basic bootstrap is controlled by two short text based INI files.
|
||||
While Lumiera presumably won't get _that_ heavyweight and is clearly
|
||||
not intended to become a general business application platform like OSGi --
|
||||
the underlying principles can serve as a point of reference for modern
|
||||
development standards.
|
||||
|
||||
This leads to the following conclusions:
|
||||
|
||||
- we need to define a standard folder layout for the bundle
|
||||
- the application must not rely on any compiled-in absolute paths
|
||||
- the executable should fetch the directly accompanying shared modules
|
||||
- all other lib dependencies should be handled by the system mechanisms
|
||||
- the bootstrap configuration likewise must not be compiled-in
|
||||
- this configuration must be human readable and clearly exhibit its purpose
|
||||
- the same system must be able to adapt to a FSH conforming installation layout
|
||||
|
||||
Judging from our current planning and the existing codebase, Lumiera
|
||||
is on a good way in that direction, yet some cleanup needs to be done,
|
||||
especially removing convenience shortcuts from the early days of development
|
||||
and catching up with the repair of some traits of sloppyness here and there.
|
||||
|
||||
Library resolution
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
In former days, it was common habit to compile-in a hard wired absolute
|
||||
+RPATH+. This can be considered obsolete practice; for example, the Debian
|
||||
policy forbids doing so. This is the result from numerous maintainability
|
||||
problems in the past. On the other hand, the GNU linker and other modern
|
||||
linkers support a relative resolution of shared modules directly accompanying
|
||||
an specific executable. The Debian policy allows this, if and only if these
|
||||
shared modules are installed with the same binary package and only used by
|
||||
this specific executable(s). Together, this is exactly what we need to
|
||||
solve our requirement.
|
||||
|
||||
Thus, the build process enables the new-style DT-tags in the Elf binary
|
||||
and sets the +DT_RUNPATH+ with an value relative to +$ORIGIN+, which resolves
|
||||
to the path of the currently executing binary. Moreover, it is _sufficient_
|
||||
to set this on the initial executable _only,_ because this creates a common
|
||||
searchpath for all lib resolution events in the scope of that loaded executable.
|
||||
Besides that, we need to care that our private libraries have a unique +SONAME+,
|
||||
in this case all starting with the prefix +liblumiera*+. Note moreover that this
|
||||
new-style +DT_RUNPATH+ indeed _can_ be overridden by an +LD_LIBRARY_PATH+ in the
|
||||
environment, should there be the need for very special experiments.
|
||||
|
||||
Bootstrap location
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
Thus, a single relative library folder becomes the only hard wired start
|
||||
configuration. In our case, the folder +$ORIGIN/modules+ was chosen. The
|
||||
root of the package then holds all the binaries depending on these common
|
||||
internal libraries, that is the +lumiera+ executable and any accompanying
|
||||
special tools. As usual with such large application bundles, these get
|
||||
only _symlinked_ into the +/usr/bin+ folder on installation.
|
||||
|
||||
For sake of clarity, after starting the executable, the _same location_
|
||||
is used to load the bootstrap configuration. This configuration in turn
|
||||
defines all further locations like the extended configuration, project
|
||||
templates, plugin search path, the GUI module to load, the search path
|
||||
for icons and GUI resources, project templates and similar basics.
|
||||
|
||||
Relative paths and the location of the executable
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
According to the general requirements outlined above, most paths should
|
||||
be given in a relative fashion. Unfortunately there is no portable solution
|
||||
for self-discovering the currently running executable. But at least there
|
||||
is a solution for all current major platforms. Under Linux, this information
|
||||
can be retrieved from the kernel through the +/proc+ filesystem.
|
||||
|
||||
Again for sake of clarity, the same token +$ORIGIN+ was chosen to denote
|
||||
this executable location (note: this is _not_ the current working directory).
|
||||
Moreover, due to the folder layout detailed above, this coincides with the
|
||||
root of the application bundle, thus making for a self-explanatory convention.
|
||||
Besides +$ORIGIN+, these search paths later on likely will contain locations
|
||||
below the user's home directory, e.g. +~/.lumiera/themes+
|
||||
|
||||
|
||||
Tasks
|
||||
~~~~~
|
||||
// List what needs to be done to implement this Proposal:
|
||||
* identify what impedes such a modern setup procedure ([green]#✔ done#)
|
||||
* rectify the folder structure created in the build target
|
||||
directory ([green]#✔ done#)
|
||||
* build the executables in a way to allow relative resolution of the
|
||||
internal shared modules ([green]#✔ done#)
|
||||
* replace the compiled-in path definitions for plugin loading by a
|
||||
configurable bootstrap ([green]#✔#)
|
||||
* add an working library implementation for a config loader ([green]#✔ done#)
|
||||
* add a mechanism for establishing the path of the current execubable. +
|
||||
This is _non-portable_ ([green]#✔ done#)
|
||||
* wire the prepared API in the GUI to use this working config loader
|
||||
for resolving GUI resources ([green]#✔ done#)
|
||||
* try to extract the path search code from the existing config loader,
|
||||
or build a new solution based on standard libraries ([green]#✔ done#)
|
||||
* introduce an output root directory into the buildsystem, allowing
|
||||
for package builds ([green]#✔#)
|
||||
* define a _Debian packaging_ as proof-of-concept ([green]#✔ done#)
|
||||
|
||||
|
||||
Discussion
|
||||
~~~~~~~~~~
|
||||
|
||||
Pros
|
||||
^^^^
|
||||
* self-contained
|
||||
* self-explanatory
|
||||
* based on _best practices_
|
||||
* conforming with FSH and Debian policy
|
||||
|
||||
|
||||
Cons
|
||||
^^^^
|
||||
* requires work
|
||||
* raises the bar at the implementation side
|
||||
* requires an bootstrap sequence to be explicitly performed
|
||||
on application startup
|
||||
* breaks with some beloved habits of the Unix community
|
||||
|
||||
|
||||
Alternatives
|
||||
^^^^^^^^^^^^
|
||||
//alternatives: explain alternatives and tell why they are not viable:
|
||||
I can think of two alternatives
|
||||
|
||||
. dealing with all those problems _later_
|
||||
. not making an concept, rather sticking to UNIX habits
|
||||
|
||||
The first alternative is indeed worth considering, because we're settling
|
||||
some things to be really implemented way later, which bears some dangers.
|
||||
But, on the other hand, it is a common practice known from extreme programming
|
||||
to deliver early and regularly, which effectively means to set up the deploy
|
||||
path of an application really early in the development cycle. The rationale
|
||||
is that -- according to general experience -- the deployment always turns
|
||||
up some very specific problems and constraints, which can be a serious
|
||||
threat when discovered late in the development process.
|
||||
|
||||
The second alternative isn't really applicable IMHO. The original UNIX philosophy
|
||||
breeds on an academic setup and really excels with small nifty commandline utils
|
||||
combined by pipes, each specialised to do a single thing very well. These utils
|
||||
are more like the objects within our implementation. The concept of large
|
||||
application software bundles and desktop software was always a bit alien
|
||||
within the classic UNIX environment.
|
||||
|
||||
|
||||
|
||||
Rationale
|
||||
---------
|
||||
//rationale: Give a concise summary why it should be done *this* way:
|
||||
|
||||
This RfC can be seen as an commitment to an professional approach and as
|
||||
clarification: Traditionally, the Unix community hailed a lot of _black magic_
|
||||
practices like compiled-in installation paths, macro magic, +sed+ and +awk+
|
||||
trickery, inline code compiled on-the-fly, relying on very specific and
|
||||
un-obvious behaviour of some build script, configuration via environment
|
||||
variables and a lot of similar idioms. These practices might be adequate
|
||||
in a quickly moving Research & Development setup, but turned out to be
|
||||
not so helpful when it comes to industrial strength development,
|
||||
as they are known to lead to maintenance problems.
|
||||
|
||||
|
||||
|
||||
|
||||
//Conclusion
|
||||
//----------
|
||||
//conclusion: When approbate (this proposal becomes a Final)
|
||||
// write some conclusions about its process:
|
||||
|
||||
|
||||
|
||||
|
||||
Comments
|
||||
--------
|
||||
//comments: append below
|
||||
|
||||
.State -> Draft
|
||||
There is now a complete implementation of this concept on my ``proc'' branch. +
|
||||
Moreover, I was able to define an initial Debian packaging for Lumiera on top
|
||||
of that implementation.
|
||||
|
||||
During that work, I had opportunity to visit various areas of the existing codebase,
|
||||
which reminded me of several small issues, which seem to become unhealthy when lying
|
||||
around unfixed for such a long time. Probably I'll start a clean-up initiative and
|
||||
try to bring these points to discussion separately.
|
||||
|
||||
So 13 Feb 2011 20:04:00 CET Ichthyostega <prg@ichthyostega.de>
|
||||
|
||||
|
||||
//endof_comments:
|
||||
|
|
@ -9,7 +9,7 @@ This documentation section contains documentation for both users and developers.
|
|||
|
||||
The user manual containing the full reference for using Lumiera :
|
||||
|
||||
* link:manual.html[User Manual] _(planned)_
|
||||
* link:user/manual.html[User Manual] _(planned)_
|
||||
|
||||
=== Developer
|
||||
Informations about the structure of Lumiera, they give an overview on the main components of the application :
|
||||
|
|
@ -23,6 +23,4 @@ Programming-oriented details about the functional layers of Lumiera as well as a
|
|||
=== Presentation documents
|
||||
Documents that you can use as you wish to present or promote Lumiera :
|
||||
|
||||
* link:white-papers-presentations.html[Whitepapers and Presentations]
|
||||
|
||||
|
||||
* link:/media/index.html[Whitepapers and Presentations]
|
||||
|
|
|
|||
64
doc/technical/howto/DebugGdbPretty.txt
Normal file
64
doc/technical/howto/DebugGdbPretty.txt
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
GDB Python pretty printers
|
||||
==========================
|
||||
|
||||
Since some time, GDB supports Python written extension modules, especially
|
||||
for pretty printing of data structures. A selection of pre-defined pretty printers
|
||||
for STL containers is part of the standard distribution. The graphical debugger frontend
|
||||
provided by the Eclipse CDT automatically uses this debugger provided presentation
|
||||
to show the value of variables in the detail pane of the variables view, while the
|
||||
individual variable entries always show the expandable structure view.
|
||||
|
||||
Installation notes
|
||||
------------------
|
||||
|
||||
This feature requires an python enabled GDB (>6.8.50). Debian/Lenny isn't enough,
|
||||
but compiling the GDB package from Debian/Squeeze (GDB-7.1) is straightforward.
|
||||
Moreover, you need to check out and install the python pretty-printers and
|
||||
you need to activate them through your +~/.gdbinit+
|
||||
|
||||
[source,python]
|
||||
----
|
||||
#
|
||||
# .gdbinit : GDB Config file
|
||||
#
|
||||
# 3/2010 - Ichthyo: add python pretty printers for STL
|
||||
|
||||
python
|
||||
import sys
|
||||
sys.path.insert(0, '/opt/gdb/stlPrettyPrinter')
|
||||
from libstdcxx.v6.printers import register_libstdcxx_printers
|
||||
register_libstdcxx_printers (None)
|
||||
end
|
||||
----
|
||||
For more informations link:http://sourceware.org/gdb/wiki/STLSupport[see here..]
|
||||
|
||||
.Hello World
|
||||
[source,C]
|
||||
----
|
||||
#include <iostream>
|
||||
#include <string>
|
||||
#include <vector>
|
||||
|
||||
using std::string;
|
||||
using std::cout;
|
||||
using std::endl;
|
||||
|
||||
|
||||
int
|
||||
main (int, char**)
|
||||
{
|
||||
std::string str = "hullo wöld";
|
||||
std::vector<int> vec (1000);
|
||||
|
||||
for (uint i = 0; i < vec.size(); ++i)
|
||||
vec[i] = i;
|
||||
|
||||
cout << str << "\n.gulp.\n";
|
||||
return 0;
|
||||
}
|
||||
----
|
||||
When selecting the string or the vector in the Eclipse variables view
|
||||
(or when issuing "print str" at the GDB prompt), the GDB python pretty-printer
|
||||
should be activated.
|
||||
|
||||
|
||||
18
doc/technical/howto/index.txt
Normal file
18
doc/technical/howto/index.txt
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
Developer HOWTOs
|
||||
================
|
||||
|
||||
|
||||
This section contains a loose collection of instructions, recipes, tutorials and
|
||||
similar usefull pieces of information targeted at Lumiera developers. See also
|
||||
|
||||
- the general link:{l}/project/faq.html[Lumiera FAQ]
|
||||
- the link:{ldoc}/user/index.html[User documentation]
|
||||
|
||||
== Notepad
|
||||
- link:DebugGdbPretty.html[Python pretty printers for GDB]
|
||||
|
||||
|
||||
[icon="warning.png"]
|
||||
WARNING: Website under construction
|
||||
|
||||
|
||||
|
|
@ -1,40 +1,34 @@
|
|||
////
|
||||
Technote Documentation
|
||||
======================
|
||||
Technical Documentation
|
||||
=======================
|
||||
|
||||
* link:http://www.lumiera.org/doxy/[Doxygen generated documentation]
|
||||
* link:gui/index.html[GUI-Layer]
|
||||
* link:proc/index.html[Proc-Layer]
|
||||
* link:backend/index.html[Backend]
|
||||
* link:build/index.html[Buildsystem]
|
||||
|
||||
|
||||
[icon="warning.png"]
|
||||
WARNING: Website under construction
|
||||
////
|
||||
== Technical Documentation
|
||||
|
||||
This documentation section contains technical documentation about Lumiera.
|
||||
To get an overview of all the internals and components, you might want to read
|
||||
link:innerCore/the_inner_core.html[Lumiera the Inner Core]
|
||||
|
||||
=== Three Layers
|
||||
== Three Layers
|
||||
The technical documentation is split in three parts, one for each of the three main layers of Lumiera.
|
||||
You may want to read the link:../design/index.html[Design Documents] first to get an overview of all the components.
|
||||
|
||||
* link:gui/index.html[*Graphical User Interface*] : Documents about the default GTK GUI that comes with Lumiera.
|
||||
* link:gui/index.html[*Graphical User Interface*] : Documents related to the GTK based Lumiera GUI
|
||||
|
||||
* link:proc/index.html[*Processing layer*]
|
||||
* link:proc/index.html[*Processing layer*] : Documents regarding Session, models and the engine structure
|
||||
|
||||
* link:backend/index.html[*Backend system*]
|
||||
* link:backend/index.html[*Backend system*] : Documents about the data and processing backend
|
||||
|
||||
|
||||
== Tools
|
||||
|
||||
=== Tools
|
||||
.Development
|
||||
* link:http://www.lumiera.org/doxy/[*Doxygen generated documentation*] : Complete reference for the code of Lumiera.
|
||||
|
||||
.Building
|
||||
* link:build/index.html[*Buildsystem*] : Installation & compilation tools, dependencies and packaging.
|
||||
|
||||
.HOWTO
|
||||
* link:howto/index.html[*Developer HOWTOs*] : Collection of instructions, recipes, hints and similar
|
||||
materials intended for developers
|
||||
|
||||
|
||||
[icon="warning.png"]
|
||||
WARNING: Website under construction
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ User Documentation
|
|||
|
||||
* link:manual.html[We need to write a user manual....]
|
||||
* The following document might become an introductory overview: +
|
||||
link:outerSpace/lumiera_from_outer_space.html[Lumiera from Outer Space]
|
||||
link:outerSpace/lumiera_from_outer_space.html[Lumiera (as seen) from Outer Space]
|
||||
* link:outerSpace/Glossary.html[Glossary of common terms]
|
||||
|
||||
[icon="warning.png"]
|
||||
|
|
|
|||
195
doc/user/tutorials/building.txt
Normal file
195
doc/user/tutorials/building.txt
Normal file
|
|
@ -0,0 +1,195 @@
|
|||
Building Lumiera from source
|
||||
============================
|
||||
|
||||
Currently, after building the application, you can try out the Lumiera GUI
|
||||
and you can run the test suite.
|
||||
|
||||
For building Lumiera, besides the GNU C/C++ compiler (Version 4.X), you will
|
||||
need:
|
||||
|
||||
* http://git-scm.com/[git]
|
||||
* http://www.gnu.org/software/libtool/[libtool]
|
||||
* http://www.boost.org/[Boost libraries]
|
||||
* http://gmerlin.sourceforge.net/[GAVL library]
|
||||
* *NoBug* (see below)
|
||||
|
||||
TIP: Generally speaking, when you want to build software, you need the
|
||||
_development_ version of the packages, containing the headers and pre-built
|
||||
libraries to link against. Usually, these packages are named `-devel` or `-dev`
|
||||
|
||||
.Notes for Ubuntu:
|
||||
|
||||
On Hardy you need also:
|
||||
|
||||
* libglade2-dev
|
||||
* libgtkmm-2.4-dev
|
||||
* libxv-dev
|
||||
|
||||
For most Debian based systems, e.g. Ubuntu, you can install these dependencies
|
||||
with:
|
||||
|
||||
------------------------------------------------------------
|
||||
sudo apt-get install build-essential autoconf git-core libboost-dev \
|
||||
libboost-program-options-dev libboost-regex-dev libgavl-dev libgdl-1-dev \
|
||||
libglade2-dev libgtkmm-2.4-dev librsvg2-dev libtool libxv-dev scons valgrind
|
||||
------------------------------------------------------------
|
||||
|
||||
Build directory
|
||||
---------------
|
||||
|
||||
You need a directory for checking out the sources and running the build. This
|
||||
could be a temp directory, or some "workspace" directory below your home
|
||||
directory. We'll call it _workspace directory_ from now on.
|
||||
|
||||
Lumiera specific libraries
|
||||
--------------------------
|
||||
|
||||
Now that you have your basic build system setup, Lumiera needs a few more
|
||||
special support libraries. Currently you need to build those from source and
|
||||
install them, so the Lumiera build process can pick them up.
|
||||
|
||||
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 permissions 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,
|
||||
sometimes you need to remove these manually built libraries).
|
||||
|
||||
Installing NoBug
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
*NoBug* is an instrumentation and diagnostics library. +
|
||||
Go into the mentioned _workspace direcory_ (maybe create a new
|
||||
directory). First, let's get the NoBug source code:
|
||||
|
||||
------------------------------------------------------------
|
||||
git clone git://git.pipapo.org/nobug
|
||||
------------------------------------------------------------
|
||||
|
||||
This will create a (sub)directory called nobug with source code in your current
|
||||
directory. +
|
||||
Compile NoBug with the following commands
|
||||
|
||||
------------------------------------------------------------
|
||||
cd nobug
|
||||
autoreconf -i
|
||||
mkdir build
|
||||
cd build
|
||||
../configure
|
||||
make
|
||||
make install
|
||||
------------------------------------------------------------
|
||||
|
||||
Installing GDL
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
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. Thus, for now we 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).
|
||||
|
||||
------------------------------------------------------------
|
||||
git clone git://git.lumiera.org/gdl-package
|
||||
cd gdl-package
|
||||
./configure
|
||||
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
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
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
|
||||
libraries later when you try to start Lumiera. If you don't want to reconfigure
|
||||
your system and add `/usr/local/lib` to the mentioned 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 'gdl-lum\|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. If any if this libs are not listed, investigate why before continuing.
|
||||
|
||||
|
||||
Building Lumiera
|
||||
----------------
|
||||
|
||||
Lumiera has two maintained (and equivalent) build systems: *scons* and
|
||||
*autotools*. You can pick the one you feel more comfortable with.
|
||||
|
||||
When trying to build a development version of Lumiera, it might well be that at
|
||||
times one of the builds doesn't work temporarily. It is always a good idea to
|
||||
check the current build stats from our *builddrone*, which automatically builds
|
||||
the latest version from 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 prerequisite libraries, go into the
|
||||
_workspace directory_ to retrieve the Lumiera source code and build it.
|
||||
|
||||
|
||||
* to retrieve the source code with git and then build with *scons*:
|
||||
+
|
||||
(see available build options by issuing `scons -h` )
|
||||
+
|
||||
-----------------
|
||||
git clone git://git.lumiera.org/LUMIERA
|
||||
cd LUMIERA
|
||||
scons
|
||||
-----------------
|
||||
+
|
||||
|
||||
* alternatively, if you prefer building with *autotools*:
|
||||
+
|
||||
-----------------
|
||||
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`
|
||||
|
||||
This will take some time.
|
||||
|
||||
NOTE: you can not _install_ Lumiera currently. Do not try it, it will not work.
|
||||
Just run it from the build directory.
|
||||
|
||||
After the build has finished successfully, you should be able to start Lumiera.
|
||||
Currently, this will bring up the GUI, without any further functionality
|
||||
|
||||
* for autotools build: issue `./lumiera` (from within the `build` subdirectory)
|
||||
* for scons build:
|
||||
+
|
||||
-------------------
|
||||
cd bin
|
||||
./lumiera
|
||||
-------------------
|
||||
|
||||
You should see something like (screenshot from 1/2009):
|
||||
|
||||
image:/media/img/design.gui/screenshot090124-resources.jpg[]
|
||||
26
doc/user/tutorials/contributing.txt
Normal file
26
doc/user/tutorials/contributing.txt
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
Contributing to Lumiera
|
||||
=======================
|
||||
|
||||
Nothing is easier, follow the
|
||||
http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html[the basic
|
||||
instructions], notably the following parts:
|
||||
|
||||
------------------------------------------------------------
|
||||
$ git config --global user.name "Your Name Comes Here"
|
||||
$ git config --global user.email you@yourdomain.example.com
|
||||
------------------------------------------------------------
|
||||
|
||||
Then you are ready to go, you can edit and commit the lumiera code locally in
|
||||
your cloned repository. Please do small commits which fix/improve only one
|
||||
single thing and use meaningful commit messages.
|
||||
|
||||
Check that you didn't break anything, by running the testsuite (see above)
|
||||
|
||||
Finally you can push your changes to the lumiera server to the 'mob' repository:
|
||||
|
||||
------------------------------------------------------------
|
||||
$ git push git://git.lumiera.org/lumiera/mob master:refs/heads/YOURNAME
|
||||
------------------------------------------------------------
|
||||
|
||||
This creates a new branch 'YOURNAME' on the mob repository. Then you notify the
|
||||
other devs on the mailinglist and they may merge your code into the mainline.
|
||||
7
doc/user/tutorials/index.txt
Normal file
7
doc/user/tutorials/index.txt
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
Tutorials
|
||||
=========
|
||||
|
||||
This page contains tutorials for beginners interested in Lumiera development.
|
||||
|
||||
* link:building.html[Building Lumiera from source]
|
||||
* link:contributing.html[Contributing to Lumiera]
|
||||
Loading…
Reference in a new issue