diff --git a/admin/rfc.sh b/admin/rfc.sh index 06f050613..0c2c37338 100755 --- a/admin/rfc.sh +++ b/admin/rfc.sh @@ -4,64 +4,79 @@ shopt -s extglob function usage() { - less <<"EOF" -Script to maintain Lumiera RFC's + less -F <<"EOF" +Lumiera RFC maintenance script +============================== + +// Note: the source of this documentation is maintained +// directly admin/rfc.sh in its usage() function +// edit it only there and then regenerate +// doc/devel/technical/infra/ with: +// ./admin/rfc.sh help >doc/technical/infra/rfcsh.txt + +Usage +----- -usage: ./admin/rfc.sh [options] -options: - title - Quoted string used as RFC title - rfc - Name of the RFC, smart matched, unique - rfcs - Name of the RFC, smart matched, multiple - regex - Regex matched against the content of a RFC - chapter - Heading of a section +Commands (with and [optional] parameters) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -commands (with and [optional] parameters): - find [regex] - List all matching RFC's (matching 'regex') - show [regex] - Read RFC's (matching 'regex') - create - Create a new RFC - edit <rfc> [chapter] - Edit RFC at chapter - asciidoc <rfc> - pass the rfc.txt to 'asciidoc' command - comment <rfc> - Add a new comment to a RFC - draft <rfc> - Change RFC to Draft state - final <rfc> - Change RFC to Final state - park <rfc> - Change RFC to Parked state - drop <rfc> - Change RFC to Dropped state - supersede <rfc> <new> - Supersede RFC with a new RFC - discard <rfc> - Delete an RFC - help - Show this help - process - Do automatic maintenance work - wrap <rfcs> - canonical reformatting + find <rfcs> [regex]:: List all matching RFC's (matching `regex`) + show <rfcs> [regex]:: Read RFC's (matching `regex`) + create <title>:: Create a new RFC + edit <rfc> [chapter]:: Edit RFC at chapter + asciidoc <rfc>:: pass the rfc.txt to `asciidoc` command + comment <rfc>:: Add a new comment to a RFC + draft <rfc>:: Change RFC to Draft state + final <rfc>:: Change RFC to Final state + park <rfc>:: Change RFC to Parked state + drop <rfc>:: Change RFC to Dropped state + supersede <rfc> <new>:: Supersede RFC with a new RFC + discard <rfc>:: Delete an RFC + help:: Show this help + process:: Do automatic maintenance work + wrap <rfcs>:: canonical reformatting -Smart matching: - RFC names don't need to be given exactly, they use a globbing pattern. - This is: - - case insensitive - - whitespaces are ignored - - '*' stands for any number of parameters - - '?' is any single character - - when starting with '/' they are matched against the begin of the name - - some regex operators work too - 'find' and 'show' can operate on many matches so the given rfc name doesn't - need to be unique. The other commands will complain when the RFC name given - doesn't resolve to one unique RFC. +Option types +~~~~~~~~~~~~ -Notes: - When less presents multiple files one can go forth and back with the ':n' - and ':p' commands. + title:: Quoted string used as RFC title + rfc:: Name of the RFC, smart matched, unique + rfcs:: Name of the RFC, smart matched, multiple + regex:: Regex matched against the content of a RFC + chapter:: Heading of a section - The tile for 'create' should be a normal document title. Possibly quoted - since it may contain spaces and not too long. The filename is this title - in CamelCase with all spaces and special characters removed. - Chapter machching single lines containing this word, special asciidoc - comments in the form '//word:.*' and asciidoc block attributes '[word.*]' - on a single line. When a chapter pattern is not unique, the last one is - picked. +Smart matching +-------------- - rfc.sh executes git add/rm/mv commands, but never commits. One should do a - commit as soon he finished editing. +RFC names don't need to be given exactly, they use a globbing pattern. +This is: + - case insensitive + - whitespaces are ignored + - `*` stands for any number of parameters + - `?` is any single character + - when starting with `/` they are matched against the begin of the name + - some regex operators work too +`find` and `show` can operate on many matches so the given rfc name doesn't +need to be unique. The other commands will complain when the RFC name given +doesn't resolve to one unique RFC. + +When `less` presents multiple files one can go forth and back with the `:n` +and `:p` commands. + +The tile for `create` should be a normal document title. Possibly quoted +since it may contain spaces and not too long. The filename is this title +in CamelCase with all spaces and special characters removed. + +Chapter machching single lines containing this word, special asciidoc +comments in the form `//word:.*` and asciidoc block attributes `[word.*]` +on a single line. When a chapter pattern is not unique, the last one is +picked. + +rfc.sh executes git add/rm/mv commands, but never commits. One should do a +commit as soon he finished editing. EOF } diff --git a/doc/design/architecture/ArchitectureSummary.txt b/doc/design/architecture/ArchitectureSummary.txt new file mode 100644 index 000000000..4ddd3b4ba --- /dev/null +++ b/doc/design/architecture/ArchitectureSummary.txt @@ -0,0 +1,36 @@ +Lumiera Architecture: Executive Summary +======================================= +:Author: Hermann Voßeler +:Email: <Ichthyostega@web.de> +:Date: Sept 2010 + +//Menu: label Summary + +.Three Layers +Besides the (obvious) separation in GUI frontend and render engine, editing core and application logic +are treated separately. Besides enforcing clearly defined interfaces, the ability for script driven +``headless'' operation and extensibility by plug-ins are deeply rooted in the overall design. + +.Strong Separation +High-level and low-level realm remain cleanly separated, relying on a compiler-like translation mechanism. +This way, each part can be optimised for its purpose. The GUI exposes a feature-rich session model close +to the problem domain, while the engine operates on a performance optimised render nodes graph. + +.Scheduling Micro Operations +High performance calculations in the engine are organised as micro tasks to be scheduled, +allowing for adaptation to current and future hardware, expected to operate increasingly parallelised. + +.Intelligent IO +The engine is backed by an sophisticated frame cache and self adjusting I/O manager for maximising throughput +and bandwidth use. + +.Stream Type System +Instead of relying on a single media framework, data streams are abstracted and classified, allowing to +handle most wiring, detection of possible connections and conversion automatically. + +.Rules Based Configuration +Rather than driven by hard wired default behaviour or tedious manual operation, control flow is guided by +a set of rules shaped configuration, which scales better to large and complicated projects. Queries are +issued at decision points, allowing to build up a work environment customised and tailored for the needs +of specific projects. + diff --git a/doc/design/architecture/index.txt b/doc/design/architecture/index.txt new file mode 100644 index 000000000..0d6996b8e --- /dev/null +++ b/doc/design/architecture/index.txt @@ -0,0 +1,13 @@ +Design Documents: Lumiera Architecture +====================================== + +This section will feature some rather high-level considerations regarding +the architecture of the application. + +.Executive Summary +See link:ArchitectureSummary.html[here] for a short summary of the core architecture +ideas of the envisioned Lumiera Application. + + + + diff --git a/doc/design/index.txt b/doc/design/index.txt index 8ff8a6a22..1b8114d54 100644 --- a/doc/design/index.txt +++ b/doc/design/index.txt @@ -1,6 +1,15 @@ Lumiera Design Documents ======================== +// Menu : prepend child design/backend +// Menu : prepend child engine +// Menu : prepend child model +// Menu : prepend child design/gui +// Menu : prepend child architecture + +// Menu : append child plugins +// Menu : append child workflow + The goal of Lumiera is to provide a professional tool for video editing on GNU/Linux systems. The vision of the development team defines a modern design for the core of a Non-Linear Editing software. One of the key aspect of Lumiera diff --git a/doc/devel/images/lumiera_big_graph.png b/doc/devel/images/lumiera_big_graph.png new file mode 100644 index 000000000..ec08d77fd Binary files /dev/null and b/doc/devel/images/lumiera_big_graph.png differ diff --git a/doc/technical/infra/MenuGen.txt b/doc/technical/infra/MenuGen.txt index 7691f8528..060f178e4 100644 --- a/doc/technical/infra/MenuGen.txt +++ b/doc/technical/infra/MenuGen.txt @@ -204,6 +204,7 @@ supported placement directives commandline options ^^^^^^^^^^^^^^^^^^^ The behaviour of the +menugen+ script can be influenced by some options: + predefined:: using the built-in predefined nodes scan:: discover nodes debug:: dump data structure after discovery diff --git a/doc/technical/infra/debianDepot.txt b/doc/technical/infra/debianDepot.txt new file mode 100644 index 000000000..f599950b2 --- /dev/null +++ b/doc/technical/infra/debianDepot.txt @@ -0,0 +1,128 @@ +Lumiera Debian Package and Depot maintainance +============================================= +:Author: Hermann Voßeler deb@ichthyostega.de +:Date: 3/2011 + +//Menu: label Debian Depot + +This Debian-Depot is part of the Lumiera build infrastructure. +It is managed automatically, based on the link:http://mirrorer.alioth.debian.org/[reprepro] tool by Bernhard Link + + +The Lumiera debian package +-------------------------- +As our whole infrastructure relies heavily on the Git version management tool, it's only natural +also to organise the (debian) packaging with the help of Git. Fortunatlely, there is a nifty tool +called link:https://honk.sigxcpu.org/piki/projects/git-buildpackage/[git-buildpackage], written +by Guido Günther exactly for this purpuse: It treats the _debianisation_ as a branch in the +Git repository, forking off the mainline at the release point. + +For Lumiera, this _debianisation branch_ is called 'deb' and can be found in the +link:http://git.lumiera.org/gitweb?p=lumiera/debian;a=summary[git:/git.lumiera.org/lumiera/debian] repository. + +To (re)build the debian package + +. +git clone git:/git.lumiera.org/lumiera/debian+ +. +mkdir pack.deb+ +. +cd debian+ +. +git-buildpackage --git-upstream-branch=+_RELEASE-TAG_ + +-- 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. + + +Debian-Depot for installation via Apt +------------------------------------- +While it is easy just to build a debian package and then install it locally through ++dpkg -i+, if we want to support automated installation and upgrades using the Apt +package manager, we need to build up more infrastructure. The primary reason is that +for any source package, a multitude of binary packages might be built for different +architectures; moreover, we want to support several different distributions. +For this purpose,the Apt package manager requires a precisely defined folder structure, +accessible online via 'http:' or 'ftp:'. For maintaining this folder structure, there +are three concievable levels of complexy: + +minimal layout, manual maintainance:: + place everything in a single directory accessible online. Use only one pseudo-distribution + and call the (single) component \'.\' -- just dump packages into the directory and update + the packages list + +multiple distributions and components, pool directory:: + this setup is already a full-blown debian depot, just there are some limitations + on the flexibility: there might be only _one_ version of each package per distribution, + and all different distributions use a shared pool (and thus require different packages + to be labeled stringently) + +major distribution or mirror site:: + similar to the above, this is a complete debian depot, but it is backed by a database + and allows for much more flexible configuration and is highly automated. + + +For Lumiera, it seems the middle option is the right choice: while it still keeps the +infrastructure simple, it allows for multiple _distributions_ (Debian/stable, Ubuntu....) +and multiple _components_ (experimental, development, release). The mentioned 'reprepro' +tool provides this degree of functionality: Basically, this is a fixed directory structure +with some control files; the frontent is a commandline tool with a plethora of options +and quite some automation- and extension hooks. Internally, it uses an embedded BerkelyDB. + +Using 'reprepro', existing source, binary or comined packages can be _added_ (imported) +into the structure with a single command; the files comprising the package are then +added automatically to the pool directory and all the indices, directories and GPG +signatures are created and updated automatically. Previous versions of the same +package are purged, when not needed by any existing package anymore + +everyday usage +~~~~~~~~~~~~~~ + +import a package:: + +reprepro -V -C experimental include lenny lumiera_0.pre.01-1+maverick_i386.changes+ ++ +this adds the given binary lumiera package, together with all sources and the original +tarball to the 'lenny' repository, into the 'experimental' section + +dump out an entire repository:: + +reprepro -V export lenny+ ++ +this will __re__generate all of the indices, signatures and metadata of the 'lenny' repository + + +Configuration +~~~~~~~~~~~~~ +The current configuration and the state of the Debian Depot index files is tracked +is a separate branch in the +link:http://git.lumiera.org/gitweb?p=lumiera/debian;a=shortlog;h=refs/heads/depot[lumiera/debian] +repository. (Note: this is a somewhat unconventional setup, insofar the 'depot' branch tracks +a directory tree completely separete from the main lumiera source tree tracked by the deb branch; +I choose this layout because of the marginal relevance of this depot management; I just didn't +want to create _yet another not so useful Git repository..._) + + * primary link:http://git.lumiera.org/gitweb?p=lumiera/debian;a=blob;f=conf/distributions;hb=refs/heads/depot[configuration] + * Logfile of imports: link:http://git.lumiera.org/gitweb?p=lumiera/debian;a=blob;f=log/lenny.log;hb=refs/heads/depot[for Lenny] + +[NOTE] +.some special details to note in our setup +======================================================================================================================= +- each block in the 'distributions' file defines a repository for a ``distribution'' (e.g. Lenny, Lucid, Maverick). + Within such a repo, there are sections named 'Components'. +- The _override_ files mentioned in the configuration allow to overwrite / replace arbitrary fields in the metadata of + all packages added to that distribution. +- In this setup, we enabled the 'tracking' function: thereby reprepro will keep track of the dependencies between + binary packages, signatures, debianisation patches and original upstream tarballs. Never packages overwirte older + ones -- _at any time there is at most one version of a package in the repository._ Parts not referred to anymore + are automatically discareded. In our configuration, they are moved into the 'morguedir' +- Please make sure the *gpg signing key* is in proper order, because it protects against evil spirited manipulations. + +======================================================================================================================= + + +current setup 3/2011 +^^^^^^^^^^^^^^^^^^^^ +While later we want to automate most of this packaging business, currently it's done semi-manual. +Mostly, Ichthyo builds the packages on his local PC (or a VM) and then adds/imports them to the +'reprepro' -- changes are then propagated to lumiera.org via rsync; as kind of a backup, the +index files are also pushed to link:http://git.lumiera.org/gitweb?p=lumiera/debian;a=shortlog;h=refs/heads/depot[Git]. +---- +rsync -rclvz --progress --partial --delete /local/filesys/path/to/Lumirep/depot/ ichthyo@www.lumiera.org:/var/local/www_debian +---- + diff --git a/doc/technical/infra/index.txt b/doc/technical/infra/index.txt index f1c903af9..a47abbf95 100644 --- a/doc/technical/infra/index.txt +++ b/doc/technical/infra/index.txt @@ -8,6 +8,64 @@ used for building and maintaining documentation and website. * see link:../build/index.html[separate page for the Buildsystem] * generating the link:MenuGen.html[navigation menu] for the website + * how to use the link:rfcsh.html[rfc.sh] script for maintaining RFC's +Other tools in the ./admin folder +--------------------------------- + +There are various other small tools and scripts in the admin folder which are +not yet fully documented (Read the Source!). + +.headercheck +This is a small tool which checks that all headers are sufficiently standalone +and include anything they need. In future we might extend this to find out +bogus includes by predefining (-D) headerguards they include, effectively +disableing this include for a test. + +.render_icon.py +used by the buildsystem to translate svg icons to bitmaps (png) + +.treeinfo.sh +Generates a report about the projects directory structure by parsing the +DIR_INFO files (which have to be maintained manually) + +A DIR_INFO is just a small text file where the first line shall give a short +summary about the purpose of this directory followed by arbitary text giving +more details. + +.git_hooks +A directory containing example git hooks for signing and pushing on commit. +Only use them when you know what you are doing. + +.lumiera_c_skeleton +A script which instantiates a new pair of .c/.h files. + +.vg-run.sh +convenience wrapper script to run an executable with valgrind +using "typical options"; output goes to a logfile, which is +fed to less afterwards. + +A valgrind suppression file is generated automatically, in +case there is an executable "vgsuppression" located in the same +directory as the target executable. + +.gnu-indent +call the "indent" tool with parameters suitable for our (GNU derrived) coding style + +.testrunner +Script driving make and running a test, possibly under valgrind. Works only +for autotools build. + +.vgsuppression_gen.sh +Use an existing 'vgsupression' executable to generate a valgrind supression file. + +Bitrot +------ + +Scripts which are not in use and need some makeover to be removed + + testfilter.sh + rsync_docs_to_lumieraorg.sh + diff --git a/doc/technical/infra/rfcsh.txt b/doc/technical/infra/rfcsh.txt new file mode 100644 index 000000000..40732fed2 --- /dev/null +++ b/doc/technical/infra/rfcsh.txt @@ -0,0 +1,73 @@ +Lumiera RFC maintenance script +============================== + +// Note: the source of this documentation is maintained +// directly admin/rfc.sh in its usage() function +// edit it only there and then regenerate +// doc/devel/technical/infra/ with: +// ./admin/rfc.sh help >doc/technical/infra/rfcsh.txt + +Usage +----- + + ./admin/rfc.sh <command> [options] + +Commands (with <mandatory> and [optional] parameters) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + find <rfcs> [regex]:: List all matching RFC's (matching `regex`) + show <rfcs> [regex]:: Read RFC's (matching `regex`) + create <title>:: Create a new RFC + edit <rfc> [chapter]:: Edit RFC at chapter + asciidoc <rfc>:: pass the rfc.txt to `asciidoc` command + comment <rfc>:: Add a new comment to a RFC + draft <rfc>:: Change RFC to Draft state + final <rfc>:: Change RFC to Final state + park <rfc>:: Change RFC to Parked state + drop <rfc>:: Change RFC to Dropped state + supersede <rfc> <new>:: Supersede RFC with a new RFC + discard <rfc>:: Delete an RFC + help:: Show this help + process:: Do automatic maintenance work + wrap <rfcs>:: canonical reformatting + +Option types +~~~~~~~~~~~~ + + title:: Quoted string used as RFC title + rfc:: Name of the RFC, smart matched, unique + rfcs:: Name of the RFC, smart matched, multiple + regex:: Regex matched against the content of a RFC + chapter:: Heading of a section + + +Smart matching +-------------- + +RFC names don't need to be given exactly, they use a globbing pattern. +This is: + - case insensitive + - whitespaces are ignored + - `*` stands for any number of parameters + - `?` is any single character + - when starting with `/` they are matched against the begin of the name + - some regex operators work too +`find` and `show` can operate on many matches so the given rfc name doesn't +need to be unique. The other commands will complain when the RFC name given +doesn't resolve to one unique RFC. + +When `less` presents multiple files one can go forth and back with the `:n` +and `:p` commands. + +The tile for `create` should be a normal document title. Possibly quoted +since it may contain spaces and not too long. The filename is this title +in CamelCase with all spaces and special characters removed. + +Chapter machching single lines containing this word, special asciidoc +comments in the form `//word:.*` and asciidoc block attributes `[word.*]` +on a single line. When a chapter pattern is not unique, the last one is +picked. + +rfc.sh executes git add/rm/mv commands, but never commits. One should do a +commit as soon he finished editing. + diff --git a/doc/user/intro/intro.txt b/doc/user/intro/intro.txt index 1bc008b7c..0e32a454b 100644 --- a/doc/user/intro/intro.txt +++ b/doc/user/intro/intro.txt @@ -119,7 +119,7 @@ Processing of Video (and audio) data can be generalized as graph processing (more precisely ``directed acyclic graphs''). Data flows on the edges of these graphs and is processed in the nodes. -image:lumiera_big_graph.svg[Example for a graph] +image:{imgd}/lumiera_big_graph.png[Example for a graph] When we look at this model we discover that we only need to build xref:builder[->] such graphs, the nodes themselves can be seen as black boxes @@ -162,7 +162,7 @@ The visible Universe Now its time to take a look at the prelimary Lumiera GUI: -image:lumiera_screenshot.png[Screenshot of Lumiera] +image:{l}/images/lumiera_gui_small.png[Current Lumiera GUI Screenshot] The GUI is a plugin by itself and only one way to work Lumiera, it will become possible to create special-purpose GUIs or control Lumiera in different ways, @@ -178,6 +178,7 @@ xref:screenconcept[->] to adapt to different workplaces and workflows. Viewer ~~~~~~ +[red]#to be written# // only one viewer type used for everything // how is audio integrated in the viewer @@ -194,21 +195,20 @@ Viewer Transport Controls ~~~~~~~~~~~~~~~~~~ -// current gui is not final (transport controls attached to the timeline) -// It is not finally decided where transport controls will be integrated -// possibly as its own gui element +The layout in current gui is rather preliminary -- it is not finally decided +where transport controls will be integrated; possibly as its own gui element -// This are devices either controlled by widgets or by some input device (midi -// etc) so their gui may look differently. -// Either way they connect to a Play Controler xref.. in the core which -// manages playing and cursor positioning. +This are devices either controlled by widgets or by some input device +(MIDI, control surface, etc) so their gui may look differently. +Either way they connect to a Play Controler xref.. in the core which +manages playing and cursor positioning. -// thus there will be some gui facility to attach Transport controls to Play -// Controllers. Transport controls are ganged when they attach to the same -// Play Controler. +thus there will be some gui facility to attach Transport controls to Play +Controllers. Transport controls are ganged when they attach to the same +Play Controler. -// just playing some footage for preview creates a simple internal timeline, -// no magic here. +just playing some footage for preview creates a simple internal timeline, +no magic here. // TODO: bit unrelated, think about how ganging controls in general should // work, also for faders, masks and so on @@ -220,12 +220,13 @@ Transport Controls Timeline View ~~~~~~~~~~~~~ -// hierarchical tracks, not just a stack +hierarchical tracks, not just a list + +Format Independent Timeline, one can put anything on the timeline. +the busses constrain what kind of data is pulled out and in turn the +builder creates a processing graph which does the necessary conversions and +stuff. -// Format Independent Timeline, one can put anything on the timeline. -// the busses constrain what kind of data is pulled out and in turn the -// builder creates a processing graph which does the necessary conversions and -// stuff. // Q: how to handle interaction, for example when some conversion can only be // done in a lossy way and some conversion node may or may not be inserted // (i mean gui wise)? @@ -241,19 +242,23 @@ Timeline View // a special case of a selection. -// Busses -// ~~~~~~ -// How will the gui define busses? +Busses +~~~~~~ +The GUI provides a separate _bus view_, showing the master busses (subgroups) +in a manner similar to an audio mixing desk. Any bus is just a means to collect +and sum up the output of a specific kind of media (video, audio, number of channels), +produced by various processing elements and other busses. Conceptionally, these global +busses are considered a part of the timeline Asset View ~~~~~~~~~~ -// Manages all assets available in one project. -// * source media/footage/soundfiles -// * prepared clips, known subprojects -// * all available effects and transitions -// * internal artefacts like sequences and automation data sets +Manages all assets available in one project. + * source media/footage/soundfiles + * prepared clips, known subprojects + * all available effects and transitions + * internal artefacts like sequences and automation data sets // First this will be simply implemented showing data loaded into the session // and all available plugins/effects @@ -272,18 +277,23 @@ Asset View // the contents of a clip bin can be played like a storyboard +'''''''' + Dark Matter ----------- -// coarse overview about things the user does not see but have some contact -// with, details later... +[red]#to be written# +coarse overview about things the user does not see but have some contact +with, details later... -Now lets take a look under the hood. Lumiera + +Now lets take a look under the hood. Session storage ~~~~~~~~~~~~~~~ +[red]#to be written# // not generateable data @@ -314,15 +324,19 @@ output destination, layering, fade control, audio pan,... Rendering Engine ~~~~~~~~~~~~~~~~ -// rendering +[red]#to be written# +rendering... [[builder]] +[red]#to be written# -// rules system - +rules system +[red]#to be written# I/O Subsystem ~~~~~~~~~~~~~ +[red]#to be written# + // file handling // vault, work, cache // repositories @@ -331,12 +345,16 @@ I/O Subsystem Configuration ~~~~~~~~~~~~~ +[red]#to be written# + // configuration system // serves defaults, actual data are stored in the session Plugins/Interfaces ~~~~~~~~~~~~~~~~~~ +[red]#to be written# + // explain whats it is // portability // versioning @@ -345,6 +363,7 @@ Plugins/Interfaces Rendering Video --------------- +[red]#to be written# // describe the flow of data to render a frame @@ -354,6 +373,7 @@ Rendering Video Pulling a Frame ~~~~~~~~~~~~~~~ +[red]#to be written# // special cases, // case studies, @@ -372,45 +392,19 @@ Pulling a Frame // show some case-studies that someone gets a feel how plugins work -[[pluginstack]] - -//Audio +[red]#TODO# Consider integrating the following things into the document above - -// TODO Following things need to be integrated into the document above - - -* [[plugins]] -* [[timeline]] -* [[demultiplexer]] -* [[multiplexer]] -* [[encoder]] -* [[pull]] -bus defines rendering format -* [[caching]] -* [[profiling]] -* [[rendernode]] -* [[frameserver]] -* [[screenconcept]] -* [[busses]] - -// gui/screen concepts -// perspectives - -// Automation - - - - -// 3 layered model - - -such as that we only need to pull exactly what we need, -posibly down to the pixel, this also allows efficient caching xref:caching[->] -for intermediate data, to be reused later. - +* plugins +* timeline +* pull +* bus defines rendering format +* caching +* frameserver +* screenconcept / perspectives +* automation +* 3 layered model diff --git a/doc/user/intro/lumiera_big_graph.svg b/doc/user/intro/lumiera_big_graph.svg index 67cf01f66..d995d913f 100644 --- a/doc/user/intro/lumiera_big_graph.svg +++ b/doc/user/intro/lumiera_big_graph.svg @@ -33,20 +33,21 @@ borderopacity="1.0" inkscape:pageopacity="0.0" inkscape:pageshadow="2" - inkscape:zoom="1.0518407" - inkscape:cx="564.81009" - inkscape:cy="277.96054" + inkscape:zoom="1.4875274" + inkscape:cx="444.97376" + inkscape:cy="280.84291" inkscape:document-units="px" - inkscape:current-layer="layer2" + inkscape:current-layer="layer4" showgrid="true" - inkscape:window-width="1274" - inkscape:window-height="774" + inkscape:window-width="1668" + inkscape:window-height="1020" inkscape:window-x="0" inkscape:window-y="0" inkscape:window-maximized="0" inkscape:snap-to-guides="false" inkscape:snap-grids="true" - inkscape:snap-global="true"> + inkscape:snap-global="true" + gridtolerance="5"> <inkscape:grid type="xygrid" id="grid2854" @@ -63,8 +64,36 @@ <dc:format>image/svg+xml</dc:format> <dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> - <dc:title /> + <dc:title>Lumiera Data Flow Overview</dc:title> + <cc:license + rdf:resource="http://creativecommons.org/licenses/by-sa/3.0/" /> + <dc:date>Summer 2010</dc:date> + <dc:creator> + <cc:Agent> + <dc:title>Christian Thäter</dc:title> + </cc:Agent> + </dc:creator> + <dc:publisher> + <cc:Agent> + <dc:title>Lumiera.org</dc:title> + </cc:Agent> + </dc:publisher> </cc:Work> + <cc:License + rdf:about="http://creativecommons.org/licenses/by-sa/3.0/"> + <cc:permits + rdf:resource="http://creativecommons.org/ns#Reproduction" /> + <cc:permits + rdf:resource="http://creativecommons.org/ns#Distribution" /> + <cc:requires + rdf:resource="http://creativecommons.org/ns#Notice" /> + <cc:requires + rdf:resource="http://creativecommons.org/ns#Attribution" /> + <cc:permits + rdf:resource="http://creativecommons.org/ns#DerivativeWorks" /> + <cc:requires + rdf:resource="http://creativecommons.org/ns#ShareAlike" /> + </cc:License> </rdf:RDF> </metadata> <g @@ -130,10 +159,10 @@ x="279.23798" y="309.81433" /> <rect - style="fill:#ffffff;stroke:#b3b3b3;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + style="fill:#ffffff;stroke:#b3b3b3;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" id="rect4737" width="110" - height="80" + height="94.736069" x="230" y="354.40942" /> <rect @@ -158,19 +187,16 @@ style="display:inline"> <path style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" - d="m 502,426.40942 40,0" + d="M 500,424.40942 L 540,424.40942" id="path3467" /> - <path - style="fill:none;stroke:#b3b3b3;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" - d="m 502,456.40942 40,0" - id="path3471" /> <path style="fill:none;stroke:#ff0000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" - d="m 502,486.40942 38.57143,-0.51948" - id="path3473" /> + d="M 500,464.40942 L 540,464.40942" + id="path3473" + sodipodi:nodetypes="cc" /> <path - style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2, 2;stroke-dashoffset:0" - d="m 502,441.40942 40,0" + style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:2, 2;stroke-dashoffset:1;stroke-opacity:1" + d="M 500,444.40942 L 540,444.40942" id="path3475" /> <path style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2, 2;stroke-dashoffset:0" @@ -272,6 +298,11 @@ d="M 365,74.580418 L 474.92023,194.40942" id="path2552" sodipodi:nodetypes="cc" /> + <path + id="path3336" + d="M 345,336.82264 L 475,289.40942 L 475,194.40942" + style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2, 2;stroke-dashoffset:0" + sodipodi:nodetypes="ccc" /> </g> <g inkscape:label="Elements" @@ -668,10 +699,10 @@ <g style="display:inline" id="g3629-3" - transform="translate(15,140)"> + transform="translate(15,149.9825)"> <path transform="translate(0,527.95272)" - d="m 265,284.40942 a 15,5 0 1 1 -30,0 15,5 0 1 1 30,0 z" + d="M 265,284.40942 A 15,5 0 1 1 235,284.40942 A 15,5 0 1 1 265,284.40942 z" sodipodi:ry="5" sodipodi:rx="15" sodipodi:cy="284.40942" @@ -681,7 +712,7 @@ sodipodi:type="arc" /> <path transform="translate(0,527.95272)" - d="m 265,279.40942 a 15,5 0 1 1 -30,0 15,5 0 1 1 30,0 z" + d="M 265,279.40942 A 15,5 0 1 1 235,279.40942 A 15,5 0 1 1 265,279.40942 z" sodipodi:ry="5" sodipodi:rx="15" sodipodi:cy="279.40942" @@ -691,7 +722,7 @@ sodipodi:type="arc" /> <path transform="translate(0,527.95272)" - d="m 265,274.40942 a 15,5 0 1 1 -30,0 15,5 0 1 1 30,0 z" + d="M 265,274.40942 A 15,5 0 1 1 235,274.40942 A 15,5 0 1 1 265,274.40942 z" sodipodi:ry="5" sodipodi:rx="15" sodipodi:cy="274.40942" @@ -701,7 +732,7 @@ sodipodi:type="arc" /> <path transform="translate(0,527.95272)" - d="m 265,269.40942 a 15,5 0 1 1 -30,0 15,5 0 1 1 30,0 z" + d="M 265,269.40942 A 15,5 0 1 1 235,269.40942 A 15,5 0 1 1 265,269.40942 z" sodipodi:ry="5" sodipodi:rx="15" sodipodi:cy="269.40942" @@ -892,10 +923,10 @@ <g style="display:inline" id="g3629-3-2" - transform="translate(70,140)"> + transform="translate(70,149.9825)"> <path transform="translate(0,527.95272)" - d="m 265,284.40942 a 15,5 0 1 1 -30,0 15,5 0 1 1 30,0 z" + d="M 265,284.40942 A 15,5 0 1 1 235,284.40942 A 15,5 0 1 1 265,284.40942 z" sodipodi:ry="5" sodipodi:rx="15" sodipodi:cy="284.40942" @@ -905,7 +936,7 @@ sodipodi:type="arc" /> <path transform="translate(0,527.95272)" - d="m 265,279.40942 a 15,5 0 1 1 -30,0 15,5 0 1 1 30,0 z" + d="M 265,279.40942 A 15,5 0 1 1 235,279.40942 A 15,5 0 1 1 265,279.40942 z" sodipodi:ry="5" sodipodi:rx="15" sodipodi:cy="279.40942" @@ -915,7 +946,7 @@ sodipodi:type="arc" /> <path transform="translate(0,527.95272)" - d="m 265,274.40942 a 15,5 0 1 1 -30,0 15,5 0 1 1 30,0 z" + d="M 265,274.40942 A 15,5 0 1 1 235,274.40942 A 15,5 0 1 1 265,274.40942 z" sodipodi:ry="5" sodipodi:rx="15" sodipodi:cy="274.40942" @@ -925,7 +956,7 @@ sodipodi:type="arc" /> <path transform="translate(0,527.95272)" - d="m 265,269.40942 a 15,5 0 1 1 -30,0 15,5 0 1 1 30,0 z" + d="M 265,269.40942 A 15,5 0 1 1 235,269.40942 A 15,5 0 1 1 265,269.40942 z" sodipodi:ry="5" sodipodi:rx="15" sodipodi:cy="269.40942" @@ -1108,12 +1139,12 @@ <text xml:space="preserve" style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial" - x="285" + x="296.88394" y="319.40942" id="text3434"><tspan sodipodi:role="line" id="tspan3436" - x="285" + x="296.88394" y="319.40942">Busses</tspan></text> <text xml:space="preserve" @@ -1128,73 +1159,74 @@ <text xml:space="preserve" style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial" - x="374" + x="383.98251" y="364.40942" id="text3430-0"><tspan sodipodi:role="line" id="tspan3432-2" - x="374" + x="383.98251" + y="364.40942">Viewer</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial;text-anchor:start;text-align:start;writing-mode:lr;line-height:90%" + x="460" + y="174.40942" + id="text3434-2" + sodipodi:linespacing="90%"><tspan + sodipodi:role="line" + id="tspan2554">Switch-</tspan><tspan + sodipodi:role="line" + id="tspan2556">board</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial" + x="550" + y="304.40942" + id="text4506"><tspan + sodipodi:role="line" + id="tspan4508" + x="550" + y="304.40942">Data on Disk</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial" + x="550" + y="364.40942" + id="text4510"><tspan + sodipodi:role="line" + id="tspan4512" + x="550" y="364.40942">Viewer</tspan></text> <text xml:space="preserve" style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial" - x="460" - y="174.40942" - id="text3434-2"><tspan - sodipodi:role="line" - id="tspan3436-9" - x="460" - y="174.40942">Busses</tspan></text> - <text - xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial" - x="548.41583" - y="296.5054" - id="text4506"><tspan - sodipodi:role="line" - id="tspan4508" - x="548.41583" - y="296.5054">Data on Disk</tspan></text> - <text - xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial" - x="550.85516" - y="348.0954" - id="text4510"><tspan - sodipodi:role="line" - id="tspan4512" - x="550.85516" - y="348.0954">Viewer</tspan></text> - <text - xml:space="preserve" - style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial" - x="545.9765" - y="397.85779" + x="545" + y="399.40942" id="text4514"><tspan sodipodi:role="line" id="tspan4516" - x="545.9765" - y="397.85779">Node/Plugin</tspan></text> + x="545" + y="399.40942">Node/Plugin</tspan></text> <text xml:space="preserve" style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial" - x="549.39154" - y="426.15408" + x="545" + y="424.40942" id="text4518"><tspan sodipodi:role="line" id="tspan4520" - x="549.39154" - y="426.15408">Build Connection between Nodes</tspan></text> + x="545" + y="424.40942">Build Connection between Nodes</tspan></text> <text xml:space="preserve" style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial" - x="549.39154" - y="442.74155" + x="545" + y="444.40942" id="text4522"><tspan sodipodi:role="line" id="tspan4524" - x="549.39154" - y="442.74155">Temporary Connection between node</tspan></text> + x="545" + y="444.40942">Temporary Connection between node</tspan></text> <text xml:space="preserve" style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial" @@ -1208,12 +1240,21 @@ <text xml:space="preserve" style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial" - x="255" + x="290" y="109.40942" id="text4711"><tspan sodipodi:role="line" id="tspan4713" - x="255" + x="290" y="109.40942">Preprocessing</tspan></text> + <text + id="text3328" + y="464.40942" + x="545" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial;text-anchor:start;text-align:start;writing-mode:lr;line-height:125%" + xml:space="preserve" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan3332">External Connection</tspan></text> </g> </svg> diff --git a/doc/user/tutorials/DebianBuilding.txt b/doc/user/tutorials/DebianBuilding.txt new file mode 100644 index 000000000..5e33957b6 --- /dev/null +++ b/doc/user/tutorials/DebianBuilding.txt @@ -0,0 +1,198 @@ +building from source -- the Debian Way +====================================== +:Author: Ichthyostega +:Date: 3/2011 + +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. + +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 + 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. +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. + + +building from source package +---------------------------- +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/ lenny experimental +---- +. get all the *build dependencies* ++ +---- +sudo apt-get build-dep nobug-dev +sudo apt-get build-dep libgdl-lum-dev +sudo apt-get build-dep lumiera +---- +. *build* using the source package. ++ +---- +apt-get source --compile nobug-dev +---- + + * After building went through without error, it might happen that you're be + 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. ++ +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' ++ +---- +sudo dpkg -i libnobug2_201008.1-1_i386.deb nobug-dev_201008.1-1_i386.deb +---- ++ +of course, the package names, versions and architecture will vary, depending on your +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 + +. clean up. ++ +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. + + +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 +package more convenient or improve the usage in some way. In addition, it also stores +a list of _suggested_ additional things to try. Now, since some time, the 'Apt' package +management tool by default automatically installs also the _recommended_ software, not +only the bare required prerequisites. + +While this is certainly fine for users not into the details of package management, it +has the downside of installing sometimes _a lot_ of additional software no one asked +about. Plus, all these installed packages are upgraded from time to time. An impressive +example of this kind of _bloat_ is the *asciidoc* package, which recommends to install +dockbook, an complete XML toolchain plus a TeX distribution, giving you an average of +additional 500MB to download and install. + +Of course, this behaviour can be changed. Just add the following line to your Apt configuration +---- +APT::Install-Recommends "false"; +---- +^_Disclaimer:_ please be sure you understand the consequences...^ + + +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' +What follows are some more in-depth explanations and background informations + + +anatomy of a debian source package +---------------------------------- + +Debian source packages provide a standardised way of compiling software. These +packages are not intended to be _installed_ on your system; rather you just download +them and use them to build the software. + +Each Debian source package is based on an original _upstream_ tarball. In addition to +this '\*.orig.tar.gz', there is a '\*.diff.gz' which contains all the _modifications_ +done to the original upstream sources in order to compile it with Debian. Especially, +this so called ``debianisation patch'' adds a 'debian/' subdirectory to the source tree, +which then holds all the control files used by Debian package management. Finally, the +third part of each Debian source package is a _manifest_ file ('*.dsc'), which states +that this is a Debian package and contains the primary control informations, the +name and version number. Of course, these three files are named with a common name +prefix, which matches the 'official' package name and version. + +Quite frequently, a given source package generates several binary packages, e.g. the +main program, maybe a library and a documentation bundle. Because of this, often the +source package is named slightly different then the binary package, which can be a +problem sometimes. If in doubt, use the link:http://packages.debian.org[Debian package +search] or the link:http://packages.ubuntu.com[equivalent for Ubuntu] to locate packages, +versions, even individual files, or to get at the bug tracker for a package. + +interesting files in the debian subdirectory +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Most of the files in that subdirectory are relevant only for the people maintaining +the package. With the exception of the following: + +- the 'debian/control' file defines the properties and *metadata* of the package. Here you'll + find the definition of the prerequisites, the name of the packager, the explanatory text. +- 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 + + +commands for handling source packages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +For all package building tasks, you can use an arbitrary directory of your choice. +It is recommended to build with normal user permissions (not as root). + +- 'apt-get source' PACKAGENAME downloads the three parts of the source package. You may + use both the name of a binary or the source package in this command. After downloading, + the original tarball is extracted and the debianisation patch is applied. That is, + the tree is ready for building +- 'apt-get source \--compile' PACKAGENAME does even more: it starts off the build + of a binary package after downloading and preparing the sources... +- 'dpkg-source -x' SRCPACKAGE.dsc just extracts a source package and applies the diff +- 'sudo apt-get buld-dep' PACKAGENAME fetches and installs all the prerequisites + necessary for building the denoted package. (however, it does _not_ download the + source package itself) +- 'sudo dpkg -i' BIN-PACKAGE.deb finally installs the result of your building efforts. + 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 +source tree, if you want to build the whole package, or even want to tweak and +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 + 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' + +prerequisites for building +~~~~~~~~~~~~~~~~~~~~~~~~~~ +For performing any compiling and packaging tasks, you need some additional software, +which by default isn't installed on a desktop system -- most notably the GNU C compiler. +On any Debian based system, you get these basic tooling by +---- +sudo apt-get install build-essential +---- + +library development packages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +When building software linked against some library, we need additional 'header files' +provided together with the library. Conventionally, these headers are packaged separately +from the library and shipped as a package with a name like 'LIBNAME-dev'. You can safely +__de__install these development packages when done with building. + + + diff --git a/doc/user/tutorials/building.txt b/doc/user/tutorials/building.txt index f7eb94bfc..0092da1cc 100644 --- a/doc/user/tutorials/building.txt +++ b/doc/user/tutorials/building.txt @@ -2,15 +2,26 @@ Building Lumiera from source ============================ Currently, after building the application, you can try out the Lumiera GUI -and you can run the test suite. +and you can run the test suite. This tutorial details the basic procedure +to compile Lumiera on a Linux (or comparable) system. We'll assume that +the reader has acquired basic _commandline survival skills_ and is able +to figure out the usage of the Git version management system from the +documentation (but we'll mention each actually required command +explicitly) -For building Lumiera, besides the GNU C/C++ compiler (Version 4.X), you will -need: +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]). + The purpose of this tutorial here is to show you the elementary + and generic steps to compile Lumiera from source. - * http://git-scm.com/[git] - * http://www.gnu.org/software/libtool/[libtool] - * http://www.boost.org/[Boost libraries] - * http://gmerlin.sourceforge.net/[GAVL library] +For building Lumiera, besides the GNU C/C++ compiler (Version 4.X), you will need: + + * 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) The GUI depends on: @@ -22,17 +33,17 @@ 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` -For most Debian based systems, e.g. Ubuntu, you can install these dependencies -with: +For 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 \ -libgtkmm-2.4-dev librsvg2-dev libtool libxv-dev scons valgrind ------------------------------------------------------------- +------------------------------------------------------------------------------------- +sudo apt-get install build-essential autoconf scons valgrind libtool git-core \ +libboost-dev libboost-program-options-dev libboost-regex-dev libboost-filesystem-dev \ +libgavl-dev libgdl-1-dev libgtkmm-2.4-dev librsvg2-dev libxv-dev +------------------------------------------------------------------------------------- Optionally, you may also want to install the *gtk2-engines* package. + Build directory --------------- @@ -85,8 +96,9 @@ 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. +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 +with an existing (older) installation of GDL. Ubuntu 9.04 note:: intltool-update is not patched, you must add +/usr/share/intltool-debian/+ @@ -121,7 +133,7 @@ variable. Either way, check that all libraries are accessible and OK: ------------------------------------------------------------ -sudo ldconfig -v | grep 'gdl-lum\|nobug' +sudo ldconfig -v | grep 'nobug' ------------------------------------------------------------ and you should get a list of the libraries, part of which should look like this: @@ -132,7 +144,9 @@ 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. If any if this libs are not listed, investigate why before continuing. +or similar. The same holds true for 'libgdl-lum.so.0' if you needed to build it +explicitly for your system. If any if these libraries are not listed, +investigate why before continuing. Building Lumiera @@ -175,20 +189,14 @@ 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. +NOTE: you do not need to _install_ Lumiera. It will find its required files +relative to the generated directory structure, which is freely relocatable +as a whole. Just invoke the +target/lumiera+ executable. The current +working directory is not 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 - * for autotools build: issue `./lumiera` (from within the `build` subdirectory) - * for scons build: -+ -------------------- -cd bin -./lumiera -------------------- - You should see something like: image:{l}/images/lumiera_gui_small.png[Current Lumiera GUI Screenshot] diff --git a/doc/user/tutorials/index.txt b/doc/user/tutorials/index.txt index d8f4fd075..f878cf4bc 100644 --- a/doc/user/tutorials/index.txt +++ b/doc/user/tutorials/index.txt @@ -1,7 +1,10 @@ Tutorials ========= +//Menu: sort children + This page contains tutorials for beginners interested in Lumiera development. * link:building.html[Building Lumiera from source] + * link:DebianBuilding.html[Building from Debian source package] * link:contributing.html[Contributing to Lumiera]