dev-manual, ref-manual: Updated licensing text information.

Fixes [YOCTO #8634]

To clear up the behavior the COPY_LIC_DIRS, COPY_LIC_MANIFEST,
and LICENSE_CREATE_PACKAGE variable behaviors, I updated the
glossary descriptions of the variables.  Also, added more info
to the "Providing License Text" section in the dev-manual.  Tied
everything together with good referencing.

(From yocto-docs rev: d1f8fb672aeba8b163cc79d5043e6ffcddc9db25)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

2 files changed, 93 insertions, 2 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index f0836e8b1d..eaf840d4d1 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -9941,6 +9941,28 @@
                 Adding these statements to the configuration file ensures
                 that the licenses collected during package generation
                 are included on your image.
+                <note>
+                    <para>Setting all three variables to "1" results in the
+                    image having two copies of the same license file.
+                    One copy resides in
+                    <filename>/usr/share/common-licenses</filename> and
+                    the other resides in
+                    <filename>/usr/share/license</filename>.</para>
+
+                    <para>The reason for this behavior is because
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></ulink>
+                    and
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></ulink>
+                    add a copy of the license when the image is built but do not
+                    offer a path for adding licenses for newly installed packages
+                    to an image.
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></ulink>
+                    adds a separate package and an upgrade path for adding
+                    licenses to an image.</para>
+                </note>
+            </para>
+
+            <para>
                 As the source archiver has already archived the original
                 unmodified source that contains the license files,
                 you would have already met the requirements for inclusion
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 0b2c426b68..3d68dd6ac2 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -2354,7 +2354,20 @@
                     <filename>/usr/share/common-licenses</filename>,
                     for each package.
                     The license files are placed
-                    in directories within the image itself.
+                    in directories within the image itself during build time.
+                    <note>
+                        The <filename>COPY_LIC_DIRS</filename> does not
+                        offer a path for adding licenses for newly installed
+                        packages to an image, which might be most suitable
+                        for read-only filesystems that cannot be upgraded.
+                        See the
+                        <link linkend='var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></link>
+                        variable for additional information.
+                        You can also reference the
+                        "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"
+                        section in the Yocto Project Development Manual for
+                        information on providing license text.
+                    </note>
                 </para>
             </glossdef>
         </glossentry>
@@ -2369,7 +2382,20 @@
                     If set to "1", the OpenEmbedded build system copies
                     the license manifest for the image to
                     <filename>/usr/share/common-licenses/license.manifest</filename>
-                    within the image itself.
+                    within the image itself during build time.
+                    <note>
+                        The <filename>COPY_LIC_MANIFEST</filename> does not
+                        offer a path for adding licenses for newly installed
+                        packages to an image, which might be most suitable
+                        for read-only filesystems that cannot be upgraded.
+                        See the
+                        <link linkend='var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></link>
+                        variable for additional information.
+                        You can also reference the
+                        "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"
+                        section in the Yocto Project Development Manual for
+                        information on providing license text.
+                    </note>
                 </para>
             </glossdef>
         </glossentry>
@@ -7179,6 +7205,49 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-LICENSE_CREATE_PACKAGE'><glossterm>LICENSE_CREATE_PACKAGE</glossterm>
+            <info>
+                LICENSE_CREATE_PACKAGE[doc] = "Creates an extra package (i.e. ${PN}-lic) for each recipe and adds that package to the RRECOMMENDS+${PN}."
+            </info>
+            <glossdef>
+                <para role="glossdeffirst">
+<!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+                        Setting <filename>LICENSE_CREATE_PACKAGE</filename>
+                        to "1" causes the OpenEmbedded build system to create
+                        an extra package (i.e.
+                        <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-lic</filename>)
+                        for each recipe and to add those packages to the
+                        <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link><filename>_${PN}</filename>.
+                </para>
+
+                <para>
+                    The <filename>${PN}-lic</filename> package installs a
+                    directory in <filename>/usr/share/licenses</filename>
+                    named <filename>${PN}</filename>, which is the recipe's
+                    base name, and installs files in that directory that
+                    contain license and copyright information (i.e. copies of
+                    the appropriate license files from
+                    <filename>meta/common-licenses</filename> that match the
+                    licenses specified in the
+                    <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
+                    variable of the recipe metadata and copies of files marked
+                    in
+                    <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>
+                    as containing license text).
+                </para>
+
+                <para>
+                    For related information on providing license text, see the
+                    <link linkend='var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></link>
+                    variable, the
+                    <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
+                    variable, and the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"
+                    section in the Yocto Project Development Manual.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-LICENSE_FLAGS'><glossterm>LICENSE_FLAGS</glossterm>
             <info>
                 LICENSE_FLAGS[doc] = "Specifies additional flags for a recipe you must whitelist through LICENSE_FLAGS_WHITELIST in order to allow the recipe to be built."