summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-common-tasks.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml793
1 files changed, 591 insertions, 202 deletions
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