2 files changed, 57 insertions, 11 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 0f006c790d..e0db037454 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -9977,6 +9977,25 @@
                 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>
@@ -9986,15 +10005,6 @@
                 of the license information with source as defined by the GPL
                 and other open source licenses.
             </para>
-
-            <para>
-                See the
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></ulink>,
-                <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>
-                variable descriptions for more information.
-            </para>
         </section>
 
         <section id='providing-compilation-scripts-and-source-code-modifications'>
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index f752856b9d..53bc544b5b 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -2348,7 +2348,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>
@@ -2363,7 +2376,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>
@@ -7159,6 +7185,16 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     <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>