[kirkstone][PATCH 8/8] manuals: document VIRTUAL-RUNTIME variables

michael.opdenacker
2024-03-14T09:14:14Z

Document the convention to use variables prefixed by VIRTUAL_RUNTIME.
Add references to the new term where possible.

Another reason is that such variables are recommended
in a warning issued by meta/classes-global/insane.bbclass

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Reported-by: Tim Orling <ticotimo@gmail.com>
---
documentation/dev-manual/device-manager.rst | 8 ++---
documentation/ref-manual/variables.rst | 37 ++++++++++++++++++---
2 files changed, 36 insertions(+), 9 deletions(-)

diff --git a/documentation/dev-manual/device-manager.rst b/documentation/dev-manual/device-manager.rst
index 0343d19b9c..49fc785fec 100644
--- a/documentation/dev-manual/device-manager.rst
+++ b/documentation/dev-manual/device-manager.rst
@@ -60,10 +60,10 @@ kernel.
All devices created by ``devtmpfs`` will be owned by ``root`` and have
permissions ``0600``.

-To have more control over the device nodes, you can use a device manager
-like ``udev`` or ``busybox-mdev``. You choose the device manager by
-defining the ``VIRTUAL-RUNTIME_dev_manager`` variable in your machine or
-distro configuration file. Alternatively, you can set this variable in
+To have more control over the device nodes, you can use a device manager like
+``udev`` or ``busybox-mdev``. You choose the device manager by defining the
+:term:`VIRTUAL-RUNTIME_dev_manager <VIRTUAL-RUNTIME>` variable in your machine
+or distro configuration file. Alternatively, you can set this variable in
your ``local.conf`` configuration file::

VIRTUAL-RUNTIME_dev_manager = "udev"
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 0f9e114771..ccd1963339 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -6364,11 +6364,11 @@ system and gives an overview of their function and contents.

.. note::

- A corresponding mechanism for virtual runtime dependencies
- (packages) exists. However, the mechanism does not depend on any
- special functionality beyond ordinary variable assignments. For
- example, ``VIRTUAL-RUNTIME_dev_manager`` refers to the package of
- the component that manages the ``/dev`` directory.
+ A corresponding mechanism for virtual runtime dependencies (packages)
+ exists. However, the mechanism does not depend on any special
+ functionality beyond ordinary variable assignments. For example,
+ :term:`VIRTUAL-RUNTIME_dev_manager <VIRTUAL-RUNTIME>` refers to the
+ package of the component that manages the ``/dev`` directory.

Setting the "preferred provider" for runtime dependencies is as
simple as using the following assignment in a configuration file::
@@ -9385,6 +9385,33 @@ system and gives an overview of their function and contents.
Additionally, you should also set the
:term:`USERADD_ERROR_DYNAMIC` variable.

+ :term:`VIRTUAL-RUNTIME`
+ :term:`VIRTUAL-RUNTIME` is a commonly used prefix for defining virtual
+ packages for runtime usage, typically for use in :term:`RDEPENDS`
+ or in image definitions.
+
+ An example is ``VIRTUAL-RUNTIME_base-utils`` that makes it possible
+ to either use BusyBox based utilities::
+
+ VIRTUAL-RUNTIME_base-utils = "busybox"
+
+ or their full featured implementations from GNU Coreutils
+ and other projects::
+
+ VIRTUAL-RUNTIME_base-utils = "packagegroup-core-base-utils"
+
+ Here are two examples using this virtual runtime package. The
+ first one is in :yocto_git:`initramfs-framework_1.0.bb
+ </poky/tree/meta/recipes-core/initrdscripts/initramfs-framework_1.0.bb?h=scarthgap>`::
+
+ RDEPENDS:${PN} += "${VIRTUAL-RUNTIME_base-utils}"
+
+ The second example is in the :yocto_git:`core-image-initramfs-boot
+ </poky/tree/meta/recipes-core/images/core-image-initramfs-boot.bb?h=scarthgap>`
+ image definition::
+
+ PACKAGE_INSTALL = "${INITRAMFS_SCRIPTS} ${VIRTUAL-RUNTIME_base-utils} base-passwd"
+
:term:`VOLATILE_LOG_DIR`
Specifies the persistence of the target's ``/var/log`` directory,
which is used to house postinstall target log files.
--
2.34.1