4.8. Layers in PTXdist¶
For better maintenance or other reasons, a PTXdist project can be split into multiple layers. Each layer has exactly the same directory hierarchy as described in PTXdist’s Directory Hierarchy and other chapters.
All layers are explicitly stacked in the filesystem. The top layer is the
workspace of the PTXdist project. Any
selected_* links and the platform
build directory are created here. The layer below is defined by the
subdirectory or symlink named
base/. More can be stacked the same
base/base/ is the third layer and so on.
In many ways, PTXdist itself can be considered as the bottom layer. This is
either implicit or explicit with one last
A project can overwrite files provided by PTXdist in many different ways, e.g. rule files or files installed with install_alternative etc. This concept expands naturally to layers. Each layer can overwrite files provided by lower layers in the exact same way. Any files are always searched for in a strict layer by layer order.
Writing Layer Aware Rules¶
For the most part, package rules work just as expected when multiple layers are used. Any layer specific handling is done implicitly by PTXdist. However, there are a few things that need special handling.
The variables PTXDIST_WORKSPACE and PTXDIST_PLATFORMCONFIGDIR always refer to the directories in the top layer. These variables might be used in rules files like this:
MY_KERNEL_CONFIG := $(PTXDIST_PLATFORMCONFIGDIR)/kernelconfig.special
If the referenced file is in any layer but the top one then it will not be found. To handle use-cases like this, the macros ptx/in-path and ptx/in-platformconfigdir can be used:
MY_KERNEL_CONFIG := $(call ptx/in-platformconfigdir, kernelconfig.special)
This way, the layers are searched top to bottom until the config file is found.
PTXdist Config Files with Multiple Layers¶
In many cases a layer may want to modify the ptxconfig by enabling or disabling some options. Any changes must be propagated through the whole layer stack.
The features and workflow described here apply to the ptxconfig, the platformconfig and any collectionconfig used in the project.
To do this, PTXdist stores a delta config to the layer below and a full config file in each layer. If the two files are missing then the config is unchanged. The bottom layer has only the config file and no delta.
At runtime, PTXdist will always use the full config file in the top layer where the config exists. Before doing so, it will ensure that the config is consistent across all layers. This means that, for any layer that contains a delta config, the full config file of the layer below has not changed since the delta config was last updated. If any inconsistency is detected, PTXdist will abort.
For any command that modifies the config file, except
PTXdist will use kconfig implicitly on all layers to check if the config
for this layer is up to date. This is a stricter check than the consistency
validation. For example, if a new package was added to a layer without
updating the ptxconfig then this will be detected and PTXdist will
abort. If all other layers are up to date, then PTXdist will use the delta
config of the top layer, apply it to the full config of the layer below
and execute the specified command with the resulting config file.
If the config file does not exist yet on the top layer, then it
will be created if changes to the config are made. Similarly the config
will be deleted if the delta is empty after the changes. In either case
it may be necessary to update any
selected_* link to point to the
If PTXdist detects an inconsistency or an out of date config file then it
must be updated before they can be used. This can be done by using the
oldconfig command. In this special case, PTXdist will iterate from the
bottom to the top layer and run
oldconfig for each of them. It will
use the delta config applied to the full config of the layer below at each
step. This means that it’s possible to enable or disable an option in the
bottom layer and
oldconfig will propagate this change to all other
Packages with kconfig Based Config Files¶
For packages such as the Linux kernel that have kconfig based config files,
a lot of the infrastructure to handle config files and deltas across
multiple layers can be reused (see Kconfig Diffs).
Consistency validation is done implicitly
menuconfig and other kconfig commands will use config files and
deltas as expected.
It’s not possible to implicitly run
oldconfig on other layers (this may
require a different source tree for the packages), so any inconsistencies
must be resolved manually by running
oldconfig explicitly on each
The make macros that provide these features are currently used by the barebox and kernel packages and templates.