[PATCH] manuals: document LICENSE_FLAGS_DETAILS

[michael.opdenacker@bootlin.com]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

From: Ross Burton <ross.burton@arm.com>

Signed-off-by: Ross Burton <ross.burton@arm.com>
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
CC: Quentin Schulz <foss+yocto@0leil.net>
---
 documentation/dev-manual/licenses.rst           |  7 +++++++
 .../migration-guides/release-notes-4.3.rst      |  5 ++++-
 documentation/ref-manual/variables.rst          | 17 +++++++++++++++++
 3 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/documentation/dev-manual/licenses.rst b/documentation/dev-manual/licenses.rst
index 9629dc5329..e62a3c501f 100644
--- a/documentation/dev-manual/licenses.rst
+++ b/documentation/dev-manual/licenses.rst
@@ -123,6 +123,13 @@ name and version (after variable expansion)::
 
    LICENSE_FLAGS = "license_${PN}_${PV}"
 
+It is possible to give more details about a specific license
+using flags on the :term:`LICENSE_FLAGS_DETAILS` variable::
+
+   LICENSE_FLAGS_DETAILS[my-eula-license] = "\nFor further details, see https://example.com/eula."
+
+If set, this will be displayed to the user if the license hasn't been accepted.
+
 In order for a component restricted by a
 :term:`LICENSE_FLAGS` definition to be enabled and included in an image, it
 needs to have a matching entry in the global
diff --git a/documentation/migration-guides/release-notes-4.3.rst b/documentation/migration-guides/release-notes-4.3.rst
index c19cf6e4f9..87cd622743 100644
--- a/documentation/migration-guides/release-notes-4.3.rst
+++ b/documentation/migration-guides/release-notes-4.3.rst
@@ -10,6 +10,8 @@ New Features / Enhancements in 4.3
 
 -  New variables:
 
+   -  :term:`FILE_LAYERNAME`: bitbake now sets this to the name of the layer containing the recipe
+
    -  :term:`FIT_ADDRESS_CELLS` and :term:`UBOOT_FIT_ADDRESS_CELLS`.
       See details below.
 
@@ -17,7 +19,8 @@ New Features / Enhancements in 4.3
 
    -  :term:`KERNEL_DTBVENDORED`: whether to keep vendor subdirectories.
 
-   -  :term:`FILE_LAYERNAME`: bitbake now sets this to the name of the layer containing the recipe
+   -  :term:`LICENSE_FLAGS_DETAILS`: add extra details about a recipe license
+      in case it is not allowed by :term:`LICENSE_FLAGS_ACCEPTED`.
 
 - Layername functionality available through overrides
 
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 7a71abc0ae..71c02a8510 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -4968,6 +4968,23 @@ system and gives an overview of their function and contents.
       ":ref:`dev-manual/licenses:enabling commercially licensed recipes`"
       section in the Yocto Project Development Tasks Manual.
 
+   :term:`LICENSE_FLAGS_DETAILS`
+      Adds details about a flag in :term:`LICENSE_FLAGS`. This way,
+      if such a flag is not accepted through :term:`LICENSE_FLAGS_ACCEPTED`,
+      the error message will be more informative, containing the specified
+      extra details.
+
+      For example, a recipe with an EULA may set::
+
+         LICENSE_FLAGS = "FooBar-EULA"
+         LICENSE_FLAGS_DETAILS[FooBar-EULA] = "\nFor further details, see https://example.com/eula."
+
+      If ``Foobar-EULA`` isn't in :term:`LICENSE_FLAGS_ACCEPTED`, the
+      error message is more useful::
+
+        Has a restricted license 'FooBar-EULA' which is not listed in your LICENSE_FLAGS_ACCEPTED.
+        For further details, see https://example.com/eula.
+
    :term:`LICENSE_PATH`
       Path to additional licenses used during the build. By default, the
       OpenEmbedded build system uses :term:`COMMON_LICENSE_DIR` to define the
-- 
2.34.1