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 --- .../poky-ref-manual/technical-details.xml | 159 +++++++++++++++++++++ 1 file changed, 159 insertions(+) (limited to 'documentation/poky-ref-manual/technical-details.xml') 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. + +
+