From adebd9f9bca496510bf5631f62eb16d283f1d728 Mon Sep 17 00:00:00 2001 From: Alexander Kanavin Date: Wed, 11 Dec 2024 14:46:15 +0100 Subject: [PATCH] bitbake: bitbake-user-manual-metadata: add a section about 'addfragments` (Bitbake rev: 47e4645da582daa8f3e818ba98e9652c2dcf202f) Signed-off-by: Alexander Kanavin Signed-off-by: Richard Purdie --- .../bitbake-user-manual-metadata.rst | 48 ++++++++++++++++++- 1 file changed, 47 insertions(+), 1 deletion(-) diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst index 40a0c6f02d..75930fef82 100644 --- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst @@ -754,7 +754,9 @@ share the task. This section presents the mechanisms BitBake provides to allow you to share functionality between recipes. Specifically, the mechanisms include ``include``, ``inherit``, :term:`INHERIT`, and ``require`` -directives. +directives. There is also a higher-level abstraction called +``configuration fragments`` that is enabled with ``addfragments`` +directive. Locating Include and Class Files -------------------------------- @@ -962,6 +964,50 @@ the ``autotools`` and ``pkgconfig`` classes:: INHERIT += "autotools pkgconfig" +``addfragments`` Directive +-------------------------- + +This directive allows fine-tuning local configurations with configuration +snippets contained in layers in a structured, controlled way. Typically it would +go into ``bitbake.conf``, for example:: + + addfragments conf/fragments OE_FRAGMENTS OE_FRAGMENTS_METADATA_VARS + +``addfragments`` takes three parameters: + +- path prefix for fragment files inside the layer file tree that bitbake +uses to construct full paths to the fragment files + +- name of variable that holds the list of enabled fragments in an +active build + +- name of variable that contains a list of variable names containing +fragment-specific metadata (such as descriptions) + +This allows listing enabled configuration fragments in ``OE_FRAGMENTS`` +variable like this:: + + OE_FRAGMENTS = "core/domain/somefragment core/someotherfragment anotherlayer/anotherdomain/anotherfragment" + +Fragment names listed in this variable must be prefixed by the layer name +where a fragment file is located, defined by :term:`BBFILE_COLLECTIONS` in ``layer.conf``. + +The implementation then expands this list into +:ref:`require ` +directives with full paths to respective layers:: + + require /path/to/core-layer/conf/fragments/domain/somefragment.conf + require /path/to/core-layer/conf/fragments/someotherfragment.conf + require /path/to/another-layer/conf/fragments/anotherdomain/anotherfragment.conf + +The variable containing a list of fragment metadata variables could look like this:: + + OE_FRAGMENTS_METADATA_VARS = "BB_CONF_FRAGMENT_SUMMARY BB_CONF_FRAGMENT_DESCRIPTION" + +The implementation will add a flag containing the fragment name to each of those variables +when parsing fragments, so that the variables are namespaced by fragment name, and do not override +each other when several fragments are enabled. + Functions =========