Lumiera is built such that it can be invoked from a ''bundle directory''
without the need to install it into the system; this requires to perform
a relative lookup of shared modules loaded as dependencies.
Since Lumiera has a layered architecture, and each layer is built into a shared object,
we get transitive dependencies and thus transitive relative lookup.
There was a bug in binutils 2.23, which caused that transitive relative lookup to fail.
* as of 2025, Debian/Trixie is defined as ''Reference Platform''
* in Trixie the binutils version is v2.44-3
* after removing the workaround, Lumiera and all tests can be launched
* thus ''considering this workaround as obsolete now''
This is a Debian policy, which collides with the default behaviour
of GCC rsp. the plattform linker. The latter creates all ELF files as
executable, possibly because some platforms require that, and also
because some libraries provide a main() function for diagnostics.
The argument by the Debian people is that most libraries don't provide
such a main() and that this is an esoteric feature which should not be
supported by default.
We can fix that in our SCons build, since we use a specialised Builder
to also define the install targets systematically; it suffices to add
a post-action to these install targets for shared objects.
Note: currently Debian/Trixie provides SCons 4.8, but v4.10 will provide
a shorthand notation with the env.Chmod Action factory.
The XDG Desktop spec is accepted universally, and thus
the old Debian-specific 'menu' system is deprecated and
no longer engaged automatically.
See: https://lists.debian.org/debian-devel-announce/2015/09/msg00000.html
Thus we'll now provide a Desktop file and install that already from out
SCons build system, together with a suitable variation of the Lumiera icon.
TODO: not sure if everything was done the correct way
* do we need to ''register'' the new file in some way (preinst script?)
* the menu entry shows up, but not the icon
* but if we put an absolute path for the lumiera.svg into the desktop file, it shows up
Remark: in later experiments with package building,
the menu entry and the icon showed up in the menu.
Not sure if this requires a reboot or some similar
trigger (like restart of the destkop)
...funny enough I never noticed this obvious mistake,
since I never install software directly into my system,
while the DEB-build does not use absolute paths...
Solution:
* SCons has this speical convention that a path prefixed with '#'
is resolved relative to the root of the build (where the SConstruct resides)
* now we apply this automatically to the two relevant settings
** INSTALLDIR
** TARGDIR
* but only (conditionally) if the configured path is relative, not absolute
As a consequence, most other hard-coded usages of the '#'-prefix can then be dropped
Debian-Docbase allows to register some HTML documentation;
My old package definition added placeholder config, which renders
the documentation configuration invalid (as pointed out by Lintian).
However, I still think it is a good idea to have the anchor point
already defined, and thus I came up with the idea of in fact
providing some usable placeholder content...
As it turns out, we also have a placeholder page at the Lumiera website,
where the User Manual is assumed to be located later — so why not extend
this one and then provide the HTML-rendering for the DEB package?
To allow for this setup
* I have now extended the placeholder page for the Website
to include some generic description about Lumiera (from the 'about' page)
* Furthermore, I added the screenshot (from the »Outer Space« page)
* and I use this a an opportunity to document the various test / demo
facilities currently available in the GUI, since these are rather obscure.
While only intended for the developer, it seems still worthwhile
to describe the possible effects — it may well be that we retain
some of that test/demo functionality and in that case, we have
now already some starting point for a documentation
* Then, to include that page as stand-alone HTML, I used the 'Print Edit WE'-plugin
from Firefox, to encode the images as inline-base64 URLs (which are restored
by a tiny JavaScript embedded into that page)
* and last but not least, our SCons buildsystem needs the ability
to install such a documentation file, since it seems most adequate
to handle this requirement as part of the generic installation (and
not hidden in some Debian scripting)
BuilderDoxygen and BuilderGCH are external plug-ins,
not developed in this project and probably unmaintained.
TODO: decide how to fix or replace them...
The build system Scons switched from using Python 2.7 to using
Python 3.x, so the build breaks on, for example, Debian Bullseye.
As a first step use `ato3` to convert Python scripts from 2 to 3.
* Lumiera source code always was copyrighted by individual contributors
* there is no entity "Lumiera.org" which holds any copyrights
* Lumiera source code is provided under the GPL Version 2+
== Explanations ==
Lumiera as a whole is distributed under Copyleft, GNU General Public License Version 2 or above.
For this to become legally effective, the ''File COPYING in the root directory is sufficient.''
The licensing header in each file is not strictly necessary, yet considered good practice;
attaching a licence notice increases the likeliness that this information is retained
in case someone extracts individual code files. However, it is not by the presence of some
text, that legally binding licensing terms become effective; rather the fact matters that a
given piece of code was provably copyrighted and published under a license. Even reformatting
the code, renaming some variables or deleting parts of the code will not alter this legal
situation, but rather creates a derivative work, which is likewise covered by the GPL!
The most relevant information in the file header is the notice regarding the
time of the first individual copyright claim. By virtue of this initial copyright,
the first author is entitled to choose the terms of licensing. All further
modifications are permitted and covered by the License. The specific wording
or format of the copyright header is not legally relevant, as long as the
intention to publish under the GPL remains clear. The extended wording was
based on a recommendation by the FSF. It can be shortened, because the full terms
of the license are provided alongside the distribution, in the file COPYING.
the new structure causes them now to be installed into $TARGET/stage
which is simply not what I want. I still consider $TARGET/gui the better choice,
since an administrator or packager is not aware of our layer namings.
The existing solution was half baked anyway, it did not really replicate the source tree.
On the other hand, I want to retain the location of the CSS files within the GUI tree,
since I consider it a good practice, to keep "code-like" resources with the actual code,
and not far away in some arcane "data" directory.
No I've noticed, that the env.GuiResource() function is only used once, for this very task.
So, for the time being, we can keep it simple and deditaced to that task, i.e
we pick up all CSS files we find and install it into a single target directory.
NOTE: this issue has brought to my attention two further, completely unrelated issues
* Ticket #1192 (Lumiera hangs on failed GUI start)
* The ProcDispatcher does an idle wait, due to an error in timed-wait implementation
This is a somewhat intricate problem. As long as we linked with --no-as-needed,
these problems could not manifest themselves, since all dependencies are spotted
correctly by SCons and thus added as direct children of the executable.
But when we switch to --as-needed linking, the linker will omit some of
the dependencies given from the build system, when the code to be linked
doesn't call directly into these dependencies. But of course dynamic modules
may depend on each other, and indeed, the Lumiera libs do so. Thus
the linker may omit the dependency to liblumierasupport, and just add
a dependency to, say liblumierabackend. But the backend in turn
depends on the support library.
Now the problem is, that when resolving several steps deep into such
a dependency chain, our special relative path resolution scheme fails.
The fix is to give each lumiera module itself another relative path
resolution spec, which overrides at that point the root spec given
for the executable. Thus, we define
- for the executable: "search at $ORIGIN/modules"
- for the modules: "search at $ORIGIN/../modules"
This accounts for the fact, that a module, which is the Origin
for a transitive resolution step, already sits in a subdirectory
below the executable; thus step one level up and devle down into
the hard wired modules directory. Alternatively, we could also
use just "search at $ORIGIN" (i.e. in the same directory).
But assuming that in future we'll roll several core plugins,
which also count as "Lumiera modules", the scheme defined here
is more flexible, since it allows to place those core plugins
into sibling directories.
Not sure if this works; problem is that the icons
generated from SVG are just dumped into the target
folder, but we miss to generate the respective
installation targets
especially this means to use the common well-known names again,
like "Program" "SharedLibrary". The customisation now happens
invisible in LumieraEnvironment.
the installed lumiera exe can even be started...
...well with a bit of cheating: you need to cd into the lib/lumiera
because the PLUGINPATH problem isn't solved yet
WARNING: breakes build on Debian/stable
Explanation: I tried to provide a backported implementtation of
features introduced with SCons 1.0 (until we can require SCons 1.0 officially)
Unfortionately, some internal APIs changed quite large in 0.97
Have to build in some conditional code, so it works with SCons 0.96 again)
