From 01d5729e13b8688b7238bf763dfd808df5808005 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 4 Jan 2012 10:15:21 -0600 Subject: 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 Signed-off-by: Richard Purdie --- documentation/poky-ref-manual/extendpoky.xml | 108 +------------- .../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. @@ -919,111 +918,6 @@ -
- Tracking License Changes - - - The license of an upstream project might change in the future. In order to prevent these changes - going unnoticed, the Yocto Project provides a - LIC_FILES_CHKSUM - 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. - - -
- Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable - - - The LIC_FILES_CHKSUM - variable contains checksums of the license text in the source code for the recipe. - Following is an example of how to specify LIC_FILES_CHKSUM: - - LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ - file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ - file://licfile2.txt;endline=50;md5=zzzz \ - ..." - - - - - The Yocto Project uses the - S variable as the - default directory used when searching files listed in - LIC_FILES_CHKSUM. - The previous example employs the default directory. - - - - You can also use relative paths as shown in the following example: - - LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\ - md5=bb14ed3c4cda583abc85401304b5cd4e" - LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6" - - - - - In this example, the first line locates a file in - S/src/ls.c. - The second line refers to a file in - WORKDIR, which is the parent - of S. - - - Note that this variable is mandatory for all recipes, unless the - LICENSE variable is set to "CLOSED". - -
- -
- Explanation of Syntax - - As mentioned in the previous section, the - LIC_FILES_CHKSUM 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. - - - - 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. - - - - There is no limit to how many files you can specify using the - LIC_FILES_CHKSUM 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. - - - - 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. - - - - If the whole file contains only license text, you do not need to use the "beginline" and - "endline" parameters. - -
-
-
Handling a Package Name Alias 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 @@
+
+ Licenses + + + 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. + + +
+ Tracking License Changes + + + The license of an upstream project might change in the future. In order to prevent these changes + going unnoticed, the Yocto Project provides a + LIC_FILES_CHKSUM + 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. + + +
+ Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable + + + The LIC_FILES_CHKSUM + variable contains checksums of the license text in the source code for the recipe. + Following is an example of how to specify LIC_FILES_CHKSUM: + + LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ + file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ + file://licfile2.txt;endline=50;md5=zzzz \ + ..." + + + + + The Yocto Project uses the + S variable as the + default directory used when searching files listed in + LIC_FILES_CHKSUM. + The previous example employs the default directory. + + + + You can also use relative paths as shown in the following example: + + LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\ + md5=bb14ed3c4cda583abc85401304b5cd4e" + LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6" + + + + + In this example, the first line locates a file in + S/src/ls.c. + The second line refers to a file in + WORKDIR, which is the parent + of S. + + + Note that this variable is mandatory for all recipes, unless the + LICENSE variable is set to "CLOSED". + +
+ +
+ Explanation of Syntax + + As mentioned in the previous section, the + LIC_FILES_CHKSUM 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. + + + + 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. + + + + There is no limit to how many files you can specify using the + LIC_FILES_CHKSUM 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. + + + + 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. + + + + If the whole file contains only license text, you do not need to use the "beginline" and + "endline" parameters. + +
+
+ +
+ Enabling Commercially Licensed Recipes + + + By default, the Yocto Project build system disables components that + have commercial licensing requirements. + The following four statements in the + $HOME/poky/meta/conf/distro/poky.conf file + disable components: + + COMMERCIAL_LICENSE ?= "lame gst-fluendo-mp3 libmad mpeg2dec ffmpeg qmmp" + COMMERCIAL_AUDIO_PLUGINS ?= "" + COMMERCIAL_VIDEO_PLUGINS ?= "" + COMMERCIAL_QT ?= "qmmp" + + + + + If you want to enable these components, you can do so by making sure you have + the following statements in the configuration file: + + 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 = "" + + + + + Excluding a package name from the + COMMERCIAL_LICENSE or + COMMERCIAL_QT statement enables that package. + + + + Specifying audio and video plug-ins as part of the + COMMERCIAL_AUDIO_PLUGINS and + COMMERCIAL_VIDEO_PLUGINS statements includes + the plug-ins into built images - thus adding support for media formats. + +
+