From 35655863cad0ebcb78001bafd781e212bdffe4bc Mon Sep 17 00:00:00 2001
From: Scott Rifenbark <scott.m.rifenbark@intel.com>
Date: Tue, 13 Aug 2013 14:43:52 +0300
Subject: ref-manual: Review comments added, new variables added

* Updated some links in the insane.bbclass sectioni so they
  now point to some new variables.

* Added glossary descriptions for PKGD, PKGDEST, and
  INCOMPATIBLE_LICENSE.

* Added a paragraph to the LICENSE variable to describe
  situations where the output might have components whose
  licensing is from two different licenses (licensing on
  a per-package basis).

(From yocto-docs rev: b8dd3b3d5cb912ed7c5d3c9b6c01d93347e95b84)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 documentation/ref-manual/ref-classes.xml   |  6 +--
 documentation/ref-manual/ref-variables.xml | 75 +++++++++++++++++++++++++++++-
 2 files changed, 77 insertions(+), 4 deletions(-)

(limited to 'documentation')

diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index 42f33e811e..7a5a5ddb58 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -648,7 +648,7 @@
             <listitem><para><emphasis><filename>incompatible-license:</filename></emphasis>
                 Report when packages are excluded from being created due to
                 being marked with a license that is in
-                <filename>INCOMPATIBLE_LICENSE</filename>.
+                <link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link>.
                 </para></listitem>
             <listitem><para><emphasis><filename>compile-host-path:</filename></emphasis>
                 Checks the <filename>do_compile</filename> log for indications
@@ -762,8 +762,8 @@
                 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>,
                 <link linkend='var-D'><filename>D</filename></link>,
                 <link linkend='var-PN'><filename>PN</filename></link>, and
-                <filename>PKGD</filename>) are undefined during
-                <filename>do_package</filename>.
+                <link linkend='var-PKGD'><filename>PKGD</filename></link>) are
+                undefined during <filename>do_package</filename>.
                 </para></listitem>
             <listitem><para><emphasis><filename>pkgv-undefined:</filename></emphasis>
                 Checks to see if the <filename>PKGV</filename> variable
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 7b88ffe5ca..099846412b 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -1727,7 +1727,7 @@ Core layer for images cannot be removed
         <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
             <glossdef>
                 <para>
-                    Specifes the format of the root filesystem created by
+                    Specifies the format of the root filesystem created by
                     the OpenEmbedded build system.
                     Available formats are a subset of the
                     supported images listed in
@@ -2009,6 +2009,33 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-INCOMPATIBLE_LICENSE'><glossterm>INCOMPATIBLE_LICENSE</glossterm>
+            <glossdef>
+                <para>
+                    Specifies a space-separated list of license names
+                    (as they would appear in
+                    <link linkend='var-LICENSE'><filename>LICENSE</filename></link>)
+                    that should be excluded from the build.
+                    Recipes that provide no alternatives to listed incompatible
+                    licenses are not built.
+                    Packages that are individually licensed with the specified
+                    incompatible licenses will be deleted.
+                </para>
+
+                <note>
+                    This functionality is only regularly tested using
+                    the following setting:
+                    <literallayout class='monospaced'>
+     INCOMPATIBLE_LICENSE = "GPLv3"
+                    </literallayout>
+                    Although you can use other settings, you might be required
+                    to remove dependencies on or provide alternatives to
+                    components that are required to produce a functional system
+                    image.
+                </note>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm>INHIBIT_DEFAULT_DEPS</glossterm>
             <glossdef>
                 <para>
@@ -2583,6 +2610,21 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     The final example is from <filename>sysstat</filename>,
                     which presents a single license.
                 </para>
+
+                <para>
+                    You can also specify licenses on a per-package basis to
+                    handle situations where components of the output have
+                    different licenses.
+                    For example, a piece of software whose code is
+                    licensed under GPLv2 but has accompanying documentation
+                    licensed under the GNU Free Documentation License 1.2 could
+                    be specified as follows:
+                    <literallayout class='monospaced'>
+     LICENSE = "GFDL-1.2 &amp; GPLv2"
+     LICENSE_${PN} = "GPLv2"
+     LICENSE_${PN}-doc = "GFDL-1.2"
+                    </literallayout>
+                </para>
             </glossdef>
         </glossentry>
 
@@ -3417,6 +3459,37 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-PKGD'><glossterm>PKGD</glossterm>
+            <glossdef>
+                <para>
+                    Points to the destination directory for files to be
+                    packaged before they are split into individual packages.
+                    This directory defaults to the following:
+                    <literallayout class='monospaced'>
+     ${WORKDIR}/package
+                    </literallayout>
+                    Do not change this default.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PKGDEST'><glossterm>PKGDEST</glossterm>
+            <glossdef>
+                <para>
+                    Points to the parent directory for files to be packaged
+                    after they have been split into individual packages.
+                    This directory defaults to the following:
+                    <literallayout class='monospaced'>
+     ${WORKDIR}/packages-split
+                    </literallayout>
+                    Under this default directory, the build system creates
+                    directories for each package specified in
+                    <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
+                    Do not change this default.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-PN'><glossterm>PN</glossterm>
             <glossdef>
                 <para>This variable can have two separate functions depending on the context: a recipe
-- 
cgit v1.2.3-54-g00ecf