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:
parent
40f44ec529
commit
01d5729e13
|
@ -9,8 +9,7 @@
|
||||||
software packages, extending or customizing images or porting the Yocto Project to
|
software packages, extending or customizing images or porting the Yocto Project to
|
||||||
new hardware (adding a new machine).
|
new hardware (adding a new machine).
|
||||||
The chapter also describes ways to modify package source code, combine multiple
|
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
|
versions of library files into a single image, and handle a package name alias.
|
||||||
a package name alias.
|
|
||||||
Finally, the chapter contains advice about how to make changes to the
|
Finally, the chapter contains advice about how to make changes to the
|
||||||
Yocto Project to achieve the best results.
|
Yocto Project to achieve the best results.
|
||||||
</para>
|
</para>
|
||||||
|
@ -919,111 +918,6 @@
|
||||||
</section>
|
</section>
|
||||||
</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">
|
<section id="usingpoky-configuring-DISTRO_PN_ALIAS">
|
||||||
<title>Handling a Package Name Alias</title>
|
<title>Handling a Package Name Alias</title>
|
||||||
<para>
|
<para>
|
||||||
|
|
|
@ -568,6 +568,165 @@
|
||||||
</section>
|
</section>
|
||||||
</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>
|
</chapter>
|
||||||
<!--
|
<!--
|
||||||
vim: expandtab tw=80 ts=4
|
vim: expandtab tw=80 ts=4
|
||||||
|
|
Loading…
Reference in New Issue