manuals: document LICENSE_FLAGS_DETAILS

(From yocto-docs rev: 299c9b295a8476abdb32fba01ac2f45efacea6f1)

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>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

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] = "For 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

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
 

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] = "For 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