documentation/poky-ref-manual: Enabling recipes with commercial license requirements

I created a new section in the "Technical Details" chapter of
the YP Reference Manual to deal with licensing.  I migrated the
existing section on tracking licenses from the "Extending YP"
chapter into this section.  The new section now includes that info
as well as the new information here.

Fixes [YOCTO #576]

(From yocto-docs rev: b0d04bf99838d64e71ccd43d587d6641aaa26038)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

2 files changed, 160 insertions, 107 deletions

diff --git a/documentation/poky-ref-manual/extendpoky.xml b/documentation/poky-ref-manual/extendpoky.xml
index f88e2a1..56b806d 100644
--- a/documentation/poky-ref-manual/extendpoky.xml
+++ b/documentation/poky-ref-manual/extendpoky.xml
@@ -9,8 +9,7 @@
         software packages, extending or customizing images or porting the Yocto Project to
         new hardware (adding a new machine). 
         The chapter also describes ways to modify package source code, combine multiple 
-        versions of library files into a single image, track license changes, and handle
-        a package name alias.
+        versions of library files into a single image, and handle a package name alias.
         Finally, the chapter contains advice about how to make changes to the 
         Yocto Project to achieve the best results.
     </para>
@@ -919,111 +918,6 @@
         </section> 
     </section>
 
-    <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
-        <title>Tracking License Changes</title>
-
-        <para>
-            The license of an upstream project might change in the future. In order to prevent these changes
-            going unnoticed, the Yocto Project provides a 
-            <filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></filename>
-            variable to track changes to the license text. The checksums are validated at the end of the
-            configure step, and if the checksums do not match, the build will fail.
-        </para>
-
-        <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
-            <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
-
-            <para>
-                The <filename>LIC_FILES_CHKSUM</filename>
-                variable contains checksums of the license text in the source code for the recipe.
-                Following is an example of how to specify <filename>LIC_FILES_CHKSUM</filename>:
-                <literallayout class='monospaced'>
-     LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
-                         file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
-                         file://licfile2.txt;endline=50;md5=zzzz \
-                         ..."
-                </literallayout>
-            </para>
-
-            <para>
-                The Yocto Project uses the 
-                <filename><link linkend='var-S'>S</link></filename> variable as the 
-                default directory used when searching files listed in 
-                <filename>LIC_FILES_CHKSUM</filename>.
-                The previous example employs the default directory.
-            </para>
-
-            <para>
-                You can also use relative paths as shown in the following example: 
-                <literallayout class='monospaced'>
-     LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\
-                                         md5=bb14ed3c4cda583abc85401304b5cd4e"
-     LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
-                </literallayout>
-            </para>
-
-            <para>
-                In this example, the first line locates a file in 
-                <filename><link linkend='var-S'>S</link>/src/ls.c</filename>. 
-                The second line refers to a file in 
-                <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, which is the parent
-                of <filename>S</filename>.
-            </para>
-            <para>
-                Note that this variable is mandatory for all recipes, unless the 
-                <filename>LICENSE</filename> variable is set to "CLOSED".
-            </para>
-        </section>
-
-        <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
-            <title>Explanation of Syntax</title>
-            <para>
-                As mentioned in the previous section, the 
-                <filename>LIC_FILES_CHKSUM</filename> variable lists all the 
-                important files that contain the license text for the source code. 
-                It is possible to specify a checksum for an entire file, or a specific section of a
-                file (specified by beginning and ending line numbers with the "beginline" and "endline"
-                parameters, respectively). 
-                The latter is useful for source files with a license notice header,
-                README documents, and so forth.
-                If you do not use the "beginline" parameter, then it is assumed that the text begins on the 
-                first line of the file. 
-                Similarly, if you do not use the "endline" parameter, it is assumed that the license text 
-                ends with the last line of the file. 
-            </para>
-
-            <para>
-                The "md5" parameter stores the md5 checksum of the license text. 
-                If the license text changes in any way as compared to this parameter
-                then a mismatch occurs.
-                This mismatch triggers a build failure and notifies the developer.
-                Notification allows the developer to review and address the license text changes.
-                Also note that if a mismatch occurs during the build, the correct md5 
-                checksum is placed in the build log and can be easily copied to the recipe.
-            </para>
-
-            <para>
-                There is no limit to how many files you can specify using the 
-                <filename>LIC_FILES_CHKSUM</filename> variable.
-                Generally, however, every project requires a few specifications for license tracking. 
-                Many projects have a "COPYING" file that stores the license information for all the source 
-                code files.
-                This practice allows you to just track the "COPYING" file as long as it is kept up to date. 
-            </para>
-
-            <tip>
-                If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match 
-                error and displays the correct "md5" parameter value during the build. 
-                The correct parameter is also captured in the build log. 
-            </tip>
-
-            <tip>
-                If the whole file contains only license text, you do not need to use the "beginline" and 
-                "endline" parameters. 
-            </tip>
-        </section>
-    </section>
-
     <section id="usingpoky-configuring-DISTRO_PN_ALIAS">
         <title>Handling a Package Name Alias</title>
         <para>
diff --git a/documentation/poky-ref-manual/technical-details.xml b/documentation/poky-ref-manual/technical-details.xml
index 9e40a66..965d967 100644
--- a/documentation/poky-ref-manual/technical-details.xml
+++ b/documentation/poky-ref-manual/technical-details.xml
@@ -568,6 +568,165 @@
     </section>
 </section>
 
+<section id="licenses">
+    <title>Licenses</title>
+
+    <para>
+        This section describes the mechanism by which the Yocto Project build system 
+        tracks changes to licensing text.
+        The section also describes how to enable commercially licensed receipes, 
+        which by default are disabled.
+    </para>
+
+    <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
+        <title>Tracking License Changes</title>
+
+        <para>
+            The license of an upstream project might change in the future. In order to prevent these changes
+            going unnoticed, the Yocto Project provides a 
+            <filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></filename>
+            variable to track changes to the license text. The checksums are validated at the end of the
+            configure step, and if the checksums do not match, the build will fail.
+        </para>
+
+        <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
+            <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
+
+            <para>
+                The <filename>LIC_FILES_CHKSUM</filename>
+                variable contains checksums of the license text in the source code for the recipe.
+                Following is an example of how to specify <filename>LIC_FILES_CHKSUM</filename>:
+                <literallayout class='monospaced'>
+     LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
+                         file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
+                         file://licfile2.txt;endline=50;md5=zzzz \
+                         ..."
+                </literallayout>
+            </para>
+
+            <para>
+                The Yocto Project uses the 
+                <filename><link linkend='var-S'>S</link></filename> variable as the 
+                default directory used when searching files listed in 
+                <filename>LIC_FILES_CHKSUM</filename>.
+                The previous example employs the default directory.
+            </para>
+
+            <para>
+                You can also use relative paths as shown in the following example: 
+                <literallayout class='monospaced'>
+     LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\
+                                         md5=bb14ed3c4cda583abc85401304b5cd4e"
+     LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
+                </literallayout>
+            </para>
+
+            <para>
+                In this example, the first line locates a file in 
+                <filename><link linkend='var-S'>S</link>/src/ls.c</filename>. 
+                The second line refers to a file in 
+                <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, which is the parent
+                of <filename>S</filename>.
+            </para>
+            <para>
+                Note that this variable is mandatory for all recipes, unless the 
+                <filename>LICENSE</filename> variable is set to "CLOSED".
+            </para>
+        </section>
+
+        <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
+            <title>Explanation of Syntax</title>
+            <para>
+                As mentioned in the previous section, the 
+                <filename>LIC_FILES_CHKSUM</filename> variable lists all the 
+                important files that contain the license text for the source code. 
+                It is possible to specify a checksum for an entire file, or a specific section of a
+                file (specified by beginning and ending line numbers with the "beginline" and "endline"
+                parameters, respectively). 
+                The latter is useful for source files with a license notice header,
+                README documents, and so forth.
+                If you do not use the "beginline" parameter, then it is assumed that the text begins on the 
+                first line of the file. 
+                Similarly, if you do not use the "endline" parameter, it is assumed that the license text 
+                ends with the last line of the file. 
+            </para>
+
+            <para>
+                The "md5" parameter stores the md5 checksum of the license text. 
+                If the license text changes in any way as compared to this parameter
+                then a mismatch occurs.
+                This mismatch triggers a build failure and notifies the developer.
+                Notification allows the developer to review and address the license text changes.
+                Also note that if a mismatch occurs during the build, the correct md5 
+                checksum is placed in the build log and can be easily copied to the recipe.
+            </para>
+
+            <para>
+                There is no limit to how many files you can specify using the 
+                <filename>LIC_FILES_CHKSUM</filename> variable.
+                Generally, however, every project requires a few specifications for license tracking. 
+                Many projects have a "COPYING" file that stores the license information for all the source 
+                code files.
+                This practice allows you to just track the "COPYING" file as long as it is kept up to date. 
+            </para>
+
+            <tip>
+                If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match 
+                error and displays the correct "md5" parameter value during the build. 
+                The correct parameter is also captured in the build log. 
+            </tip>
+
+            <tip>
+                If the whole file contains only license text, you do not need to use the "beginline" and 
+                "endline" parameters. 
+            </tip>
+        </section>
+    </section>
+
+    <section id="enabling-commercially-licensed-recipes">
+        <title>Enabling Commercially Licensed Recipes</title>
+
+        <para>
+            By default, the Yocto Project build system disables components that 
+            have commercial licensing requirements.
+            The following four statements in the
+            <filename>$HOME/poky/meta/conf/distro/poky.conf</filename> file
+            disable components:
+            <literallayout class='monospaced'>
+     COMMERCIAL_LICENSE ?= "lame gst-fluendo-mp3 libmad mpeg2dec ffmpeg qmmp"
+     COMMERCIAL_AUDIO_PLUGINS ?= ""
+     COMMERCIAL_VIDEO_PLUGINS ?= ""
+     COMMERCIAL_QT ?= "qmmp"
+            </literallayout>
+        </para> 
+
+        <para>
+            If you want to enable these components, you can do so by making sure you have
+            the following statements in the configuration file:
+            <literallayout class='monospaced'>
+     COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
+        gst-plugins-ugly-mpegaudioparse"
+     COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
+        gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
+     COMMERCIAL_LICENSE = ""
+     COMMERCIAL_QT = ""
+            </literallayout>
+        </para>
+
+        <para>
+            Excluding a package name from the 
+            <filename>COMMERCIAL_LICENSE</filename> or 
+            <filename>COMMERCIAL_QT</filename> statement enables that package.  
+        </para>
+
+        <para>
+            Specifying audio and video plug-ins as part of the 
+            <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and 
+            <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements includes 
+            the plug-ins into built images - thus adding support for media formats.
+        </para>
+    </section>
+</section>
 </chapter>
 <!-- 
 vim: expandtab tw=80 ts=4