Build: some further code clean-up and documentation

* Simplify some constructs from the Python-3 migration
 * update copyright, since I did maintain the SCons build continuosly
 * remove unused method from Buildhelper

Furthermore, the documentation page for our build system
https://lumiera.org/documentation/technical/build/SCons.html
has been reworked, to add a synopsis, some further background
information about the internal structure of SCons and about
the specific conventions and definitions used for Lumiera

SConstruct

@@ -4,7 +4,7 @@
 ##
 
 #  Copyright (C)
-#    2008,            Hermann Vosseler <Ichthyostega@web.de>
+#    2008-2025        Hermann Vosseler <Ichthyostega@web.de>
 #
 # **Lumiera** is free software; you can redistribute it and/or modify it
 # under the terms of the GNU General Public License as published by the
@@ -16,7 +16,7 @@
 # NOTE: scons -h for help.
 # This script /defines/ the components and how they fit together.
 # SCons will derive dependencies and the necessary build steps.
-# Read more about the SCons build system at: http://www.scons.org
+# Read more about the SCons build system at: https://www.scons.org
 
 
 # NOTE: Lumiera SCons extension modules and plugins
@@ -52,7 +52,6 @@ SConscript(dirs=['data','src','src/tool','research','tests','doc'], exports='env
 
 # additional files to be cleaned when cleaning 'build'
 env.Clean ('build', [ 'scache.conf', '.sconf_temp', '.sconsign.dblite', 'config.log' ])
-env.Clean ('build', [ 'src/pre.gch' ])
 
 
 
@@ -63,8 +62,8 @@ env.Clean ('build', [ 'src/pre.gch' ])
 Import('lumiera plugins tools gui testsuite')
 
 build = env.Alias('build', lumiera + plugins + tools + gui)
+# this defines the SCons **default target**
 env.Default('build')
-# SCons default target
 
 
 #env.Alias ('all', build + testsuite + doxydoc)

admin/scons/Buildhelper.py

@@ -4,7 +4,7 @@
 ##
 
 #  Copyright (C)
-#    2008,            Hermann Vosseler <Ichthyostega@web.de>
+#    2008-2025        Hermann Vosseler <Ichthyostega@web.de>
 #
 # **Lumiera** is free software; you can redistribute it and/or modify it
 # under the terms of the GNU General Public License as published by the
@@ -104,19 +104,6 @@ def isSrcDir(path, patterns=SRCPATTERNS):
 
 
 
-def filterNodes(nlist, removeName=None):
-    """ filter out scons build nodes using the given criteria.
-        removeName: if set, remove all nodes with this srcname
-    """
-    if removeName:
-        predicate = lambda n : not fnmatch.fnmatch(os.path.basename(str(n[0])), removeName)
-    else:
-        predicate = lambda n : True
-    
-    return list(filter(predicate, nlist))
-
-
-
 def getDirname (d, basePrefix=None):
     """ extract directory name without leading path,
         or without the explicitly given basePrefix
@@ -218,7 +205,7 @@ def extract_localPathDefs (localDefs):
         pattern and returns them wrapped into a Record for convenient access
     """
     def relevantPathDefs (mapping):
-        for (k,v) in list(mapping.items()):
+        for (k,v) in mapping.items():
             if (k.startswith('src') or k.startswith('build') or k.startswith('install')) and Util.is_String(v):
                 v = v.strip()
                 if not v.endswith('/'): v += '/'

admin/scons/LumieraEnvironment.py

@@ -4,7 +4,7 @@
 ##
 
 #  Copyright (C)
-#    2008,            Hermann Vosseler <Ichthyostega@web.de>
+#    2008-2025        Hermann Vosseler <Ichthyostega@web.de>
 #
 # **Lumiera** is free software; you can redistribute it and/or modify it
 # under the terms of the GNU General Public License as published by the
@@ -123,6 +123,7 @@ class LumieraConfigContext(ConfigBase):
 
 
 
+
 ###############################################################################
 ####### Lumiera custom tools and builders #####################################
 
@@ -343,7 +344,7 @@ class LumieraModuleBuilder(WrappedStandardExeBuilder):
                 for t in target:
                     os.chmod(str(t), 0o644)
                 return None
-#           removeExecBit = env.Chmod(toInstall, 0o644)
+#           removeExecBit = env.Chmod(toInstall, 0o644)                    # ◁◁◁ could use this for SCons > 4.10
             msg = '....... clear exec perm %s' % [str(t) for t in toInstall]
             removeExecBit = env.Action(_Chmod, msg)
             env.AddPostAction(toInstall, removeExecBit)

admin/scons/Platform.py

@@ -4,7 +4,7 @@
 ##
 
 #  Copyright (C)
-#    2012,            Hermann Vosseler <Ichthyostega@web.de>
+#    2012-2025        Hermann Vosseler <Ichthyostega@web.de>
 #
 # **Lumiera** is free software; you can redistribute it and/or modify it
 # under the terms of the GNU General Public License as published by the
@@ -140,8 +140,7 @@ def configure(env):
         print("*** unable to build due to the following problems:")
         for isue in problems:
             print(" *  %s" % isue)
-        print()
+        print("\nbuild aborted.")
-        print("build aborted.")
         Exit(1)
     
     print("** Gathered Library Info: %s" % list(conf.env.libInfo.keys()))

admin/scons/Setup.py

@@ -4,7 +4,7 @@
 ##
 
 #  Copyright (C)
-#    2012,            Hermann Vosseler <Ichthyostega@web.de>
+#    2012-2025        Hermann Vosseler <Ichthyostega@web.de>
 #
 # **Lumiera** is free software; you can redistribute it and/or modify it
 # under the terms of the GNU General Public License as published by the

doc/technical/build/SCons.txt

@@ -1,16 +1,44 @@
 SCons Build-System
 ==================
 :author: Ichthyo
-:date: 2012
+:date: 2012 · 2025
+:toc:
 
 //MENU: label SCons Build
 
 Lumiera uses a build system based on https://scons.org/[SCons]
 
-SCons is an open source software construction tool based on Python build definition scripts.
+SCons is an open source software construction tool based on build definition scripts
-Within these build scripts, we define a data structure to describe the parts and dependencies
+written in Python. Within these build scripts, we define a data structure to describe
-of our software. When executed, SCons evaluates those definitions and the actual files in
+the parts and dependencies of our software. When executed, SCons evaluates those
-the source tree to derive a build strategy, which is then performed.
+definitions and the actual files in the source tree to derive a build strategy,
+which is then performed to actually (re)build the software.
+
+Synopsis
+--------
+[cols=">,<m,2<",grid="none"]
+|=====================
+| just build Lumiera: | scons -j#            | # ≔ -1 => all cores
+| build + run Tests:  | scons -j# check      | -> see 'target/,testlog'
+| development build:  | scons -j# testcode   | -> `target/test-suite <TestName>`
+| install:            | scons -j# install    | installs below '/usr/local/', ⚠ sudo
+| see possible config:| scons -h             | ⚠ settings are *sticky* -> see './optcache'
+|=====================
+
+
+
+.Known shortcomings of SCons
+[NOTE]
+--
+* No one knows it
+* It is written in Python
+* It is _declarative_ not _imperative_ +
+  Thus people hate that they can not just figure out some script
+* A SCons build can not be manipulated by setting environment variables
+* SCons has no default interface for package managers. +
+  Each project has to solve that individually...
+* SCons is not a platform-, package- and dependency manager.
+--
 
 SCons core concepts
 -------------------
@@ -18,19 +46,21 @@ SCons core concepts
 
 .SCons Environment
 When SCons starts building the project, it creates its own environment with dependency trees,
-helper functions, builders and other stuff. The SCons environment is created in memory and some parts of it
+helper functions, builders and other stuff. The SCons environment is built in memory and some parts of it
 are saved to disk to speed up things on the next start. The definition of the build happens within this
-artificial build environment. This often confuses people who used Makefiles, where environment is actually
+abstracted build environment. This often confuses people who used Makefiles, where ``environment'' is actually
 the System Environment.
 
 .System Environment
 the familiar operating system container with environment variables such as PATH, HOME etc.
 It is usually accessible via os.environ mapping in Python and therefore in SCons too.
-SCons doesn't import any settings from System Environment automatically (like flags for compilers,
+SCons does not automatically import any settings from System Environment automatically
-or paths for tools), because it's designed to be a cross platform tool with _predictable behaviour._
+(like flags for compilers, or paths for tools), because it's designed to be a cross platform tool
-That's why, if you rely on any system PATHs or environment variables -- you need to extract
+with _predictable behaviour._
+If you rely on any system PATHs or environment variables -- you need to extract
 those settings explicitly in your build definition.
 
+
 .SConstruct
 when SCons executes, it performs a build definition python script written by the user.
 By convention, this main script is called 'SConstruct' and is located in the root of the source tree.
@@ -44,10 +74,22 @@ the sub-trees of the project.
 
 .Builder
 The SCons buildsystem revolves around the metaphor of a _Builder_. This is a SCons object that you explicitly
-invoke from the scripts to _define_ that there is something to build, transforming a _source_ into a _target_.
+invoke from the scripts to _define_ that there is something to build, thereby transforming a _source_ into a _target_.
 So the target depends on the sources, and typically those _source nodes_ were created by previous builder invocations.
-The power of SCons is in the fact that dependencies are tracked automatically. When source files change, the system
+The use of Builders is _declarative:_ it is a statement _that_ a transformation (build step) has to happen, while
-is able to derive which targets to rebuild.
+the knowledge _how_ this can be achieved is kept implicit within the buildsystem.
+
+.Action
+These are are functors that perform something (execute an external command or call a python function, for instance).
+A Builder retains a list of Actions needed to update its targets; those Actions are run when needed.
+
+.Node
+This is the basic building block of the dependency graph, while the arcs are created by using Builders:
+a Node represents a filesystem object, such as a file or directory which can also be a build result and
+as such does not exist yet. There are also Alias nodes and Value nodes which represent setting values.
+The power of SCons is in the fact that dependencies can be tracked and a build strategy can be derived,
+automatically, based on the structure of this dependency graph. And because the building blocks of that
+graph are _abstract,_ users can _represent the specifics of their build_ in an uniform way.
 
 .Scanner
 when defining a builder, SCons relies on modular scanner components to ``understand'' the source of the build step.
@@ -58,26 +100,46 @@ through plug-ins.
 .Tool
 any further, external component that adds Builders, Scanners and other helpers to SCons environments
 for use within scripts. There are special tools for _configuring the platform_ to detect libraries and
-further requirements. Relying on those tools. the build environment will be outfitted to reflect the
+further requirements. Tools do not operate themselves, rather they will configure the build environment
-needs of the specific build. Sub-environments with special configuration may be created.
+to reflect the needs of the specific build.
+
+.Construction Variable
+All key-value settings within a Construction Environment which are used to instruct SCons about builds.
+Construction Variables can describe compiler flags, locations of commands to execute, and many other characteristics.
+They are used for _text substitution_ in command template strings for invocation of external commands, relying on
+the usual `$VARIABLE` syntax. Since the configuration of a SCons environment is defined by its
+Construction Variables, sub-environments with special configuration may be created.
+
+.Signature
+SCons computes a signature for elements on the dependency graph using a cryptographic hash function which
+has the property that the same input repeatably leads to the same signature. The default function is MD5.
+Signatures are used throughout SCons to identify file contents, build command lines, or to identify cached
+build artefacts. Signatures are chained to determine if something needs to be re-built.
 
 .Target
-any _node_ or ``build step'' encountered through the definition of the build is a _target_. The actual build
+any _Node_ or ``build result'' encountered through the definition of the build is a _target_. The actual build
 will be triggered by requesting a target, which typically might be just an executable known to reside at some
-location in the tree. Special _alias targets_ may be defined, based on other targets, to trigger off standard
+location in the tree, or a _target directory_ where the build is assumed to place build results.
-build situations. Especially, a _default_ target may be defined.
+Special _alias targets_ may be defined, based on other targets, to set off standard
+build sequences. Notably, a _default_ target can be defined for the build.
 
 ''''
+....
+​
+​
+​
+....
+
 
 Organisation of the Lumiera SCons build
 ---------------------------------------
-Within our build system, we build upon the power of the Python programming language to create abstractions
+Within our build system, we leverage the power of the Python programming language to create abstractions
-tailored to the needs of our project. Located in the `admin/scons` subdirectory, you'll find a collection
+tailored to the needs of our project. Located in the 'admin/scons' subdirectory, you'll find a collection
 of Python modules to provide these building blocks.
 
 - the *LumieraEnvironment* is created as a subclass of the standard SCons build environment; it is
-  outfitted with pre-configured custom builders for executables, libraries, extension module, Lumiera plug-in
+  outfitted with pre-configured custom builders for executables, libraries, extension modules,
-  and icon resources.
+  Lumiera plug-ins and icon resources.
 - all these *custom builders* implement a set of conventions and directory locations within the tree.
   These are defined (and can be adjusted) in the *Setup.py* module. This way, each builder automatically
   places the generated artefacts at standard build and installation locations.
@@ -89,15 +151,15 @@ Sub-trees
 ~~~~~~~~~
 .the source tree
 All sourcecode of the core application resides below `src/`. Building these components is controlled by
-the SConscript residing in this application source root. By convention, this is also the root for header
+the SConscript located within this application source root. By convention, this is also the root for header
 includes -- _all headers should be included relative_ to `src/`.
 
 .the three layers
 Within this application core tree, there are sub-trees for the main layers comprising the application.
 Each of these sub-trees will be built into a shared library and then linked against the application framework
-and common services residing in `src/common`. These common services in turn are also built into a shared
+and common services residing in 'src/common'. These common services in turn are also built into a shared
 library `liblumieracommon.so`, as is the collection of helper classes and support facilities, known as
-our 'support library' `liblumierasupport.so`. Besides, there is a sub-tree for core plug-ins and helper tools.
+our `support library' `liblumierasupport.so`. Besides, there is a sub-tree for core plug-ins and helper tools.
 
 .the GTK Gui
 one of the sub-trees, residing in `src/stage` forms the _upper layer_ or _user-interaction layer_. Contrary to
@@ -106,51 +168,68 @@ Thus, the GTK Gui is built and loaded as Lumiera a plug-in.
 
 .unit tests
 Since our development is test-driven, about half of the overall code can be found in unit- and integration
-tests, residing below `test/`. There is a separate SConscript file, to define the various
+tests, arranged below 'test/'. There is a separate SConscript file, to define the various
 link:{ldoc}/technical/infra/TestSupport.html[kinds of test artefacts] to be created.
 
-- plain-C tests are defined in _test-collections_, grouped thematically into several subdirectories.
+- the tests to cover C++ components are organised into test-suites, residing in separate sub-trees.
-  Here, each translation unit provides a separate +main()+ function and is linked into a stand-alone
+  Currently (as of 11/2025), we link each sub-tree into a shared test library. Here, individual
-  executable (yet still linked against the appropriate shared libraries of the main application layers)
+  translation units define individual test case classes. At the end, all these test units
-- the tests covering C++ components are organised into test-suites, residing in separate sub-trees.
-  Currently (as of 5/2015), we link each sub-tree into a shared test library. Here
-  individual translation units define individual test case classes. At the end, all these unit tests
   are linked together with a testrunner `main()` into the `test-suite` executable.
+- plain-C tests are defined in _test-collections_, grouped thematically into several subdirectories.
+  Here, each translation unit provides a separate `main()` function and is linked into a stand-alone
+  executable (yet still linked against the appropriate shared libraries of the main application layers)
 
 .research
-There is a separate subtree for research and experiments. The rationale being to avoid re-building most
+There is a separate subtree for research and experiments. The rationale is to provide a simplified
-of the core application when it comes to experimenting and trying out new technologies.
+and flexible dependency structure for investigating fundamental problems and to try out new technologies.
+Notably there is a source file 'try.cpp', which is linked against all of the core libraries and is re-used
+any time some language features need further investigation or when new implementation techniques are pioneered.
 
 .icons and resources
-the +data/+ subtree holds resources, configuration files and icons for the GUI. Most of our icons
+the 'data/' subtree holds resources, configuration files and icons for the GUI. Most of our icons
-are defined as SVG graphics. The build process creates a helper executable (+rsvg_convert+) to render
+are defined as SVG graphics. The build process creates a helper executable (`rsvg_convert`) to render
 these vector graphics with the help of lib Cairo into icon collections of various sizes.
 
 .documentation
-Largely, the documentation is written in Asciidoc and provided online at link:{ldoc}/[the documentation section]
+Largely, the documentation is written in Asciidoc and provided online in the link:{ldoc}/[documentation section]
-of our website. The plain-text sources of this documentation tree is shipped alongside with the code.
+of our website. The plain-text sources of this documentation tree are shipped alongside with the code.
-Besides, we build *Doxygen* API documentation there, and we create design and technical specs and drawings
+Besides, we build *Doxygen* link:/doxy/[API documentation] there, and we create design and
-in SVG and in UML.
+technical specs and drawings in SVG and in UML.
 
 .the target directory
 This is where the results of the build process are created. Lumiera is organised into a
-_self contained folder structure_. As long as the relative locations, as found within +target/+,
+_self contained folder structure_. As long as the relative locations, as found within 'target/',
 are kept intact, the Application will be able to start up and find all its resources. Consequently,
-there is no need to ``install'' Lumiera (and the ``install'' target just copies this folder structure
+there is no need to ``install'' Lumiera -- in can always be launched from a package bundle placed
-into the standard installation locations of a typical Unix system)
+into some directory. In fact, the ``install'' target just copies this folder structure into the
+standard installation locations in accordance with the Filesystem Hierarchy Standard for Unix systems
 
-Unfortunately SCons is a bit weird regarding the object files created during the build process.
+WARNING: Unfortunately SCons is a bit weird regarding the object files created during the build process.
-So, for the time being, we're just building in-tree. Apologies for that.
+         So, for the time being, we're building in-tree. Apologies for that. +
+         [underline]#2025#: this aspect has been improved _upstream,_ yet we did not find the time
+         to rework our build system accordingly. Apologies for that...
+
+.installation
+As described xref:_organisation_of_the_lumiera_scons_build[above], a custom environment
+baseclass `LumieraEnvironment` is used to configure preconfigured builders, which always define
+an installation target alongside with the build target. These installation targets are arranged
+into a subtree with a _prefix,_ which is by default 'usr/local' -- following the conventions of
+the Filesystem Hierarchy Standard. As long as you just build stuff, you won't notice these
+installation targets, since by default they are located outside of the project tree. However,
+by customising the build options `PREFIX` and `INSTALLDIR`, this installation tree can be relocated.
+For example, our DEB package uses `PREFIX=usr INSTALLDIR=debian/lumiera`
+(please note that such settings are cached in './optcache' and that
+changing them causes a full rebuild)
 
 
 Invoking the Build
 ~~~~~~~~~~~~~~~~~~
-All of the build process is launched through the `scons` python script, usually installed into
+All of the build processing is launched through the `scons` python script, usually installed into
-`/usr/bin` when installing the SCons package onto the system. Just invoking
+`/usr/bin` when installing the SCons package onto the system. And by just invoking
 
  scons -h
 
-prints a summary of all custom options, targets and toggles defined for our build.
+a summary of all custom options is printed, with targets and toggles defined for our build.
 
 Targets
 ^^^^^^^
@@ -162,15 +241,19 @@ Targets
 - *all* builds the Application, test-suites and documentation
 - *install* builds and installs the Lumiera Application
 
-By convention, invoking `scons -c` <TARGET> will _clean up_ everything the given target _would_ build.
+Cleaning
+^^^^^^^^
+By convention, an invocation of `scons -c` <TARGET> will _clean up_ everything the given target _would_ build.
 Thus, invoking `scons -c /` is the most global clean operation: it will clean up al build artefacts and
 will un-install Lumiera (recall: every defined node, or directory is also a target).
 
 Configure checks
 ^^^^^^^^^^^^^^^^
-SCons does not support the concept of a separate ``configure'' step. The necessary dependency detection is
+By deliberate choice, SCons does not support the concept of a separate ``configure'' stage.
-performed before each build. Currently, we expect _all dependencies to be installed first-class_ into
+The necessary dependency detection is performed before each build, but with effective caching
-the system. We do not (yet) support custom libraries in strange locations. Please use your package manager.
+of detected settings. Currently, we expect _all dependencies to be installed first-class_ into
+the system. Custom packages can be installed at '/usr/local' -- however, we do not (yet) support
+custom libraries in arbitrary locations, passed as configuration. Please use your package manager.
 
 Caching and MD5 sums
 ^^^^^^^^^^^^^^^^^^^^
@@ -191,3 +274,84 @@ We provide several custom configuration options (run `scons -h` to get a summary
 options are *sticky*: once set, the build system will recall them in a file '.optcache' and apply
 them the same way in subsequent builds. It is fine to edit '.optcache' with a text editor.
 
+
+Technical Details
+~~~~~~~~~~~~~~~~~
+The following sections provide additional information helpful when adapting the build system.
+It should be noted that the SCons scripts are _Python modules_, invoked within a special setup.
+Python has a host of specific tweaks and kinks, notably regarding visibility, definition order,
+imports and the use of standard data types like lists, dictionaries and generator functions.
+Python knowledge is widespread nowadays, yet we had ample opportunity to notice that, for
+people not familiar with the Python idiom, the SCons scripts may seem arcane and confusing.
+
+Invocation
+^^^^^^^^^^
+After some basic checks of setup and the given command line, the SCons builder immediately
+loads the 'SConstruct' as module -- and expects that this python DSL code builds a project
+model data structure. The actual build is then driven by evaluating the dependency graph
+as implied by that model.
+
+The individual 'SConscript' definitions for each subfolder must be activated explicitly
+from the 'SConstruct', using the `SConscript(dirs=[...])` builder function. Note furthermore
+that the order of the dirs mentioned in this invocation matters, since each 'SCconscript'
+usually _imports_ some global variables at the beginning and _exports_ other settings
+at the end. Before evaluating a 'SConscript', the working directory is changed.
+
+TIP: you can launch `scons` with a python debugger, using the Lumiera directory as
+     working location and set breakpoints in 'SConstruct' or in any of our custom
+     python modules to investigate problems with some build definition not taking effect
+     as expected. Inspect the dictionary of the `Environment` with the debugger to
+     find out what has actually been configured...
+
+Start-up sequence
+^^^^^^^^^^^^^^^^^
+The Lumiera build system engages in a specific start-up sequence, which is explicitly
+coded and expands beyond the standards of the SCons build system.
+
+- first we add our _tool directory_ below 'admin/scons' to the search path,
+  so that tools and python modules defined there become visible.
+  You _must familiarise yourself_ with the contents of this directory!
+- next we create our custom root `LumieraEnvironment` instance, which is stored
+  and exported in the global variable `env`. This environment setup is done by
+  the python module 'admin/scons/Setup.py'
+- this module has some module-level definitions for standard path locations,
+  and all these settings are imported into a dictionary and placed into the
+  member field `env.path` of the `LumieraEnvironment`. All our custom builders
+  use these central settings as shared configuration.
+- once the base constructor of the SCons `Environment` class is invoked,
+  the command line is evaluated to populate the Construction Variables.
+- next, the constructor of our custom `LumieraEnvironment` installs
+  our custom tools and builder functions.
+- the last step in the start-up sequence is to invoke the `Platform.configure(env)`
+  function, which performs all the library and platform checks. This function
+  also configures the default compiler flags.
+
+Nested Build Environment
+^^^^^^^^^^^^^^^^^^^^^^^^
+Several of the 'SConscript' in subdirectories will create a nested build environment,
+which obviously derives from `LumieraEnvironment`. This way we can configure
+additional link dependencies and build configurations for some subtrees, like
+building the GUI against GTK or handling plug-in modules specifically.
+
+The custom ELF builders
+^^^^^^^^^^^^^^^^^^^^^^^
+These custom builders like `env.Program`, `env.SharedLibrary`, `env.LoadableModule`
+and `env.LumieraPlugin` are also defined in the `LumieraEnvironment.py` module.
+All these classes inherit from the SCons `Environment` through the common baseclass
+`WrappedStandardExeBuilder` -- which defines a special arrangement where an _install target_
+is always defined alongside the build target. This install target is ``dropped off'' as
+a side-effect, while _the build target will be returned._
+
+Composite targets
+^^^^^^^^^^^^^^^^^
+In SCons, a builder returns a list of target nodes, and these can be passed in a flexible
+way to further builders. At several places in our 'SConscript' definitions, we use
+Python functions defined within that script to manipulate and aggregate such
+target lists. Notably, specific sets of targets can be combined into a
+shared object (dynamic library), which is then again a SCons target
+and can be passed to other executable builders as library dependency
+for compilation and linking. Look into 'src/SConscript' or 'test/SConscript'
+to see examples of that technique -- which we also use to define that
+global compound target variables like `core`, `app_lib`, `core_lib`,
+`vault_lib`, and `support_lib`. These in turn are essential for
+building the layered dependency hierarchy in our code.

doc/technical/build/index.txt

@@ -10,7 +10,7 @@ As work progresses, we will add more information on the Lumiera build system.
 
 build -- continuous integration -- packaging
 
-* link:SCons.html[Buildsystem]
+* link:SCons.html[SCons Buildsystem]
 * link:BuildDependencies.html[Lumiera Build Dependencies]
 * link:BuildDroneDraft.html[»Builddrone« concept from 2008]
 * Packaging: link:LumieraDebianPackage.html[Debian] RPM

tests/SConscript

@@ -80,8 +80,8 @@ testSrcDirs = globRootdirs('*')
 
 
 testcases  = [testCases(env, dir)  for dir in testSrcDirs if not dir in specialDirs]
-testLibs   = sharedTestLibs.values()
+testLibs   = list(sharedTestLibs.values())
-testrunner = envSuite.Program("test-suite", ["testrunner.cpp"]+list(testLibs)+list(core_lib))
+testrunner = envSuite.Program("test-suite", ["testrunner.cpp"]+testLibs+core_lib)
 
 
 testsuite = ( testcases
@@ -96,7 +96,7 @@ Export('testsuite')
 
 
 # for creating a Valgrind-Suppression file
-vgsuppression = envSuite.Program('vgsuppression',['tool/vgsuppression.c']+list(testLibs)+list(core_lib))   ## for suppressing false valgrind alarms
+vgsuppression = envSuite.Program('vgsuppression',['tool/vgsuppression.c']+testLibs+core_lib)   ## for suppressing false valgrind alarms
 
 
 #
@@ -139,7 +139,7 @@ Depends(runTests,vgsuppression)
 
 
 #
-# define Phony targets
+# define Alias targets
 #  - 'scons testcode' triggers building of the Testsuite
 #  - 'scons check' triggers building and running
 #

wiki/thinkPad.ichthyo.mm

@@ -167947,7 +167947,8 @@ that situation will improve in forseeable future.</pre>
 <icon BUILTIN="help"/>
 <icon BUILTIN="button_cancel"/>
 </node>
-<node BACKGROUND_COLOR="#eee5c3" COLOR="#990000" CREATED="1751808890315" ID="ID_1632926954" MODIFIED="1751808916136" TEXT="Dokumentation nachf&#xfc;hren">
+<node BACKGROUND_COLOR="#eee5c3" COLOR="#990000" CREATED="1751808890315" ID="ID_1632926954" MODIFIED="1764034017617" TEXT="Dokumentation nachf&#xfc;hren">
+<linktarget COLOR="#463451" DESTINATION="ID_1632926954" ENDARROW="Default" ENDINCLINATION="-299;1671;" ID="Arrow_ID_290901015" SOURCE="ID_1856351101" STARTARROW="None" STARTINCLINATION="-169;-46;"/>
 <icon BUILTIN="flag-yellow"/>
 <node COLOR="#338800" CREATED="1751808926894" FOLDED="true" ID="ID_590515881" MODIFIED="1762803684786" TEXT="Versionsnr">
 <icon BUILTIN="button_ok"/>
@@ -169006,8 +169007,7 @@ that situation will improve in forseeable future.</pre>
       Wobei in diesem Kontext zweifelhaft ist, was ein maschinenlesbarer Code auf einer allgemeinen Lizenz-Seite bringen soll. Das w&#252;rde eigentlich nur Sinn machen, wenn der Button auf jeder Seite w&#228;re
     </p>
   </body>
-</html>
+</html></richcontent>
-</richcontent>
 <node CREATED="1762820942381" ID="ID_964155791" MODIFIED="1762820954510" TEXT="ChatGPT gefragt">
 <icon BUILTIN="wizard"/>
 <node CREATED="1762820957170" ID="ID_1885929709" MODIFIED="1762821083898" TEXT="es gab wohl einen Policy-Change">
@@ -169018,8 +169018,7 @@ that situation will improve in forseeable future.</pre>
       So stellt es zumindest ChatGPT dar. Demnach habe man die Empfehlungen bei CC vereinfacht, und biete nun einfach Grafiken an, die die User in ihre Website packen k&#246;nnen.
     </p>
   </body>
-</html>
+</html></richcontent>
-</richcontent>
 </node>
 <node CREATED="1762820965203" ID="ID_925163391" MODIFIED="1762821001026" TEXT="ChatGPT empfiehlt, &lt;link rel=&quot;license&quot;...&gt; Elemente in den HTML-Header zu packen"/>
 </node>
@@ -169200,8 +169199,7 @@ that situation will improve in forseeable future.</pre>
       ....und jeweils sehen ob sich das bew&#228;hrt und entsprechend klar ist
     </p>
   </body>
-</html>
+</html></richcontent>
-</richcontent>
 </node>
 <node CREATED="1762906124189" ID="ID_488826279" MODIFIED="1762906200724" TEXT="zun&#xe4;chst einmal: die feingranulare Aufteilung aufgeben">
 <richcontent TYPE="NOTE"><html>
@@ -171892,7 +171890,7 @@ Since then others have made contributions, see the log for the history.</font></
 </node>
 <node BACKGROUND_COLOR="#eef0c5" COLOR="#990000" CREATED="1742175483087" ID="ID_40670399" MODIFIED="1763770261946" TEXT="Nacharbeiten">
 <icon BUILTIN="pencil"/>
-<node BACKGROUND_COLOR="#f0d5c5" COLOR="#990033" CREATED="1742175488343" ID="ID_842750245" MODIFIED="1742175503373" TEXT="Listen-Konkatenation: geht es besser?">
+<node COLOR="#435e98" CREATED="1742175488343" ID="ID_842750245" MODIFIED="1764035205131" TEXT="Listen-Konkatenation: geht es besser?">
 <icon BUILTIN="help"/>
 <node CREATED="1742175505805" ID="ID_1316231941" MODIFIED="1742175579374" TEXT="Benny hat die Standard-Migration gemacht...">
 <richcontent TYPE="NOTE"><html>
@@ -171905,6 +171903,21 @@ Since then others have made contributions, see the log for the history.</font></
 </html></richcontent>
 <icon BUILTIN="info"/>
 </node>
+<node CREATED="1764035105537" ID="ID_837953449" MODIFIED="1764035204050" TEXT="in der Tat: fast alle list()-Aufrufe kann man loswerden oder eleganter schreiben">
+<richcontent TYPE="NOTE"><html>
+  <head/>
+  <body>
+    <ul>
+      <li>
+        wenn ich gleich wieder dar&#252;ber iteriere, ist es nicht notwendig, zu materialisieren
+      </li>
+      <li>
+        und f&#252;r Debendencies gilt: sie m&#252;ssen ohnehin eine Liste sein in SCons, also besser an der Erzeugungsstelle einmal in eine Liste packen
+      </li>
+    </ul>
+  </body>
+</html></richcontent>
+</node>
 </node>
 <node BACKGROUND_COLOR="#eee5c3" COLOR="#990000" CREATED="1763245245613" ID="ID_525244825" MODIFIED="1763940646058" TEXT="Python verpflichtend auf 3.0 heben">
 <arrowlink COLOR="#e1253b" DESTINATION="ID_1681367379" ENDARROW="Default" ENDINCLINATION="-773;-68;" ID="Arrow_ID_835035037" STARTARROW="None" STARTINCLINATION="-19;733;"/>
@@ -177986,10 +177999,17 @@ Since then others have made contributions, see the log for the history.</font></
 </node>
 <node BACKGROUND_COLOR="#eef0c5" COLOR="#990000" CREATED="1742175264309" ID="ID_1163480280" MODIFIED="1763770089575" TEXT="Preview-Release">
 <icon BUILTIN="pencil"/>
-<node CREATED="1742175666415" ID="ID_1986444286" MODIFIED="1742175670216" TEXT="Git-Flow einf&#xfc;hren">
+<node COLOR="#338800" CREATED="1742175666415" ID="ID_1986444286" MODIFIED="1764034071724" TEXT="Git-Flow einf&#xfc;hren">
+<icon BUILTIN="button_ok"/>
 <node CREATED="1742175672550" ID="ID_624745919" MODIFIED="1742175678761" TEXT="Namen und Schema definieren"/>
 <node CREATED="1742175679613" ID="ID_781377863" MODIFIED="1742175686624" TEXT="Doku f&#xfc;r die Website anlegen"/>
 </node>
+<node BACKGROUND_COLOR="#c2c6e6" COLOR="#435e98" CREATED="1764033907681" ID="ID_1856351101" MODIFIED="1764034061668" TEXT="Website putzen">
+<arrowlink COLOR="#463451" DESTINATION="ID_1632926954" ENDARROW="Default" ENDINCLINATION="-299;1671;" ID="Arrow_ID_290901015" STARTARROW="None" STARTINCLINATION="-169;-46;"/>
+<node CREATED="1764033915824" ID="ID_719881939" MODIFIED="1764033922236" TEXT="nach defekten Links suchen"/>
+<node CREATED="1764033923939" ID="ID_1847280993" MODIFIED="1764033931026" TEXT="alte RfCs durchgehen"/>
+<node CREATED="1764033939267" ID="ID_1000584650" MODIFIED="1764033951275" TEXT="Lizenz und Impressum"/>
+</node>
 </node>
 <node BACKGROUND_COLOR="#eef0c5" COLOR="#990000" CREATED="1742175254850" ID="ID_1647788626" MODIFIED="1763770083926" TEXT="Lumiera-DEB bauen">
 <icon BUILTIN="pencil"/>
@@ -178446,9 +178466,20 @@ Since then others have made contributions, see the log for the history.</font></
 </html></richcontent>
 </node>
 </node>
-<node BACKGROUND_COLOR="#fdfdcf" COLOR="#ff0000" CREATED="1763940534858" ID="ID_1681367379" MODIFIED="1763940646059" TEXT="Python 3.10 nun verpflichtend">
+<node BACKGROUND_COLOR="#fdfdcf" COLOR="#ff0000" CREATED="1763940534858" ID="ID_1681367379" MODIFIED="1764036260885" TEXT="nun verpflichtend">
 <linktarget COLOR="#e1253b" DESTINATION="ID_1681367379" ENDARROW="Default" ENDINCLINATION="-773;-68;" ID="Arrow_ID_835035037" SOURCE="ID_525244825" STARTARROW="None" STARTINCLINATION="-19;733;"/>
-<icon BUILTIN="flag-pink"/>
+<icon BUILTIN="yes"/>
+<node CREATED="1764036266123" ID="ID_1269311547" MODIFIED="1764036269147" TEXT="Python 3.10"/>
+<node CREATED="1764036270057" ID="ID_541648492" MODIFIED="1764036383513" TEXT="SCons 4.0">
+<richcontent TYPE="NOTE"><html>
+  <head/>
+  <body>
+    <p>
+      ...naja, nicht wirklich, denn dazu m&#252;&#223;te ich mal die ganze SCons-Doku durhclesen, um zu sehen, was man modernisieren k&#246;nnte. Aber da ich nun nur noch mit entsprechend neuerer Software arbeite, ist es auch nicht mehr angemessen, eine niedrigere Version zu deklarieren, da ich nicht merke, wenn ich neuere Feature verwende, die irgendwo im Internet beschrieben sind.
+    </p>
+  </body>
+</html></richcontent>
+</node>
 </node>
 </node>
 <node CREATED="1544239177727" HGAP="90" ID="ID_1414932362" MODIFIED="1763514226786" TEXT="Probleme..." VSHIFT="3">
@@ -178682,9 +178713,7 @@ Since then others have made contributions, see the log for the history.</font></
 <icon BUILTIN="yes"/>
 <node CREATED="1764009925908" ID="ID_1806313650" MODIFIED="1764010011962" TEXT="das ist eigentlich ein Problem von ld.so">
 <richcontent TYPE="NOTE"><html>
-  <head>
+  <head/>
-    
-  </head>
   <body>
     <p>
       der verh&#228;lt sich nach dem Motto: &#187;schad ja nix&#171;...
@@ -178693,14 +178722,11 @@ Since then others have made contributions, see the log for the history.</font></
       Auf einigen esoterischen Platformen m&#252;ssen Shared-Libs tats&#228;chlich executable sein, und auf allen anderen Plattformen wird das Flag ignoriert
     </p>
   </body>
-</html>
+</html></richcontent>
-</richcontent>
 </node>
 <node CREATED="1764010013333" ID="ID_1353176139" MODIFIED="1764010266252" TEXT="aber Debian hat eine dem entgegenstehende Policy">
 <richcontent TYPE="NOTE"><html>
-  <head>
+  <head/>
-    
-  </head>
   <body>
     <p>
       Es ist n&#228;mlich so: Shared-Libs k&#246;nnen eine <font face="Monospaced" color="#711313">main()</font>-Funktion enthalten; und <i>wenn das der Fall ist,</i>&#160;k&#246;nnen sie auch als Executables aufgerufen werden. <i>Rein theoretisch</i>&#160;k&#246;nnte das ein Baustein in einem komplexen Exploit sein, der aus einer &#252;berraschenden Ecke k&#228;me, da das ein Thema ist, was niemand &#187;auf dem Radar hat&#171;. Manche Libraries haben in der Tat ein Main, und das macht typischerweise gewisse Diagnose-Funktionalit&#228;t.
@@ -178712,8 +178738,7 @@ Since then others have made contributions, see the log for the history.</font></
       Klingt alles doch einigerma&#223;en an den Haaren herbeigezogen, aber Debian stellt sich auf den Standpunkt: Unn&#246;tiges verbieten schad' nix
     </p>
   </body>
-</html>
+</html></richcontent>
-</richcontent>
 </node>
 <node COLOR="#435e98" CREATED="1764010269199" FOLDED="true" ID="ID_287582178" MODIFIED="1764032099126" TEXT="wir k&#xf6;nnen das durch explizite Filesystem-Operationen reparieren">
 <icon BUILTIN="idea"/>
@@ -178722,23 +178747,18 @@ Since then others have made contributions, see the log for the history.</font></
 </node>
 <node BACKGROUND_COLOR="#e0ceaa" COLOR="#690f14" CREATED="1764015806283" ID="ID_618375602" MODIFIED="1764015945324" TEXT="&#x26a0; Limitierung: ich mu&#xdf; es an einen bestehenden Install()-Builder anh&#xe4;ngen">
 <richcontent TYPE="NOTE"><html>
-  <head>
+  <head/>
-    
-  </head>
   <body>
     <p>
       ...das liegt daran, da&#223; ich das Bauen von Executables und Libraries und Plugins bereits hochgradig customised habe, im LumieraEnvironment. Das bedeutet, es gibt bereits einen env.Install()-Aufruf, tief in Lumiera-spezifischem Framework-Code. Genau diesen Aufruf mu&#223; ich nun so modifizieren, da&#223; entweder davor oder danach noch die Permissions ge&#228;ndert werden.
     </p>
   </body>
-</html>
+</html></richcontent>
-</richcontent>
 <icon BUILTIN="messagebox_warning"/>
 <node CREATED="1764015955453" ID="ID_1951962763" MODIFIED="1764015978509" TEXT="Scons-Doku gelesen &#x27f6; Command() - Builder"/>
 <node BACKGROUND_COLOR="#accdc3" COLOR="#3f4015" CREATED="1764015979351" ID="ID_422855763" MODIFIED="1764024157666" TEXT="SO.ai gefragt">
 <richcontent TYPE="NOTE"><html>
-  <head>
+  <head/>
-    
-  </head>
   <body>
     <p http-equiv="content-type" content="text/html; charset=utf-8">
       Use one of these approaches: <strong>chain actions in a single <code>Command</code></strong>, or <strong>install first then attach a post-action</strong>&#160;(via <code>AddPostAction</code>&#160; or <code>Command</code>&#160;on the installed node). Both keep the install and chmod as a single build step.
@@ -178836,21 +178856,17 @@ env.Chmod(installed[0], 0o644)</code></pre>
       </li>
     </ul>
   </body>
-</html>
+</html></richcontent>
-</richcontent>
 <icon BUILTIN="wizard"/>
 <node CREATED="1764016178264" ID="ID_1731622448" MODIFIED="1764016223910" TEXT="demnach kann man also den Install()-builder im Command-Builder verwenden">
 <richcontent TYPE="NOTE"><html>
-  <head>
+  <head/>
-    
-  </head>
   <body>
     <p>
       das w&#228;re sch&#246;n ... demnach ist ja SCons wirklich so generisch, wie ich gehofft hatte
     </p>
   </body>
-</html>
+</html></richcontent>
-</richcontent>
 </node>
 <node CREATED="1764016225657" ID="ID_784807828" MODIFIED="1764016244566" TEXT="Alternativ-Vorschlag: eine Post-Action verwenden..."/>
 </node>
@@ -178859,40 +178875,31 @@ env.Chmod(installed[0], 0o644)</code></pre>
 <node CREATED="1764024209743" ID="ID_1027667828" MODIFIED="1764024236064" TEXT="im WrappedStanardBuilder wird bereits ein installTarget() aufgerufen"/>
 <node CREATED="1764024237068" ID="ID_1299073151" MODIFIED="1764024329477">
 <richcontent TYPE="NODE"><html>
-  <head>
+  <head/>
-    
-  </head>
   <body>
     <p>
       die entsprechende Methode hanhabt einen Builder-Parameter <font face="Monospaced" color="#2234d8">install=True</font>
     </p>
   </body>
-</html>
+</html></richcontent>
-</richcontent>
 <richcontent TYPE="NOTE"><html>
-  <head>
+  <head/>
-    
-  </head>
   <body>
     <p>
       ...den habe ich wohl so eingebaut, damit dieser Umstand auch deklarativ sichtbar wird; zudem gibt es Build-Resultate, die nicht installiert werden (z.B. Tests)
     </p>
   </body>
-</html>
+</html></richcontent>
-</richcontent>
 </node>
 <node CREATED="1764024334534" ID="ID_928823167" MODIFIED="1764032036570" TEXT="dann mu&#xdf; man eben im OO-Stil die installTarget() dekorieren">
 <richcontent TYPE="NOTE"><html>
-  <head>
+  <head/>
-    
-  </head>
   <body>
     <p>
       Es ist klar wie das geht, ich empfinde es aber nach heutigen Standards nicht mehr als besonders sch&#246;n, aber praktisch, da das hier ein letztlich in sich geschlossenes &#214;kosystem ist
     </p>
   </body>
-</html>
+</html></richcontent>
-</richcontent>
 </node>
 <node CREATED="1764032050729" ID="ID_465246857" MODIFIED="1764032087052" TEXT="plattform-independent...">
 <linktarget COLOR="#a9b4c1" DESTINATION="ID_465246857" ENDARROW="Default" ENDINCLINATION="-142;0;" ID="Arrow_ID_1435910489" SOURCE="ID_1857294299" STARTARROW="None" STARTINCLINATION="329;21;"/>
@@ -178901,9 +178908,7 @@ env.Chmod(installed[0], 0o644)</code></pre>
 </node>
 <node COLOR="#5b280f" CREATED="1764025095238" ID="ID_445688912" MODIFIED="1764025132369" TEXT="aber wohl erst in SCons 4.10">
 <richcontent TYPE="NOTE"><html>
-  <head>
+  <head/>
-    
-  </head>
   <body>
     <p>
       Debian/Trixie hat 4.8
@@ -178920,16 +178925,13 @@ env.Chmod(installed[0], 0o644)</code></pre>
 <node COLOR="#435e98" CREATED="1764027872597" ID="ID_1632098912" MODIFIED="1764031953974" TEXT="Verbesserungen">
 <node COLOR="#5b280f" CREATED="1764027876810" ID="ID_1482699238" MODIFIED="1764031570047" TEXT="das Action-Objekt nur einmal erzeugen">
 <richcontent TYPE="NOTE"><html>
-  <head>
+  <head/>
-    
-  </head>
   <body>
     <p>
       Nein. Macht den Code viel komplexer und steht in keinem Verh&#228;ltnis zum Nutzen, denn die paar Library-Builder invocations werden uns nicht umbringen
     </p>
   </body>
-</html>
+</html></richcontent>
-</richcontent>
 <icon BUILTIN="button_cancel"/>
 </node>
 <node COLOR="#338800" CREATED="1764027885341" ID="ID_1890347220" MODIFIED="1764031938411" TEXT="eine klarere Meldung ausgeben">
@@ -178984,17 +178986,15 @@ env.Chmod(installed[0], 0o644)</code></pre>
 </node>
 <node BACKGROUND_COLOR="#fdfdcf" COLOR="#ff0000" CREATED="1764032703964" ID="ID_765634393" MODIFIED="1764032782082" TEXT="TICKET #965 hab ich mit Trixie gel&#xf6;st">
 <richcontent TYPE="NOTE"><html>
-  <head>
+  <head/>
-    
-  </head>
   <body>
     <p>
       ...aber derzeit l&#228;uft unser Trac nicht, und ich kann nicht auf das Ticket zugreifen. Hab die Zeile mit dem Workaround einfach wieder rausgenommen
     </p>
   </body>
-</html>
+</html></richcontent>
-</richcontent>
 <icon BUILTIN="bell"/>
+<node CREATED="1764033581168" ID="ID_381618987" MODIFIED="1764033597076" TEXT="24.11.25"/>
 </node>
 </node>
 <node CREATED="1447978374453" HGAP="140" ID="ID_156552320" MODIFIED="1742180980658" TEXT="Compiler" VSHIFT="-10">
@@ -181470,8 +181470,7 @@ env.Chmod(installed[0], 0o644)</code></pre>
       <font face="Monospaced">ARCHFLAGS=&quot; -fstack-protector-strong&quot;</font>
     </p>
   </body>
-</html>
+</html></richcontent>
-</richcontent>
 </node>
 </node>
 <node CREATED="1762997171048" ID="ID_1055108179" MODIFIED="1762997177026" TEXT="Feinschliff + Test">