sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

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>
This commit is contained in:
Scott Rifenbark 2012-01-04 10:15:21 -06:00 committed by Richard Purdie
parent 40f44ec529
commit 01d5729e13
2 changed files with 160 additions and 107 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
documentation/poky-ref-manual/extendpoky.xml
View File

@ -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>

159
documentation/poky-ref-manual/technical-details.xml
View File

@ -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