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