summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-05-15 11:14:50 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-05-24 17:16:34 +0100
commit51c74acdadae6a84763e1f0ff623d664c9abb0a3 (patch)
tree33efed82b8d1a91c40648fb828f8c710dd7f5bba
parentafe2d7cf45cc666c7930e4667dfaf48e2cd5a7a4 (diff)
downloadpoky-51c74acdadae6a84763e1f0ff623d664c9abb0a3.tar.gz
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>
-rw-r--r--documentation/bsp-guide/bsp.xml4
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml793
-rw-r--r--documentation/overview-manual/overview-manual-concepts.xml391
-rw-r--r--documentation/ref-manual/ref-variables.xml12
4 files changed, 599 insertions, 601 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 87636c8bd0..00dd60a33a 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -1687,8 +1687,8 @@
1687 Thus, the build system can build the corresponding 1687 Thus, the build system can build the corresponding
1688 recipe and include the component in the image. 1688 recipe and include the component in the image.
1689 See the 1689 See the
1690 "<ulink url='&YOCTO_DOCS_OM_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>" 1690 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
1691 section in the Yocto Project Overview and Concepts 1691 section in the Yocto Project Development Tasks
1692 Manual for details on how to use these variables. 1692 Manual for details on how to use these variables.
1693 </para> 1693 </para>
1694 1694
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 61ed8f1cee..14cf1a1685 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -2187,9 +2187,8 @@
2187 containing the current checksum. 2187 containing the current checksum.
2188 For more explanation and examples of how to set the 2188 For more explanation and examples of how to set the
2189 <filename>LIC_FILES_CHKSUM</filename> variable, see the 2189 <filename>LIC_FILES_CHKSUM</filename> variable, see the
2190 "<ulink url='&YOCTO_DOCS_OM_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" 2190 "<link link='usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</link>"
2191 section in the Yocto Project Overview and Concepts 2191 section.</para>
2192 Manual.</para>
2193 2192
2194 <para>To determine the correct checksum string, you 2193 <para>To determine the correct checksum string, you
2195 can list the appropriate files in the 2194 can list the appropriate files in the
@@ -3400,7 +3399,7 @@
3400 The variable 3399 The variable
3401 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename> 3400 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename>
3402 is used to track source license changes as described in the 3401 is used to track source license changes as described in the
3403 "<ulink url='&YOCTO_DOCS_OM_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" 3402 "<link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</link>"
3404 section in the Yocto Project Overview and Concepts Manual. 3403 section in the Yocto Project Overview and Concepts Manual.
3405 You can quickly create Autotool-based recipes in a manner 3404 You can quickly create Autotool-based recipes in a manner
3406 similar to the previous example. 3405 similar to the previous example.
@@ -13501,127 +13500,515 @@ Some notes from Cal:
13501 </section> 13500 </section>
13502 </section> 13501 </section>
13503 13502
13504 <section id='maintaining-open-source-license-compliance-during-your-products-lifecycle'> 13503 <section id='working-with-licenses'>
13505 <title>Maintaining Open Source License Compliance During Your Product's Lifecycle</title> 13504 <title>Working With Licenses</title>
13506 13505
13507 <para> 13506 <para>
13508 One of the concerns for a development organization using open source 13507 As mentioned in the
13509 software is how to maintain compliance with various open source 13508 "<ulink url='&YOCTO_DOCS_OM_URL;#licensing'>Licensing</ulink>"
13510 licensing during the lifecycle of the product. 13509 section in the Yocto Project Overview and Concepts Manual,
13511 While this section does not provide legal advice or 13510 open source projects are open to the public and they
13512 comprehensively cover all scenarios, it does 13511 consequently have different licensing structures in place.
13513 present methods that you can use to 13512 This section describes the mechanism by which the
13514 assist you in meeting the compliance requirements during a software 13513 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
13515 release. 13514 tracks changes to licensing text and covers how to maintain open
13515 source license compliance during your project's lifecycle.
13516 The section also describes how to enable commercially licensed
13517 recipes, which by default are disabled.
13516 </para> 13518 </para>
13517 13519
13518 <para> 13520 <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
13519 With hundreds of different open source licenses that the Yocto 13521 <title>Tracking License Changes</title>
13520 Project tracks, it is difficult to know the requirements of each
13521 and every license.
13522 However, the requirements of the major FLOSS licenses can begin
13523 to be covered by
13524 assuming that three main areas of concern exist:
13525 <itemizedlist>
13526 <listitem><para>Source code must be provided.</para></listitem>
13527 <listitem><para>License text for the software must be
13528 provided.</para></listitem>
13529 <listitem><para>Compilation scripts and modifications to the
13530 source code must be provided.
13531 </para></listitem>
13532 </itemizedlist>
13533 There are other requirements beyond the scope of these
13534 three and the methods described in this section
13535 (e.g. the mechanism through which source code is distributed).
13536 </para>
13537 13522
13538 <para> 13523 <para>
13539 As different organizations have different methods of complying with 13524 The license of an upstream project might change in the future.
13540 open source licensing, this section is not meant to imply that 13525 In order to prevent these changes going unnoticed, the
13541 there is only one single way to meet your compliance obligations, 13526 <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
13542 but rather to describe one method of achieving compliance. 13527 variable tracks changes to the license text. The checksums are
13543 The remainder of this section describes methods supported to meet the 13528 validated at the end of the configure step, and if the
13544 previously mentioned three requirements. 13529 checksums do not match, the build will fail.
13545 Once you take steps to meet these requirements, 13530 </para>
13546 and prior to releasing images, sources, and the build system, 13531
13547 you should audit all artifacts to ensure completeness. 13532 <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
13548 <note> 13533 <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
13549 The Yocto Project generates a license manifest during 13534
13550 image creation that is located 13535 <para>
13551 in <filename>${DEPLOY_DIR}/licenses/<replaceable>image_name-datestamp</replaceable></filename> 13536 The <filename>LIC_FILES_CHKSUM</filename>
13552 to assist with any audits. 13537 variable contains checksums of the license text in the
13553 </note> 13538 source code for the recipe.
13554 </para> 13539 Following is an example of how to specify
13540 <filename>LIC_FILES_CHKSUM</filename>:
13541 <literallayout class='monospaced'>
13542 LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
13543 file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
13544 file://licfile2.txt;endline=50;md5=zzzz \
13545 ..."
13546 </literallayout>
13547 <note><title>Notes</title>
13548 <itemizedlist>
13549 <listitem><para>
13550 When using "beginline" and "endline", realize
13551 that line numbering begins with one and not
13552 zero.
13553 Also, the included lines are inclusive (i.e.
13554 lines five through and including 29 in the
13555 previous example for
13556 <filename>licfile1.txt</filename>).
13557 </para></listitem>
13558 <listitem><para>
13559 When a license check fails, the selected license
13560 text is included as part of the QA message.
13561 Using this output, you can determine the exact
13562 start and finish for the needed license text.
13563 </para></listitem>
13564 </itemizedlist>
13565 </note>
13566 </para>
13567
13568 <para>
13569 The build system uses the
13570 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
13571 variable as the default directory when searching files
13572 listed in <filename>LIC_FILES_CHKSUM</filename>.
13573 The previous example employs the default directory.
13574 </para>
13575
13576 <para>
13577 Consider this next example:
13578 <literallayout class='monospaced'>
13579 LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\
13580 md5=bb14ed3c4cda583abc85401304b5cd4e"
13581 LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
13582 </literallayout>
13583 </para>
13584
13585 <para>
13586 The first line locates a file in
13587 <filename>${S}/src/ls.c</filename> and isolates lines five
13588 through 16 as license text.
13589 The second line refers to a file in
13590 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>.
13591 </para>
13592
13593 <para>
13594 Note that <filename>LIC_FILES_CHKSUM</filename> variable is
13595 mandatory for all recipes, unless the
13596 <filename>LICENSE</filename> variable is set to "CLOSED".
13597 </para>
13598 </section>
13599
13600 <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
13601 <title>Explanation of Syntax</title>
13602
13603 <para>
13604 As mentioned in the previous section, the
13605 <filename>LIC_FILES_CHKSUM</filename> variable lists all
13606 the important files that contain the license text for the
13607 source code.
13608 It is possible to specify a checksum for an entire file,
13609 or a specific section of a file (specified by beginning and
13610 ending line numbers with the "beginline" and "endline"
13611 parameters, respectively).
13612 The latter is useful for source files with a license
13613 notice header, README documents, and so forth.
13614 If you do not use the "beginline" parameter, then it is
13615 assumed that the text begins on the first line of the file.
13616 Similarly, if you do not use the "endline" parameter,
13617 it is assumed that the license text ends with the last
13618 line of the file.
13619 </para>
13620
13621 <para>
13622 The "md5" parameter stores the md5 checksum of the license
13623 text.
13624 If the license text changes in any way as compared to
13625 this parameter then a mismatch occurs.
13626 This mismatch triggers a build failure and notifies
13627 the developer.
13628 Notification allows the developer to review and address
13629 the license text changes.
13630 Also note that if a mismatch occurs during the build,
13631 the correct md5 checksum is placed in the build log and
13632 can be easily copied to the recipe.
13633 </para>
13634
13635 <para>
13636 There is no limit to how many files you can specify using
13637 the <filename>LIC_FILES_CHKSUM</filename> variable.
13638 Generally, however, every project requires a few
13639 specifications for license tracking.
13640 Many projects have a "COPYING" file that stores the
13641 license information for all the source code files.
13642 This practice allows you to just track the "COPYING"
13643 file as long as it is kept up to date.
13644 <note><title>Tips</title>
13645 <itemizedlist>
13646 <listitem><para>
13647 If you specify an empty or invalid "md5"
13648 parameter,
13649 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
13650 returns an md5 mis-match
13651 error and displays the correct "md5" parameter
13652 value during the build.
13653 The correct parameter is also captured in
13654 the build log.
13655 </para></listitem>
13656 <listitem><para>
13657 If the whole file contains only license text,
13658 you do not need to use the "beginline" and
13659 "endline" parameters.
13660 </para></listitem>
13661 </itemizedlist>
13662 </note>
13663 </para>
13664 </section>
13665 </section>
13555 13666
13556 <section id='providing-the-source-code'> 13667 <section id="enabling-commercially-licensed-recipes">
13557 <title>Providing the Source Code</title> 13668 <title>Enabling Commercially Licensed Recipes</title>
13558 13669
13559 <para> 13670 <para>
13560 Compliance activities should begin before you generate the 13671 By default, the OpenEmbedded build system disables
13561 final image. 13672 components that have commercial or other special licensing
13562 The first thing you should look at is the requirement that 13673 requirements.
13563 tops the list for most compliance groups - providing 13674 Such requirements are defined on a
13564 the source. 13675 recipe-by-recipe basis through the
13565 The Yocto Project has a few ways of meeting this 13676 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
13566 requirement. 13677 variable definition in the affected recipe.
13678 For instance, the
13679 <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
13680 recipe contains the following statement:
13681 <literallayout class='monospaced'>
13682 LICENSE_FLAGS = "commercial"
13683 </literallayout>
13684 Here is a slightly more complicated example that contains both
13685 an explicit recipe name and version (after variable expansion):
13686 <literallayout class='monospaced'>
13687 LICENSE_FLAGS = "license_${PN}_${PV}"
13688 </literallayout>
13689 In order for a component restricted by a
13690 <filename>LICENSE_FLAGS</filename> definition to be enabled and
13691 included in an image, it needs to have a matching entry in the
13692 global
13693 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>
13694 variable, which is a variable typically defined in your
13695 <filename>local.conf</filename> file.
13696 For example, to enable the
13697 <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
13698 package, you could add either the string
13699 "commercial_gst-plugins-ugly" or the more general string
13700 "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>.
13701 See the
13702 "<link linkend='license-flag-matching'>License Flag Matching</link>"
13703 section for a full
13704 explanation of how <filename>LICENSE_FLAGS</filename> matching
13705 works.
13706 Here is the example:
13707 <literallayout class='monospaced'>
13708 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
13709 </literallayout>
13710 Likewise, to additionally enable the package built from the
13711 recipe containing
13712 <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>,
13713 and assuming that the actual recipe name was
13714 <filename>emgd_1.10.bb</filename>, the following string would
13715 enable that package as well as the original
13716 <filename>gst-plugins-ugly</filename> package:
13717 <literallayout class='monospaced'>
13718 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
13719 </literallayout>
13720 As a convenience, you do not need to specify the complete
13721 license string in the whitelist for every package.
13722 You can use an abbreviated form, which consists
13723 of just the first portion or portions of the license
13724 string before the initial underscore character or characters.
13725 A partial string will match any license that contains the
13726 given string as the first portion of its license.
13727 For example, the following whitelist string will also match
13728 both of the packages previously mentioned as well as any other
13729 packages that have licenses starting with "commercial" or
13730 "license".
13731 <literallayout class='monospaced'>
13732 LICENSE_FLAGS_WHITELIST = "commercial license"
13733 </literallayout>
13567 </para> 13734 </para>
13568 13735
13736 <section id="license-flag-matching">
13737 <title>License Flag Matching</title>
13738
13739 <para>
13740 License flag matching allows you to control what recipes
13741 the OpenEmbedded build system includes in the build.
13742 Fundamentally, the build system attempts to match
13743 <filename>LICENSE_FLAGS</filename> strings found in recipes
13744 against <filename>LICENSE_FLAGS_WHITELIST</filename>
13745 strings found in the whitelist.
13746 A match causes the build system to include a recipe in the
13747 build, while failure to find a match causes the build
13748 system to exclude a recipe.
13749 </para>
13750
13751 <para>
13752 In general, license flag matching is simple.
13753 However, understanding some concepts will help you
13754 correctly and effectively use matching.
13755 </para>
13756
13757 <para>
13758 Before a flag
13759 defined by a particular recipe is tested against the
13760 contents of the whitelist, the expanded string
13761 <filename>_${PN}</filename> is appended to the flag.
13762 This expansion makes each
13763 <filename>LICENSE_FLAGS</filename> value recipe-specific.
13764 After expansion, the string is then matched against the
13765 whitelist.
13766 Thus, specifying
13767 <filename>LICENSE_FLAGS = "commercial"</filename>
13768 in recipe "foo", for example, results in the string
13769 <filename>"commercial_foo"</filename>.
13770 And, to create a match, that string must appear in the
13771 whitelist.
13772 </para>
13773
13774 <para>
13775 Judicious use of the <filename>LICENSE_FLAGS</filename>
13776 strings and the contents of the
13777 <filename>LICENSE_FLAGS_WHITELIST</filename> variable
13778 allows you a lot of flexibility for including or excluding
13779 recipes based on licensing.
13780 For example, you can broaden the matching capabilities by
13781 using license flags string subsets in the whitelist.
13782 <note>
13783 When using a string subset, be sure to use the part of
13784 the expanded string that precedes the appended
13785 underscore character (e.g.
13786 <filename>usethispart_1.3</filename>,
13787 <filename>usethispart_1.4</filename>, and so forth).
13788 </note>
13789 For example, simply specifying the string "commercial" in
13790 the whitelist matches any expanded
13791 <filename>LICENSE_FLAGS</filename> definition that starts
13792 with the string "commercial" such as "commercial_foo" and
13793 "commercial_bar", which are the strings the build system
13794 automatically generates for hypothetical recipes named
13795 "foo" and "bar" assuming those recipes simply specify the
13796 following:
13797 <literallayout class='monospaced'>
13798 LICENSE_FLAGS = "commercial"
13799 </literallayout>
13800 Thus, you can choose to exhaustively
13801 enumerate each license flag in the whitelist and
13802 allow only specific recipes into the image, or
13803 you can use a string subset that causes a broader range of
13804 matches to allow a range of recipes into the image.
13805 </para>
13806
13807 <para>
13808 This scheme works even if the
13809 <filename>LICENSE_FLAGS</filename> string already
13810 has <filename>_${PN}</filename> appended.
13811 For example, the build system turns the license flag
13812 "commercial_1.2_foo" into "commercial_1.2_foo_foo" and
13813 would match both the general "commercial" and the specific
13814 "commercial_1.2_foo" strings found in the whitelist, as
13815 expected.
13816 </para>
13817
13818 <para>
13819 Here are some other scenarios:
13820 <itemizedlist>
13821 <listitem><para>
13822 You can specify a versioned string in the recipe
13823 such as "commercial_foo_1.2" in a "foo" recipe.
13824 The build system expands this string to
13825 "commercial_foo_1.2_foo".
13826 Combine this license flag with a whitelist that has
13827 the string "commercial" and you match the flag
13828 along with any other flag that starts with the
13829 string "commercial".
13830 </para></listitem>
13831 <listitem><para>
13832 Under the same circumstances, you can use
13833 "commercial_foo" in the whitelist and the build
13834 system not only matches "commercial_foo_1.2" but
13835 also matches any license flag with the string
13836 "commercial_foo", regardless of the version.
13837 </para></listitem>
13838 <listitem><para>
13839 You can be very specific and use both the
13840 package and version parts in the whitelist (e.g.
13841 "commercial_foo_1.2") to specifically match a
13842 versioned recipe.
13843 </para></listitem>
13844 </itemizedlist>
13845 </para>
13846 </section>
13847
13848 <section id="other-variables-related-to-commercial-licenses">
13849 <title>Other Variables Related to Commercial Licenses</title>
13850
13851 <para>
13852 Other helpful variables related to commercial
13853 license handling exist and are defined in the
13854 <filename>poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
13855 <literallayout class='monospaced'>
13856 COMMERCIAL_AUDIO_PLUGINS ?= ""
13857 COMMERCIAL_VIDEO_PLUGINS ?= ""
13858 </literallayout>
13859 If you want to enable these components, you can do so by
13860 making sure you have statements similar to the following
13861 in your <filename>local.conf</filename> configuration file:
13862 <literallayout class='monospaced'>
13863 COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
13864 gst-plugins-ugly-mpegaudioparse"
13865 COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
13866 gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
13867 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
13868 </literallayout>
13869 Of course, you could also create a matching whitelist
13870 for those components using the more general "commercial"
13871 in the whitelist, but that would also enable all the
13872 other packages with <filename>LICENSE_FLAGS</filename>
13873 containing "commercial", which you may or may not want:
13874 <literallayout class='monospaced'>
13875 LICENSE_FLAGS_WHITELIST = "commercial"
13876 </literallayout>
13877 </para>
13878
13879 <para>
13880 Specifying audio and video plug-ins as part of the
13881 <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and
13882 <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements
13883 (along with the enabling
13884 <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the
13885 plug-ins or components into built images, thus adding
13886 support for media formats or components.
13887 </para>
13888 </section>
13889 </section>
13890
13891 <section id='maintaining-open-source-license-compliance-during-your-products-lifecycle'>
13892 <title>Maintaining Open Source License Compliance During Your Product's Lifecycle</title>
13893
13569 <para> 13894 <para>
13570 One of the easiest ways to meet this requirement is 13895 One of the concerns for a development organization using open source
13571 to provide the entire 13896 software is how to maintain compliance with various open source
13572 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink> 13897 licensing during the lifecycle of the product.
13573 used by the build. 13898 While this section does not provide legal advice or
13574 This method, however, has a few issues. 13899 comprehensively cover all scenarios, it does
13575 The most obvious is the size of the directory since it includes 13900 present methods that you can use to
13576 all sources used in the build and not just the source used in 13901 assist you in meeting the compliance requirements during a software
13577 the released image. 13902 release.
13578 It will include toolchain source, and other artifacts, which
13579 you would not generally release.
13580 However, the more serious issue for most companies is accidental
13581 release of proprietary software.
13582 The Yocto Project provides an
13583 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-archiver'><filename>archiver</filename></ulink>
13584 class to help avoid some of these concerns.
13585 </para> 13903 </para>
13586 13904
13587 <para> 13905 <para>
13588 Before you employ <filename>DL_DIR</filename> or the 13906 With hundreds of different open source licenses that the Yocto
13589 <filename>archiver</filename> class, you need to decide how 13907 Project tracks, it is difficult to know the requirements of each
13590 you choose to provide source. 13908 and every license.
13591 The source <filename>archiver</filename> class can generate 13909 However, the requirements of the major FLOSS licenses can begin
13592 tarballs and SRPMs and can create them with various levels of 13910 to be covered by
13593 compliance in mind. 13911 assuming that three main areas of concern exist:
13912 <itemizedlist>
13913 <listitem><para>Source code must be provided.</para></listitem>
13914 <listitem><para>License text for the software must be
13915 provided.</para></listitem>
13916 <listitem><para>Compilation scripts and modifications to the
13917 source code must be provided.
13918 </para></listitem>
13919 </itemizedlist>
13920 There are other requirements beyond the scope of these
13921 three and the methods described in this section
13922 (e.g. the mechanism through which source code is distributed).
13594 </para> 13923 </para>
13595 13924
13596 <para> 13925 <para>
13597 One way of doing this (but certainly not the only way) is to 13926 As different organizations have different methods of complying with
13598 release just the source as a tarball. 13927 open source licensing, this section is not meant to imply that
13599 You can do this by adding the following to the 13928 there is only one single way to meet your compliance obligations,
13600 <filename>local.conf</filename> file found in the 13929 but rather to describe one method of achieving compliance.
13601 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>: 13930 The remainder of this section describes methods supported to meet the
13602 <literallayout class='monospaced'> 13931 previously mentioned three requirements.
13932 Once you take steps to meet these requirements,
13933 and prior to releasing images, sources, and the build system,
13934 you should audit all artifacts to ensure completeness.
13935 <note>
13936 The Yocto Project generates a license manifest during
13937 image creation that is located
13938 in <filename>${DEPLOY_DIR}/licenses/<replaceable>image_name-datestamp</replaceable></filename>
13939 to assist with any audits.
13940 </note>
13941 </para>
13942
13943 <section id='providing-the-source-code'>
13944 <title>Providing the Source Code</title>
13945
13946 <para>
13947 Compliance activities should begin before you generate the
13948 final image.
13949 The first thing you should look at is the requirement that
13950 tops the list for most compliance groups - providing
13951 the source.
13952 The Yocto Project has a few ways of meeting this
13953 requirement.
13954 </para>
13955
13956 <para>
13957 One of the easiest ways to meet this requirement is
13958 to provide the entire
13959 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
13960 used by the build.
13961 This method, however, has a few issues.
13962 The most obvious is the size of the directory since it includes
13963 all sources used in the build and not just the source used in
13964 the released image.
13965 It will include toolchain source, and other artifacts, which
13966 you would not generally release.
13967 However, the more serious issue for most companies is accidental
13968 release of proprietary software.
13969 The Yocto Project provides an
13970 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-archiver'><filename>archiver</filename></ulink>
13971 class to help avoid some of these concerns.
13972 </para>
13973
13974 <para>
13975 Before you employ <filename>DL_DIR</filename> or the
13976 <filename>archiver</filename> class, you need to decide how
13977 you choose to provide source.
13978 The source <filename>archiver</filename> class can generate
13979 tarballs and SRPMs and can create them with various levels of
13980 compliance in mind.
13981 </para>
13982
13983 <para>
13984 One way of doing this (but certainly not the only way) is to
13985 release just the source as a tarball.
13986 You can do this by adding the following to the
13987 <filename>local.conf</filename> file found in the
13988 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>:
13989 <literallayout class='monospaced'>
13603 INHERIT += "archiver" 13990 INHERIT += "archiver"
13604 ARCHIVER_MODE[src] = "original" 13991 ARCHIVER_MODE[src] = "original"
13605 </literallayout> 13992 </literallayout>
13606 During the creation of your image, the source from all 13993 During the creation of your image, the source from all
13607 recipes that deploy packages to the image is placed within 13994 recipes that deploy packages to the image is placed within
13608 subdirectories of 13995 subdirectories of
13609 <filename>DEPLOY_DIR/sources</filename> based on the 13996 <filename>DEPLOY_DIR/sources</filename> based on the
13610 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink> 13997 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
13611 for each recipe. 13998 for each recipe.
13612 Releasing the entire directory enables you to comply with 13999 Releasing the entire directory enables you to comply with
13613 requirements concerning providing the unmodified source. 14000 requirements concerning providing the unmodified source.
13614 It is important to note that the size of the directory can 14001 It is important to note that the size of the directory can
13615 get large. 14002 get large.
13616 </para> 14003 </para>
13617 14004
13618 <para> 14005 <para>
13619 A way to help mitigate the size issue is to only release 14006 A way to help mitigate the size issue is to only release
13620 tarballs for licenses that require the release of 14007 tarballs for licenses that require the release of
13621 source. 14008 source.
13622 Let us assume you are only concerned with GPL code as 14009 Let us assume you are only concerned with GPL code as
13623 identified by running the following script: 14010 identified by running the following script:
13624 <literallayout class='monospaced'> 14011 <literallayout class='monospaced'>
13625 # Script to archive a subset of packages matching specific license(s) 14012 # Script to archive a subset of packages matching specific license(s)
13626 # Source and license files are copied into sub folders of package folder 14013 # Source and license files are copied into sub folders of package folder
13627 # Must be run from build folder 14014 # Must be run from build folder
@@ -13644,96 +14031,97 @@ Some notes from Cal:
13644 cp tmp/deploy/licenses/$p/* $src_release_dir/$p/license 2> /dev/null 14031 cp tmp/deploy/licenses/$p/* $src_release_dir/$p/license 2> /dev/null
13645 fi 14032 fi
13646 done 14033 done
13647 done </literallayout> 14034 done
13648 At this point, you could create a tarball from the 14035 </literallayout>
13649 <filename>gpl_source_release</filename> directory and 14036 At this point, you could create a tarball from the
13650 provide that to the end user. 14037 <filename>gpl_source_release</filename> directory and
13651 This method would be a step toward achieving compliance 14038 provide that to the end user.
13652 with section 3a of GPLv2 and with section 6 of GPLv3. 14039 This method would be a step toward achieving compliance
13653 </para> 14040 with section 3a of GPLv2 and with section 6 of GPLv3.
13654 </section> 14041 </para>
14042 </section>
13655 14043
13656 <section id='providing-license-text'> 14044 <section id='providing-license-text'>
13657 <title>Providing License Text</title> 14045 <title>Providing License Text</title>
13658 14046
13659 <para> 14047 <para>
13660 One requirement that is often overlooked is inclusion 14048 One requirement that is often overlooked is inclusion
13661 of license text. 14049 of license text.
13662 This requirement also needs to be dealt with prior to 14050 This requirement also needs to be dealt with prior to
13663 generating the final image. 14051 generating the final image.
13664 Some licenses require the license text to accompany 14052 Some licenses require the license text to accompany
13665 the binary. 14053 the binary.
13666 You can achieve this by adding the following to your 14054 You can achieve this by adding the following to your
13667 <filename>local.conf</filename> file: 14055 <filename>local.conf</filename> file:
13668 <literallayout class='monospaced'> 14056 <literallayout class='monospaced'>
13669 COPY_LIC_MANIFEST = "1" 14057 COPY_LIC_MANIFEST = "1"
13670 COPY_LIC_DIRS = "1" 14058 COPY_LIC_DIRS = "1"
13671 LICENSE_CREATE_PACKAGE = "1" 14059 LICENSE_CREATE_PACKAGE = "1"
13672 </literallayout> 14060 </literallayout>
13673 Adding these statements to the configuration file ensures 14061 Adding these statements to the configuration file ensures
13674 that the licenses collected during package generation 14062 that the licenses collected during package generation
13675 are included on your image. 14063 are included on your image.
13676 <note> 14064 <note>
13677 <para>Setting all three variables to "1" results in the 14065 <para>Setting all three variables to "1" results in the
13678 image having two copies of the same license file. 14066 image having two copies of the same license file.
13679 One copy resides in 14067 One copy resides in
13680 <filename>/usr/share/common-licenses</filename> and 14068 <filename>/usr/share/common-licenses</filename> and
13681 the other resides in 14069 the other resides in
13682 <filename>/usr/share/license</filename>.</para> 14070 <filename>/usr/share/license</filename>.</para>
13683 14071
13684 <para>The reason for this behavior is because 14072 <para>The reason for this behavior is because
13685 <ulink url='&YOCTO_DOCS_REF_URL;#var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></ulink> 14073 <ulink url='&YOCTO_DOCS_REF_URL;#var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></ulink>
13686 and 14074 and
13687 <ulink url='&YOCTO_DOCS_REF_URL;#var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></ulink> 14075 <ulink url='&YOCTO_DOCS_REF_URL;#var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></ulink>
13688 add a copy of the license when the image is built but do 14076 add a copy of the license when the image is built but do
13689 not offer a path for adding licenses for newly installed 14077 not offer a path for adding licenses for newly installed
13690 packages to an image. 14078 packages to an image.
13691 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></ulink> 14079 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></ulink>
13692 adds a separate package and an upgrade path for adding 14080 adds a separate package and an upgrade path for adding
13693 licenses to an image.</para> 14081 licenses to an image.</para>
13694 </note> 14082 </note>
13695 </para> 14083 </para>
13696 14084
13697 <para> 14085 <para>
13698 As the source <filename>archiver</filename> class has already 14086 As the source <filename>archiver</filename> class has already
13699 archived the original 14087 archived the original
13700 unmodified source that contains the license files, 14088 unmodified source that contains the license files,
13701 you would have already met the requirements for inclusion 14089 you would have already met the requirements for inclusion
13702 of the license information with source as defined by the GPL 14090 of the license information with source as defined by the GPL
13703 and other open source licenses. 14091 and other open source licenses.
13704 </para> 14092 </para>
13705 </section> 14093 </section>
13706 14094
13707 <section id='providing-compilation-scripts-and-source-code-modifications'> 14095 <section id='providing-compilation-scripts-and-source-code-modifications'>
13708 <title>Providing Compilation Scripts and Source Code Modifications</title> 14096 <title>Providing Compilation Scripts and Source Code Modifications</title>
13709 14097
13710 <para> 14098 <para>
13711 At this point, we have addressed all we need to 14099 At this point, we have addressed all we need to
13712 prior to generating the image. 14100 prior to generating the image.
13713 The next two requirements are addressed during the final 14101 The next two requirements are addressed during the final
13714 packaging of the release. 14102 packaging of the release.
13715 </para> 14103 </para>
13716 14104
13717 <para> 14105 <para>
13718 By releasing the version of the OpenEmbedded build system 14106 By releasing the version of the OpenEmbedded build system
13719 and the layers used during the build, you will be providing both 14107 and the layers used during the build, you will be providing both
13720 compilation scripts and the source code modifications in one 14108 compilation scripts and the source code modifications in one
13721 step. 14109 step.
13722 </para> 14110 </para>
13723 14111
13724 <para> 14112 <para>
13725 If the deployment team has a 14113 If the deployment team has a
13726 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP layer</ulink> 14114 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP layer</ulink>
13727 and a distro layer, and those those layers are used to patch, 14115 and a distro layer, and those those layers are used to patch,
13728 compile, package, or modify (in any way) any open source 14116 compile, package, or modify (in any way) any open source
13729 software included in your released images, you 14117 software included in your released images, you
13730 might be required to release those layers under section 3 of 14118 might be required to release those layers under section 3 of
13731 GPLv2 or section 1 of GPLv3. 14119 GPLv2 or section 1 of GPLv3.
13732 One way of doing that is with a clean 14120 One way of doing that is with a clean
13733 checkout of the version of the Yocto Project and layers used 14121 checkout of the version of the Yocto Project and layers used
13734 during your build. 14122 during your build.
13735 Here is an example: 14123 Here is an example:
13736 <literallayout class='monospaced'> 14124 <literallayout class='monospaced'>
13737 # We built using the &DISTRO_NAME_NO_CAP; branch of the poky repo 14125 # We built using the &DISTRO_NAME_NO_CAP; branch of the poky repo
13738 $ git clone -b &DISTRO_NAME_NO_CAP; git://git.yoctoproject.org/poky 14126 $ git clone -b &DISTRO_NAME_NO_CAP; git://git.yoctoproject.org/poky
13739 $ cd poky 14127 $ cd poky
@@ -13742,15 +14130,15 @@ Some notes from Cal:
13742 $ git clone -b release_branch git://git.mycompany.com/meta-my-software-layer 14130 $ git clone -b release_branch git://git.mycompany.com/meta-my-software-layer
13743 # clean up the .git repos 14131 # clean up the .git repos
13744 $ find . -name ".git" -type d -exec rm -rf {} \; 14132 $ find . -name ".git" -type d -exec rm -rf {} \;
13745 </literallayout> 14133 </literallayout>
13746 One thing a development organization might want to consider 14134 One thing a development organization might want to consider
13747 for end-user convenience is to modify 14135 for end-user convenience is to modify
13748 <filename>meta-poky/conf/bblayers.conf.sample</filename> to 14136 <filename>meta-poky/conf/bblayers.conf.sample</filename> to
13749 ensure that when the end user utilizes the released build 14137 ensure that when the end user utilizes the released build
13750 system to build an image, the development organization's 14138 system to build an image, the development organization's
13751 layers are included in the <filename>bblayers.conf</filename> 14139 layers are included in the <filename>bblayers.conf</filename>
13752 file automatically: 14140 file automatically:
13753 <literallayout class='monospaced'> 14141 <literallayout class='monospaced'>
13754 # POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf 14142 # POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf
13755 # changes incompatibly 14143 # changes incompatibly
13756 POKY_BBLAYERS_CONF_VERSION = "2" 14144 POKY_BBLAYERS_CONF_VERSION = "2"
@@ -13764,14 +14152,15 @@ Some notes from Cal:
13764 ##OEROOT##/meta-yocto-bsp \ 14152 ##OEROOT##/meta-yocto-bsp \
13765 ##OEROOT##/meta-mylayer \ 14153 ##OEROOT##/meta-mylayer \
13766 " 14154 "
13767 </literallayout> 14155 </literallayout>
13768 Creating and providing an archive of the 14156 Creating and providing an archive of the
13769 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> 14157 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
13770 layers (recipes, configuration files, and so forth) 14158 layers (recipes, configuration files, and so forth)
13771 enables you to meet your 14159 enables you to meet your
13772 requirements to include the scripts to control compilation 14160 requirements to include the scripts to control compilation
13773 as well as any modifications to the original source. 14161 as well as any modifications to the original source.
13774 </para> 14162 </para>
14163 </section>
13775 </section> 14164 </section>
13776 </section> 14165 </section>
13777 14166
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 @@
3226 articles for background information on Pseudo. 3226 articles for background information on Pseudo.
3227 </para> 3227 </para>
3228 </section> 3228 </section>
3229
3230 <section id="overview-licenses">
3231 <title>Licenses</title>
3232
3233 <para>
3234 This section describes the mechanism by which the
3235 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
3236 tracks changes to licensing text.
3237 The section also describes how to enable commercially licensed
3238 recipes, which by default are disabled.
3239 </para>
3240
3241 <para>
3242 For information that can help you maintain compliance with
3243 various open source licensing during the lifecycle of the product,
3244 see the
3245 "<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>"
3246 section in the Yocto Project Development Tasks Manual.
3247 </para>
3248
3249 <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
3250 <title>Tracking License Changes</title>
3251
3252 <para>
3253 The license of an upstream project might change in the future.
3254 In order to prevent these changes going unnoticed, the
3255 <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
3256 variable tracks changes to the license text. The checksums are
3257 validated at the end of the configure step, and if the
3258 checksums do not match, the build will fail.
3259 </para>
3260
3261 <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
3262 <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
3263
3264 <para>
3265 The <filename>LIC_FILES_CHKSUM</filename>
3266 variable contains checksums of the license text in the
3267 source code for the recipe.
3268 Following is an example of how to specify
3269 <filename>LIC_FILES_CHKSUM</filename>:
3270 <literallayout class='monospaced'>
3271 LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
3272 file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
3273 file://licfile2.txt;endline=50;md5=zzzz \
3274 ..."
3275 </literallayout>
3276 <note><title>Notes</title>
3277 <itemizedlist>
3278 <listitem><para>
3279 When using "beginline" and "endline", realize
3280 that line numbering begins with one and not
3281 zero.
3282 Also, the included lines are inclusive (i.e.
3283 lines five through and including 29 in the
3284 previous example for
3285 <filename>licfile1.txt</filename>).
3286 </para></listitem>
3287 <listitem><para>
3288 When a license check fails, the selected license
3289 text is included as part of the QA message.
3290 Using this output, you can determine the exact
3291 start and finish for the needed license text.
3292 </para></listitem>
3293 </itemizedlist>
3294 </note>
3295 </para>
3296
3297 <para>
3298 The build system uses the
3299 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
3300 variable as the default directory when searching files
3301 listed in <filename>LIC_FILES_CHKSUM</filename>.
3302 The previous example employs the default directory.
3303 </para>
3304
3305 <para>
3306 Consider this next example:
3307 <literallayout class='monospaced'>
3308 LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\
3309 md5=bb14ed3c4cda583abc85401304b5cd4e"
3310 LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
3311 </literallayout>
3312 </para>
3313
3314 <para>
3315 The first line locates a file in
3316 <filename>${S}/src/ls.c</filename> and isolates lines five
3317 through 16 as license text.
3318 The second line refers to a file in
3319 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>.
3320 </para>
3321
3322 <para>
3323 Note that <filename>LIC_FILES_CHKSUM</filename> variable is
3324 mandatory for all recipes, unless the
3325 <filename>LICENSE</filename> variable is set to "CLOSED".
3326 </para>
3327 </section>
3328
3329 <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
3330 <title>Explanation of Syntax</title>
3331
3332 <para>
3333 As mentioned in the previous section, the
3334 <filename>LIC_FILES_CHKSUM</filename> variable lists all
3335 the important files that contain the license text for the
3336 source code.
3337 It is possible to specify a checksum for an entire file,
3338 or a specific section of a file (specified by beginning and
3339 ending line numbers with the "beginline" and "endline"
3340 parameters, respectively).
3341 The latter is useful for source files with a license
3342 notice header, README documents, and so forth.
3343 If you do not use the "beginline" parameter, then it is
3344 assumed that the text begins on the first line of the file.
3345 Similarly, if you do not use the "endline" parameter,
3346 it is assumed that the license text ends with the last
3347 line of the file.
3348 </para>
3349
3350 <para>
3351 The "md5" parameter stores the md5 checksum of the license
3352 text.
3353 If the license text changes in any way as compared to
3354 this parameter then a mismatch occurs.
3355 This mismatch triggers a build failure and notifies
3356 the developer.
3357 Notification allows the developer to review and address
3358 the license text changes.
3359 Also note that if a mismatch occurs during the build,
3360 the correct md5 checksum is placed in the build log and
3361 can be easily copied to the recipe.
3362 </para>
3363
3364 <para>
3365 There is no limit to how many files you can specify using
3366 the <filename>LIC_FILES_CHKSUM</filename> variable.
3367 Generally, however, every project requires a few
3368 specifications for license tracking.
3369 Many projects have a "COPYING" file that stores the
3370 license information for all the source code files.
3371 This practice allows you to just track the "COPYING"
3372 file as long as it is kept up to date.
3373 <note><title>Tips</title>
3374 <itemizedlist>
3375 <listitem><para>
3376 If you specify an empty or invalid "md5"
3377 parameter,
3378 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
3379 returns an md5 mis-match
3380 error and displays the correct "md5" parameter
3381 value during the build.
3382 The correct parameter is also captured in
3383 the build log.
3384 </para></listitem>
3385 <listitem><para>
3386 If the whole file contains only license text,
3387 you do not need to use the "beginline" and
3388 "endline" parameters.
3389 </para></listitem>
3390 </itemizedlist>
3391 </note>
3392 </para>
3393 </section>
3394 </section>
3395
3396 <section id="enabling-commercially-licensed-recipes">
3397 <title>Enabling Commercially Licensed Recipes</title>
3398
3399 <para>
3400 By default, the OpenEmbedded build system disables
3401 components that have commercial or other special licensing
3402 requirements.
3403 Such requirements are defined on a
3404 recipe-by-recipe basis through the
3405 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
3406 variable definition in the affected recipe.
3407 For instance, the
3408 <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
3409 recipe contains the following statement:
3410 <literallayout class='monospaced'>
3411 LICENSE_FLAGS = "commercial"
3412 </literallayout>
3413 Here is a slightly more complicated example that contains both
3414 an explicit recipe name and version (after variable expansion):
3415 <literallayout class='monospaced'>
3416 LICENSE_FLAGS = "license_${PN}_${PV}"
3417 </literallayout>
3418 In order for a component restricted by a
3419 <filename>LICENSE_FLAGS</filename> definition to be enabled and
3420 included in an image, it needs to have a matching entry in the
3421 global
3422 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>
3423 variable, which is a variable typically defined in your
3424 <filename>local.conf</filename> file.
3425 For example, to enable the
3426 <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
3427 package, you could add either the string
3428 "commercial_gst-plugins-ugly" or the more general string
3429 "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>.
3430 See the
3431 "<link linkend='license-flag-matching'>License Flag Matching</link>"
3432 section for a full
3433 explanation of how <filename>LICENSE_FLAGS</filename> matching
3434 works.
3435 Here is the example:
3436 <literallayout class='monospaced'>
3437 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
3438 </literallayout>
3439 Likewise, to additionally enable the package built from the
3440 recipe containing
3441 <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>,
3442 and assuming that the actual recipe name was
3443 <filename>emgd_1.10.bb</filename>, the following string would
3444 enable that package as well as the original
3445 <filename>gst-plugins-ugly</filename> package:
3446 <literallayout class='monospaced'>
3447 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
3448 </literallayout>
3449 As a convenience, you do not need to specify the complete
3450 license string in the whitelist for every package.
3451 You can use an abbreviated form, which consists
3452 of just the first portion or portions of the license
3453 string before the initial underscore character or characters.
3454 A partial string will match any license that contains the
3455 given string as the first portion of its license.
3456 For example, the following whitelist string will also match
3457 both of the packages previously mentioned as well as any other
3458 packages that have licenses starting with "commercial" or
3459 "license".
3460 <literallayout class='monospaced'>
3461 LICENSE_FLAGS_WHITELIST = "commercial license"
3462 </literallayout>
3463 </para>
3464
3465 <section id="license-flag-matching">
3466 <title>License Flag Matching</title>
3467
3468 <para>
3469 License flag matching allows you to control what recipes
3470 the OpenEmbedded build system includes in the build.
3471 Fundamentally, the build system attempts to match
3472 <filename>LICENSE_FLAGS</filename> strings found in recipes
3473 against <filename>LICENSE_FLAGS_WHITELIST</filename>
3474 strings found in the whitelist.
3475 A match causes the build system to include a recipe in the
3476 build, while failure to find a match causes the build
3477 system to exclude a recipe.
3478 </para>
3479
3480 <para>
3481 In general, license flag matching is simple.
3482 However, understanding some concepts will help you
3483 correctly and effectively use matching.
3484 </para>
3485
3486 <para>
3487 Before a flag
3488 defined by a particular recipe is tested against the
3489 contents of the whitelist, the expanded string
3490 <filename>_${PN}</filename> is appended to the flag.
3491 This expansion makes each
3492 <filename>LICENSE_FLAGS</filename> value recipe-specific.
3493 After expansion, the string is then matched against the
3494 whitelist.
3495 Thus, specifying
3496 <filename>LICENSE_FLAGS = "commercial"</filename>
3497 in recipe "foo", for example, results in the string
3498 <filename>"commercial_foo"</filename>.
3499 And, to create a match, that string must appear in the
3500 whitelist.
3501 </para>
3502
3503 <para>
3504 Judicious use of the <filename>LICENSE_FLAGS</filename>
3505 strings and the contents of the
3506 <filename>LICENSE_FLAGS_WHITELIST</filename> variable
3507 allows you a lot of flexibility for including or excluding
3508 recipes based on licensing.
3509 For example, you can broaden the matching capabilities by
3510 using license flags string subsets in the whitelist.
3511 <note>
3512 When using a string subset, be sure to use the part of
3513 the expanded string that precedes the appended
3514 underscore character (e.g.
3515 <filename>usethispart_1.3</filename>,
3516 <filename>usethispart_1.4</filename>, and so forth).
3517 </note>
3518 For example, simply specifying the string "commercial" in
3519 the whitelist matches any expanded
3520 <filename>LICENSE_FLAGS</filename> definition that starts
3521 with the string "commercial" such as "commercial_foo" and
3522 "commercial_bar", which are the strings the build system
3523 automatically generates for hypothetical recipes named
3524 "foo" and "bar" assuming those recipes simply specify the
3525 following:
3526 <literallayout class='monospaced'>
3527 LICENSE_FLAGS = "commercial"
3528 </literallayout>
3529 Thus, you can choose to exhaustively
3530 enumerate each license flag in the whitelist and
3531 allow only specific recipes into the image, or
3532 you can use a string subset that causes a broader range of
3533 matches to allow a range of recipes into the image.
3534 </para>
3535
3536 <para>
3537 This scheme works even if the
3538 <filename>LICENSE_FLAGS</filename> string already
3539 has <filename>_${PN}</filename> appended.
3540 For example, the build system turns the license flag
3541 "commercial_1.2_foo" into "commercial_1.2_foo_foo" and
3542 would match both the general "commercial" and the specific
3543 "commercial_1.2_foo" strings found in the whitelist, as
3544 expected.
3545 </para>
3546
3547 <para>
3548 Here are some other scenarios:
3549 <itemizedlist>
3550 <listitem><para>
3551 You can specify a versioned string in the recipe
3552 such as "commercial_foo_1.2" in a "foo" recipe.
3553 The build system expands this string to
3554 "commercial_foo_1.2_foo".
3555 Combine this license flag with a whitelist that has
3556 the string "commercial" and you match the flag
3557 along with any other flag that starts with the
3558 string "commercial".
3559 </para></listitem>
3560 <listitem><para>
3561 Under the same circumstances, you can use
3562 "commercial_foo" in the whitelist and the build
3563 system not only matches "commercial_foo_1.2" but
3564 also matches any license flag with the string
3565 "commercial_foo", regardless of the version.
3566 </para></listitem>
3567 <listitem><para>
3568 You can be very specific and use both the
3569 package and version parts in the whitelist (e.g.
3570 "commercial_foo_1.2") to specifically match a
3571 versioned recipe.
3572 </para></listitem>
3573 </itemizedlist>
3574 </para>
3575 </section>
3576
3577 <section id="other-variables-related-to-commercial-licenses">
3578 <title>Other Variables Related to Commercial Licenses</title>
3579
3580 <para>
3581 Other helpful variables related to commercial
3582 license handling exist and are defined in the
3583 <filename>poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
3584 <literallayout class='monospaced'>
3585 COMMERCIAL_AUDIO_PLUGINS ?= ""
3586 COMMERCIAL_VIDEO_PLUGINS ?= ""
3587 </literallayout>
3588 If you want to enable these components, you can do so by
3589 making sure you have statements similar to the following
3590 in your <filename>local.conf</filename> configuration file:
3591 <literallayout class='monospaced'>
3592 COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
3593 gst-plugins-ugly-mpegaudioparse"
3594 COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
3595 gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
3596 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
3597 </literallayout>
3598 Of course, you could also create a matching whitelist
3599 for those components using the more general "commercial"
3600 in the whitelist, but that would also enable all the
3601 other packages with <filename>LICENSE_FLAGS</filename>
3602 containing "commercial", which you may or may not want:
3603 <literallayout class='monospaced'>
3604 LICENSE_FLAGS_WHITELIST = "commercial"
3605 </literallayout>
3606 </para>
3607
3608 <para>
3609 Specifying audio and video plug-ins as part of the
3610 <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and
3611 <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements
3612 (along with the enabling
3613 <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the
3614 plug-ins or components into built images, thus adding
3615 support for media formats or components.
3616 </para>
3617 </section>
3618 </section>
3619 </section>
3620</chapter> 3229</chapter>
3621<!-- 3230<!--
3622vim: expandtab tw=80 ts=4 3231vim: expandtab tw=80 ts=4
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index e64b0d5ca9..fc667ba03e 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -7994,8 +7994,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
7994 <link linkend='var-LICENSE'><filename>LICENSE</filename></link> 7994 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
7995 is set to "CLOSED").</para> 7995 is set to "CLOSED").</para>
7996 <para>For more information, see the 7996 <para>For more information, see the
7997 "<ulink url='&YOCTO_DOCS_OM_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" 7997 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
7998 section in the Yocto Project Overview and Concepts Manual. 7998 section in the Yocto Project Development Tasks Manual.
7999 </para> 7999 </para>
8000 </glossdef> 8000 </glossdef>
8001 </glossentry> 8001 </glossentry>
@@ -8130,8 +8130,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
8130 require additional licenses in order to be used in a 8130 require additional licenses in order to be used in a
8131 commercial product. 8131 commercial product.
8132 For more information, see the 8132 For more information, see the
8133 "<ulink url='&YOCTO_DOCS_OM_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>" 8133 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
8134 section in the Yocto Project Overview and Concepts Manual. 8134 section in the Yocto Project Development Tasks Manual.
8135 </para> 8135 </para>
8136 </glossdef> 8136 </glossdef>
8137 </glossentry> 8137 </glossentry>
@@ -8150,8 +8150,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
8150 This practice is otherwise known as "whitelisting" 8150 This practice is otherwise known as "whitelisting"
8151 license flags. 8151 license flags.
8152 For more information, see the 8152 For more information, see the
8153 <ulink url='&YOCTO_DOCS_OM_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>" 8153 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
8154 section in the Yocto Project Overview and Concepts Manual. 8154 section in the Yocto Project Development Tasks Manual.
8155 </para> 8155 </para>
8156 </glossdef> 8156 </glossdef>
8157 </glossentry> 8157 </glossentry>