Linking and Application Structure

When we refer to other definitions by importing headers, these imports should be spelled out precisely to the point. Every relevant facility used in a piece of code must be reflected by the corresponding #import statement, yet there should not be any spurious imports. Ideally, just by reading the prologue of a source file, the reader should gain a clear understanding about the dependencies of this code. The standards are somewhat different for header files, since every user of this header gets these imports too. Each import incurs cost for the user — so the header should mention only those imports

Imports are to be listed in a strict order: always start with our own references, preferably starting with the facility most “on topic”. Besides, for rather fundamental library headers, it is a good idea to start with a very fundamental header, like e.g. lib/error.hpp. Of course, these widely used fundamental headers need to be carefully crafted, since the leverage of any other include pulled in through these headers is high.

Any imports regarding external or system libraries are given in a second block, after our own headers. This discipline opens the possibility for our own headers to configure or modify some system facilities, in case the need arises. It is desirable for headers to be written in a way independent of the include order. But in some, rare cases we need to rely on a specific order of include. In such cases, it is a good idea to encode this specific order right into some very fundamental header, so it gets fixed and settled early in the include processing chain. Our stage/gtk-base.hpp, as used by stage/gtk-lumiera.hpp is a good example.

We need the full definition of an entity whenever we need to know its precise memory layout, be it to allocate space, to pass an argument by-value, or to point into some filed within a struct, array or object. The full definition may be preceded by an arbitrary number of redundant, equivalent declarations. We do not actually need a full definition for any use not dealing with the space or memory layout of an entity. Especially, handling some element by pointer or reference, or spelling out a function signature to take this entity other than by-value, does not require a full definition.

Exploiting this fact allows us largely to reduce the load of dependencies, especially when it comes to “subsystem” or “package” headers, which define the access point to some central facility. Such headers should start with a list of the relevant core entities of this subsystem, but only in the form of “lightweight” forward declarations. Because, anyone actually to use one of these participants, is bound to include the specific header of this element anyway; all other users may safely skip the efforts and transitive dependencies necessary to spell out the full definition of stuff not actually used and needed.

In a similar vein, a façade interface does not actually need to pull in definitions for all the entities it is able to orchestrate. In most cases, it is sufficient to supply suitable and compatible `typedef`s in the public part of the interface, just to the point that we’re able to spell out the bare API function signatures without compilation error.

At the point, where a ctor is actually invoked, we require the full definition of the element about to be created. Consequently, at the place, where the ctor itself is defined (not just declared), the full definition of all the members of a class plus the full definition of all base classes is required. The impact of moving this point down into a single implementation translation unit can be huge, compared to incurring the same cost in each and every other translation unit just using an entity.

Yet there is a flip side of the coin: Whenever the compiler sees the full definition of an entity, it is able to inline operations. And the C++ compiler uses elaborate metrics to judge the feasibility of inlining. Especially when almost all ctor implementations are trivial (which is the case when writing good C++ style code), the runtime impact can be huge, basically boiling down a whole pile of calls and recursive invocations into precisely zero assembler code to be generated. This way, abstraction barriers can evaporate to nothingness. So we’re really dealing with a run time vs. development time and code size tradeoff here.

On a related note: care has to be taken whenever a templated class defines virtual methods. Each instantiation of the template will cause the compiler to emit a function which generates the VTable, together with code for each of the virtual functions. This effect is known as “template code bloat”.

It is is the very nature of a good design pattern, the reason why it is remembered and applied over and over again: to allow otherwise destructive forces to move past each other in a seemingly “friction-less” way. In our case, there is a design pattern known to resolve the high tension and potential conflict inherent to the situations and issues described above. And, in addition, it circumvents the lack of a real interface definition construct in C++ elegantly:

Whenever a facility has to offer an outward façade for the client, while at the same time engaging into heavy weight implementation activities, then you may split this entity into an interface shell and a private implementation delegate.
[the common name for this pattern, »PImpl« means “point-to-implementation”]
The interface part is defined in the header, fully eligible for inlining. It might even be generic — templated to adapt to a wide array of parameter types. The implementation of the API functions is also given inline, and just performs the necessary administrative steps to accept the given parameters, before passing on the calls to the private implementation delegate. This implementation object is managed by (smart) pointer, so all of the dependencies and complexities of the implementation is moved into a single dedicated translation unit, which may even be reshaped and reworked without the need to recompile the usage site.

These constructs serve a similar purpose: To segregate concerns, together with the related dependencies and overhead. They, too, represent some trade-off: a typically very intricate library construct is traded for a lean and flexible construction at usage site.

A wrapper (smart-pointer or smart handle), based on the ability of C++ to invoke ctors and dtors of stack-allocated values and object members automatically, can be used so push some cross-cutting concern into a separate code location, together with all the accompanying management facilities and dependencies, so the actual “business code” remains untainted.

In a related, but somewhat different style, an opaque holder allows to “piggyback” a value without revealing the actual implementation type. When hooked this way behind a strategy interface, extended compounds of implementation facilities can be secluded into a dedicated facility, without incurring dependency overhead or tight coupling or even in-depth knowledge onto the client, yet typesafe and with automatic tracking for clean-up and failure management.

Management of library dependencies can be a tricky subject, both obscure and contentious. There is a natural tension between the application developers (»upstream«), the packagers and distributors. Developers have a natural tendency to cut short on “secondary” concerns in order to keep matters simple. As a developer, you always try to stretch to the limit, and this very tendency limits your ability to care for intricate issues faced by just a few users, or to care for compatibility or even for extended tutorial documentation. So, as an upstream developer, if you know that the stuff you’ve built works just fine with a specific library version — be it bleeding edge or be it outdated and obsoleted since years — the most pragmatic and adequate answer is to demand from your users just to “come along with you” — frankly, the active developer has zero inclination to look back to past issues already overcome in the course of development, nor has he much interest to engage in other fields of ongoing debate not conductive to his own concerns right now. So the best solution for the developer would be just to wrap-up his own system and ship it as a huge bundle to the users. Every other solution seems inferior, just adding weight, efforts and pain without tangible benefit.

Obviously, a distributor can not agree to that stance. To create a coherent and reliable whole out of the thousand individual variations the upstream developers breed, is in itself a herculean task and would simply be impossible without forcing some degree of standardisation onto the developers. In fact, the distributor’s task becomes feasible only by offloading some efforts for compatibility in small portions onto the shoulders of the individual upstream projects. A preference for using a common set of shared libraries is even built into the toolchain, and there is a distinct tendency to discourage and even hide away the mechanisms otherwise available to deal with a self contained bundle of libraries.

Speaking in terms of history, explicit mechanisms to support packaging and distribution management are a rather new phenomenon and tend to conflict with the glorious »Unix Way« of doing things, they are cross-cutting, global and invasive. On Unix systems, traditionally there used to be two overriding mechanisms for library resolution, one for the user, one for the developer:

Based on this situation, the new-style d-tags were designed to implement a different precedence hierarchy. Whenever the new d-tags are enabled,
[the --enable-new-dtags linker flag is default in many current distributions, and especially with the »gold« linker.]
the presence of a DT_RUNPATH tag in the .dynamic section of an ELF binary completely disables the effect of any DT_RPATH. Moreover, the LD_LIBRARY_PATH is automatically disabled, whenever a binary is installed as set-user-ID or set-group-ID — which closes a blatant security loophole.

The use of both RPATH and LD_LIBRARY_PATH is strongly discouraged. Debian policy for example does not explicitly rule out the use of RPATH / RUNPATH, but it is considered bad practice
[a good summary of the situation can be found on this Debian page ]
 — with the exception of using a relative RUNPATH with $ORIGIN to add non-standard library search locations to libraries that are only intended for usage by the given executable or other libraries within the same source package.

In the new system, the precedence order is as follows
[see ld.so manpage on die.net or ld.so manpage ubuntu.com (more recent) ]

All the “search paths” mentioned here are colon separated lists of directories.

To support flexible RUNPATH (and RPATH) settings, the GNU ld.so (also the SUN and Irix linkers) allow the usage of some “magic” tokens in the .dynamic section of ELF binaries (both libraries and executables):

Since the new-style RUNPATH is not extended for resolving transitive dependencies, each library, when relying on relative locations, must provide its own RUNPATH to point at the direct dependencies at a relative location. This solution is a bit more tricky to set up, but in fact more logical and scalable on the long run. Incidentally, it can be quite a challenge to escape the $ORIGIN properly from any shell script or even build system — it is crucial that the linker itself, not the compiler driver, actually gets to “see” the dollar sign, plain, without spurious escapes.

The linker actually needs to see the dependency. Indirect, conceptual dependencies, where the client takes initiative and enrols itself actively with the server, will slip through unnoticed. Under some additional conditions, especially with self-configuring systems, this omission might even cause a whole dependency and subsystem to be disabled.

As a practical example, our C++ unit-tests are organised into test-suites, where the individual test uses a registration mechanism, providing the name of the suite and category tags. This way, the test runner may be started to execute just some category of tests. Now, switching tests to dynamic linking causes an insidious side effect: The registration mechanism uses static initialisation — which is the commonly used mechanism for this kind of tasks in C++. Place a static variable into an anonymous namespace — it will be initialised by the runtime system on start-up, causing any constructor code to run right when it is needed to enrol itself with the global (test) service. Unfortunately, static initialisation of shared objects is performed at load time of the library — which never happens unless the linker has figured out the dependency and added the library to the required set. But the linker won’t be able to see this dependency when building the test-runner, since the client, the individual test-case in the shared library is the one to call into the test-runner, not the other way round. The registration function resides in a common support library, picked as dependency both by the test-runner and the individual test case, but this won’t help us either. So, in this case (and similar cases), we need either to fabricate a “dummy” call into the library holding the clients (tests), or we need to link the test-runner with --no-as-needed — which is the preferred solution, and in fact is what we do.
[see tests/SConscript]

Locating binary dependencies relative to the executable (as described above) gets complicated when several of our own dynamically linked modules depend on each other transitively. For example, a plug-in might depend on liblumieravault.so, which in turn depends on liblumierasupport.so. Now, when we link --as-needed, the linker will add the direct dependency, but omit the transitive dependency on the support library. Which means, at runtime, that we’d need to find the support library when we are about to load the vault layer library. With the typical, external libraries already installed to the system this works, since the linker has built-in “magic” knowledge about the standard installation locations of system libraries. Not so for our own loadable components — recall, the idea was to provide a self-contained directory tree, which can be relocated in the file system as appropriate, without the need to “install” the package officially. The GNU dynamic linker can handle this requirement, though, if we supply an additional, relative search information with the library pulling in the transitive dependency. In our example, liblumieravault.so needs an additional search path to locate liblumierasupport.so relative to the vault layer lib (and not relative to the executable). For this reason, our build system by default supplies such a search hint with every Lumiera lib or dynamic module — assuming that our own shared libraries are installed into a subdirectory modules below the location of the executable; other dynamic modules (plug-ins) may be placed in sibling directories. So, to summarise, our build defines the following RPATH and RUNPATH specs: