overview-manual, dev-manual: Moved licensing how-to stuff to dev-manual

The section on licensing in the overview-manual was really "how-to"
information.  I moved this to a new section in the dev-manual for
"working with licenses".  I fixed some references in the ref-manual and
in the bsp-guide as well.

(From yocto-docs rev: f150a1ea2da900aae88fc5fa60f4115cc213ba2d)

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

1 files changed, 0 insertions, 391 deletions

diff --git a/documentation/overview-manual/overview-manual-concepts.xml b/documentation/overview-manual/overview-manual-concepts.xml
index 9f0f9d1d9f..338a190ae2 100644
--- a/documentation/overview-manual/overview-manual-concepts.xml
+++ b/documentation/overview-manual/overview-manual-concepts.xml
@@ -3226,397 +3226,6 @@
             articles for background information on Pseudo.
         </para>
     </section>
-
-    <section id="overview-licenses">
-        <title>Licenses</title>
-
-        <para>
-            This section describes the mechanism by which the
-            <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
-            tracks changes to licensing text.
-            The section also describes how to enable commercially licensed
-            recipes, which by default are disabled.
-        </para>
-
-        <para>
-            For information that can help you maintain compliance with
-            various open source licensing during the lifecycle of the product,
-            see the
-            "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Project's Lifecycle</ulink>"
-            section in the Yocto Project Development Tasks Manual.
-        </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
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
-                variable tracks 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>
-                    <note><title>Notes</title>
-                        <itemizedlist>
-                            <listitem><para>
-                                When using "beginline" and "endline", realize
-                                that line numbering begins with one and not
-                                zero.
-                                Also, the included lines are inclusive (i.e.
-                                lines five through and including 29 in the
-                                previous example for
-                                <filename>licfile1.txt</filename>).
-                                </para></listitem>
-                            <listitem><para>
-                                When a license check fails, the selected license
-                                text is included as part of the QA message.
-                                Using this output, you can determine the exact
-                                start and finish for the needed license text.
-                                </para></listitem>
-                        </itemizedlist>
-                    </note>
-                </para>
-
-                <para>
-                    The build system uses the
-                    <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
-                    variable as the default directory when searching files
-                    listed in <filename>LIC_FILES_CHKSUM</filename>.
-                    The previous example employs the default directory.
-                </para>
-
-                <para>
-                    Consider this next example:
-                    <literallayout class='monospaced'>
-     LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\
-                                         md5=bb14ed3c4cda583abc85401304b5cd4e"
-     LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
-                    </literallayout>
-                </para>
-
-                <para>
-                    The first line locates a file in
-                    <filename>${S}/src/ls.c</filename> and isolates lines five
-                    through 16 as license text.
-                    The second line refers to a file in
-                    <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>.
-                </para>
-
-                <para>
-                    Note that <filename>LIC_FILES_CHKSUM</filename> 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.
-                    <note><title>Tips</title>
-                        <itemizedlist>
-                            <listitem><para>
-                                If you specify an empty or invalid "md5"
-                                parameter,
-                                <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
-                                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.
-                                </para></listitem>
-                            <listitem><para>
-                                If the whole file contains only license text,
-                                you do not need to use the "beginline" and
-                               "endline" parameters.
-                               </para></listitem>
-                        </itemizedlist>
-                    </note>
-                </para>
-            </section>
-        </section>
-
-        <section id="enabling-commercially-licensed-recipes">
-            <title>Enabling Commercially Licensed Recipes</title>
-
-            <para>
-                By default, the OpenEmbedded build system disables
-                components that have commercial or other special licensing
-                requirements.
-                Such requirements are defined on a
-                recipe-by-recipe basis through the
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
-                variable definition in the affected recipe.
-                For instance, the
-                <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
-                recipe contains the following statement:
-                <literallayout class='monospaced'>
-     LICENSE_FLAGS = "commercial"
-                </literallayout>
-                Here is a slightly more complicated example that contains both
-                an explicit recipe name and version (after variable expansion):
-                <literallayout class='monospaced'>
-     LICENSE_FLAGS = "license_${PN}_${PV}"
-                </literallayout>
-                    In order for a component restricted by a
-                <filename>LICENSE_FLAGS</filename> definition to be enabled and
-                included in an image, it needs to have a matching entry in the
-                global
-                    <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>
-                variable, which is a variable typically defined in your
-                <filename>local.conf</filename> file.
-                For example, to enable the
-                <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
-                    package, you could add either the string
-                    "commercial_gst-plugins-ugly" or the more general string
-                    "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>.
-                See the
-                "<link linkend='license-flag-matching'>License Flag Matching</link>"
-                section for a full
-                explanation of how <filename>LICENSE_FLAGS</filename> matching
-                works.
-                Here is the example:
-                <literallayout class='monospaced'>
-     LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
-                </literallayout>
-                    Likewise, to additionally enable the package built from the
-                recipe containing
-                    <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>,
-                and assuming that the actual recipe name was
-                <filename>emgd_1.10.bb</filename>, the following string would
-                enable that package as well as the original
-                <filename>gst-plugins-ugly</filename> package:
-                <literallayout class='monospaced'>
-     LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
-                </literallayout>
-                    As a convenience, you do not need to specify the complete
-                license string in the whitelist for every package.
-                You can use an abbreviated form, which consists
-                of just the first portion or portions of the license
-                string before the initial underscore character or characters.
-                A partial string will match any license that contains the
-                given string as the first portion of its license.
-                For example, the following whitelist string will also match
-                both of the packages previously mentioned as well as any other
-                packages that have licenses starting with "commercial" or
-                "license".
-                <literallayout class='monospaced'>
-     LICENSE_FLAGS_WHITELIST = "commercial license"
-                </literallayout>
-            </para>
-
-            <section id="license-flag-matching">
-                <title>License Flag Matching</title>
-
-                <para>
-                            License flag matching allows you to control what recipes
-                    the OpenEmbedded build system includes in the build.
-                    Fundamentally, the build system attempts to match
-                    <filename>LICENSE_FLAGS</filename> strings found in recipes
-                    against <filename>LICENSE_FLAGS_WHITELIST</filename>
-                    strings found in the whitelist.
-                    A match causes the build system to include a recipe in the
-                    build, while failure to find a match causes the build
-                    system to exclude a recipe.
-                </para>
-
-                <para>
-                    In general, license flag matching is simple.
-                    However, understanding some concepts will help you
-                    correctly and effectively use matching.
-                </para>
-
-                <para>
-                    Before a flag
-                    defined by a particular recipe is tested against the
-                    contents of the whitelist, the expanded string
-                    <filename>_${PN}</filename> is appended to the flag.
-                    This expansion makes each
-                    <filename>LICENSE_FLAGS</filename> value recipe-specific.
-                    After expansion, the string is then matched against the
-                    whitelist.
-                    Thus, specifying
-                    <filename>LICENSE_FLAGS = "commercial"</filename>
-                    in recipe "foo", for example, results in the string
-                    <filename>"commercial_foo"</filename>.
-                    And, to create a match, that string must appear in the
-                    whitelist.
-                </para>
-
-                <para>
-                    Judicious use of the <filename>LICENSE_FLAGS</filename>
-                    strings and the contents of the
-                    <filename>LICENSE_FLAGS_WHITELIST</filename> variable
-                    allows you a lot of flexibility for including or excluding
-                    recipes based on licensing.
-                    For example, you can broaden the matching capabilities by
-                    using license flags string subsets in the whitelist.
-                    <note>
-                        When using a string subset, be sure to use the part of
-                        the expanded string that precedes the appended
-                        underscore character (e.g.
-                        <filename>usethispart_1.3</filename>,
-                        <filename>usethispart_1.4</filename>, and so forth).
-                    </note>
-                    For example, simply specifying the string "commercial" in
-                    the whitelist matches any expanded
-                    <filename>LICENSE_FLAGS</filename> definition that starts
-                    with the string "commercial" such as "commercial_foo" and
-                    "commercial_bar", which are the strings the build system
-                    automatically generates for hypothetical recipes named
-                    "foo" and "bar" assuming those recipes simply specify the
-                    following:
-                    <literallayout class='monospaced'>
-     LICENSE_FLAGS = "commercial"
-                    </literallayout>
-                    Thus, you can choose to exhaustively
-                    enumerate each license flag in the whitelist and
-                    allow only specific recipes into the image, or
-                    you can use a string subset that causes a broader range of
-                    matches to allow a range of recipes into the image.
-                </para>
-
-                <para>
-                    This scheme works even if the
-                    <filename>LICENSE_FLAGS</filename> string already
-                    has <filename>_${PN}</filename> appended.
-                    For example, the build system turns the license flag
-                    "commercial_1.2_foo" into "commercial_1.2_foo_foo" and
-                    would match both the general "commercial" and the specific
-                    "commercial_1.2_foo" strings found in the whitelist, as
-                    expected.
-                </para>
-
-                <para>
-                    Here are some other scenarios:
-                    <itemizedlist>
-                        <listitem><para>
-                            You can specify a versioned string in the recipe
-                            such as "commercial_foo_1.2" in a "foo" recipe.
-                            The build system expands this string to
-                            "commercial_foo_1.2_foo".
-                            Combine this license flag with a whitelist that has
-                            the string "commercial" and you match the flag
-                            along with any other flag that starts with the
-                            string "commercial".
-                            </para></listitem>
-                        <listitem><para>
-                            Under the same circumstances, you can use
-                            "commercial_foo" in the whitelist and the build
-                            system not only matches "commercial_foo_1.2" but
-                            also matches any license flag with the string
-                            "commercial_foo", regardless of the version.
-                            </para></listitem>
-                        <listitem><para>
-                            You can be very specific and use both the
-                            package and version parts in the whitelist (e.g.
-                            "commercial_foo_1.2") to specifically match a
-                            versioned recipe.
-                            </para></listitem>
-                    </itemizedlist>
-                </para>
-            </section>
-
-            <section id="other-variables-related-to-commercial-licenses">
-                <title>Other Variables Related to Commercial Licenses</title>
-
-                <para>
-                    Other helpful variables related to commercial
-                    license handling exist and are defined in the
-                    <filename>poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
-                    <literallayout class='monospaced'>
-     COMMERCIAL_AUDIO_PLUGINS ?= ""
-     COMMERCIAL_VIDEO_PLUGINS ?= ""
-                    </literallayout>
-                    If you want to enable these components, you can do so by
-                    making sure you have statements similar to the following
-                    in your <filename>local.conf</filename> 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"
-     LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
-                    </literallayout>
-                    Of course, you could also create a matching whitelist
-                    for those components using the more general "commercial"
-                    in the whitelist, but that would also enable all the
-                    other packages with <filename>LICENSE_FLAGS</filename>
-                    containing "commercial", which you may or may not want:
-                    <literallayout class='monospaced'>
-     LICENSE_FLAGS_WHITELIST = "commercial"
-                    </literallayout>
-                </para>
-
-                <para>
-                    Specifying audio and video plug-ins as part of the
-                    <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and
-                    <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements
-                    (along with the enabling
-                    <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the
-                    plug-ins or components into built images, thus adding
-                    support for media formats or components.
-                </para>
-            </section>
-        </section>
-    </section>
 </chapter>
 <!--
 vim: expandtab tw=80 ts=4