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

ref-manual: rewrite of license flags matching section. 

This whole section was very complicated and difficult to follow.
I have rewritten it to clear it up.

(From yocto-docs rev: 6ad1828eaa3e91b850696590cc732485a52f4cb6)

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 2013-03-27 08:11:41 -07:00 committed by Richard Purdie
parent 30cdf93d0c
commit cf6887d914
1 changed files with 83 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

156
documentation/ref-manual/technical-details.xml
View File

@ -7,7 +7,7 @@
<para> <para>
This chapter provides technical details for various parts of the Yocto Project. This chapter provides technical details for various parts of the Yocto Project.
Currently, topics include Yocto Project components, Currently, topics include Yocto Project components,
shared state (sstate) cache, x32, and Licenses. shared state (sstate) cache, x32, and Licenses.
</para> </para>
@ -17,7 +17,7 @@
<para> <para>
The BitBake task executor together with various types of configuration files form the The BitBake task executor together with various types of configuration files form the
OpenEmbedded Core. OpenEmbedded Core.
This section overviews these by describing what they are used for This section overviews these by describing what they are used for
and how they interact. and how they interact.
</para> </para>
@ -126,8 +126,8 @@
<title>Classes</title> <title>Classes</title>
<para> <para>
Class files (<filename>.bbclass</filename>) contain information that Class files (<filename>.bbclass</filename>) contain information that
is useful to share between is useful to share between
<ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> files. <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> files.
An example is the Autotools class, which contains An example is the Autotools class, which contains
common settings for any application that Autotools uses. common settings for any application that Autotools uses.
@ -319,7 +319,7 @@
Information based on direct inputs is referred to as the "basehash" in the Information based on direct inputs is referred to as the "basehash" in the
code. code.
However, there is still the question of a task's indirect inputs - the However, there is still the question of a task's indirect inputs - the
things that were already built and present in the things that were already built and present in the
<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
The checksum (or signature) for a particular task needs to add the hashes The checksum (or signature) for a particular task needs to add the hashes
of all the tasks on which the particular task depends. of all the tasks on which the particular task depends.
@ -366,7 +366,7 @@
</literallayout> </literallayout>
The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> is the same as the The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> is the same as the
"OEBasic" version but adds the task hash to the stamp files. "OEBasic" version but adds the task hash to the stamp files.
This results in any This results in any
<ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
change that changes the task hash, automatically change that changes the task hash, automatically
causing the task to be run again. causing the task to be run again.
@ -543,7 +543,7 @@
information in the file. information in the file.
If you specify two files, BitBake compares the two files and dumps out If you specify two files, BitBake compares the two files and dumps out
the differences between the two. the differences between the two.
This more easily helps answer the question of "What This more easily helps answer the question of "What
changed between X and Y?"</para></listitem> changed between X and Y?"</para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
@ -560,9 +560,9 @@
into the checksum calculation, but do affect a task's output. into the checksum calculation, but do affect a task's output.
A good example is perhaps when a tool changes its output. A good example is perhaps when a tool changes its output.
Assume that the output of <filename>rpmdeps</filename> needed to change. Assume that the output of <filename>rpmdeps</filename> needed to change.
The result of the change should be that all the The result of the change should be that all the
<filename>package</filename>, <filename>package_write_rpm</filename>, <filename>package</filename>, <filename>package_write_rpm</filename>,
and <filename>package_deploy-rpm</filename> shared state cache and <filename>package_deploy-rpm</filename> shared state cache
items would become invalid. items would become invalid.
But, because this is a change that is external to the code and therefore implicit, But, because this is a change that is external to the code and therefore implicit,
the associated shared state cache items do not become invalidated. the associated shared state cache items do not become invalidated.
@ -780,8 +780,8 @@
of <filename><link linkend='var-S'>S</link></filename>. of <filename><link linkend='var-S'>S</link></filename>.
</para> </para>
<para> <para>
Note that <filename>LIC_FILES_CHKSUM</filename> variable is Note that <filename>LIC_FILES_CHKSUM</filename> variable is
mandatory for all recipes, unless the mandatory for all recipes, unless the
<filename>LICENSE</filename> variable is set to "CLOSED". <filename>LICENSE</filename> variable is set to "CLOSED".
</para> </para>
</section> </section>
@ -902,94 +902,104 @@
<title>License Flag Matching</title> <title>License Flag Matching</title>
<para> <para>
In general, license flag matching is simple. License flag matching allows you to control what recipes the
However, understanding some concepts will help you OpenEmbedded build system includes in the build.
Fundamentally, the build system attempts to match
<filename>LICENSE_FLAG</filename> strings found in
recipes against <filename>LICENSE_FLAGS_WHITELIST</filename>
strings found in the whitelist.
A match, causes the build system to include a recipe in the
build, while failure to find a match causes the build system to
exclued a recipe.
</para>
<para>
In general, license flag matching is simple.
However, understanding some concepts will help you
correctly and effectively use matching. correctly and effectively use matching.
</para> </para>
<para> <para>
Before a flag Before a flag
defined by a particular recipe is tested against the defined by a particular recipe is tested against the
contents of the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, the contents of the whitelist, the expanded string
expanded string <filename>_${PN}</filename> is <filename>_${PN}</filename> is appended to the flag.
appended to the flag. This expansion makes each <filename>LICENSE_FLAGS</filename>
This expansion makes each <filename>LICENSE_FLAGS</filename>
value recipe-specific. value recipe-specific.
After expansion, the string is then matched against the After expansion, the string is then matched against the
whitelist. whitelist.
Thus, specifying <filename>LICENSE_FLAGS = "commercial"</filename> Thus, specifying
in recipe "foo" for example, results in the string <filename>LICENSE_FLAGS = "commercial"</filename>
in recipe "foo", for example, results in the string
<filename>"commercial_foo"</filename>. <filename>"commercial_foo"</filename>.
And that string would normally be appears in the whitelist And, to create a match, that string must appear in the
in order for a match to occur. whitelist.
</para> </para>
<para> <para>
Judicious use of the <filename>LICENSE_FLAGS</filename> Judicious use of the <filename>LICENSE_FLAGS</filename>
strings and the contents of the strings and the contents of the
<filename>LICENSE_FLAGS_WHITELIST</filename> variable <filename>LICENSE_FLAGS_WHITELIST</filename> variable
allows you a lot of flexibility for matching license allows you a lot of flexibility for including or excluding
flags. recipes based on licensing.
For example, you can broaden the matching capabilities by For example, you can broaden the matching capabilities by
using string subsets from the <filename>LICENSE_FLAGS</filename> using license flags string subsets in the whitelist.
variables in the whitelist. <note>When using a string subset, be sure to use the part of
<note>Be sure to use the part of the expanded the expanded string that precedes the appended underscore
string that precedes character (e.g. <filename>usethispart_1.3</filename>,
the underscore character (e.g.
<filename>usethispart_1.3</filename>,
<filename>usethispart_1.4</filename>, and so forth). <filename>usethispart_1.4</filename>, and so forth).
</note> </note>
For example, simply specifying the string "commercial" in For example, simply specifying the string "commercial" in
the whitelist matches any expanded the whitelist matches any expanded
<filename>LICENSE_FLAGS</filename> definition that starts with <filename>LICENSE_FLAGS</filename> definition that starts with
the string "commercial" such as "commercial_foo" and the string "commercial" such as "commercial_foo" and
"commercial_bar", which are the strings the build system "commercial_bar", which are the strings the build system
automatically generates for hypothetical recipes named automatically generates for hypothetical recipes named
"foo" and "bar" assuming those recipes simply specify the "foo" and "bar" assuming those recipes simply specify the
following: following:
<literallayout class='monospaced'> <literallayout class='monospaced'>
LICENSE_FLAGS = "commercial" LICENSE_FLAGS = "commercial"
</literallayout> </literallayout>
Thus, you can choose to exhaustively
enumerate each license flag in the whitelist and
allow only specific recipes into the image, or
you can use a string subset that causes a broader range of
matches to allow a range of recipes into the image.
</para> </para>
<para> <para>
Judicious use of the strings with the This scheme works even if the
<filename>LICENSE_FLAGS</filename> variable and the Broadening the match allows for a range of specificity for the <filename>LICENSE_FLAG</filename> string already
items in the whitelist, from more general to perfectly has <filename>_${PN}</filename> appended.
specific. For example, the build system turns the license flag
So you have the choice of exhaustively "commercial_1.2_foo" into "commercial_1.2_foo_foo" and would
enumerating each license flag in the whitelist to match both the general "commercial" and the specific
allow only those specific recipes into the image, or "commercial_1.2_foo" strings found in the whitelist, as
of using a more general string to pick up anything expected.
matching just the first component or components of the specified
string.
</para> </para>
<para> <para>
This scheme works even if the flag already Here are some other scenarios:
has <filename>_${PN}</filename> appended - the extra <filename>_${PN}</filename> is <itemizedlist>
redundant, but does not affect the outcome. <listitem><para>You can specify a versioned string in the
For example, a license flag of "commercial_1.2_foo" would recipe such as "commercial_foo_1.2" in a "foo" recipe.
turn into "commercial_1.2_foo_foo" and would match The build system expands this string to
both the general "commercial" and the specific "commercial_foo_1.2_foo".
"commercial_1.2_foo", as expected. Combine this license flag with a whitelist that has
The flag would also match the string "commercial" and you match the flag along
"commercial_1.2_foo_foo" and "commercial_1.2", which with any other flag that starts with the string
does not make much sense regarding use in the whitelist. "commercial".</para></listitem>
</para> <listitem><para>Under the same circumstances, you can
use "commercial_foo" in the whitelist and the
<para> build system not only matches "commercial_foo_1.2" but
For a versioned string, you could instead specify also matches any license flag with the string
"commercial_foo_1.2", which would turn into "commercial_foo", regardless of the version.
"commercial_foo_1.2_foo". </para></listitem>
And, as expected, this flag allows <listitem><para>You can be very specific and use both the
you to pick up this package along with package and version parts in the whitelist (e.g.
anything else "commercial" when you specify "commercial" "commercial_foo_1.2") to specifically match a
in the whitelist. versioned recipe.</para></listitem>
Or, the flag allows you to pick up this package along with anything "commercial_foo" </itemizedlist>
regardless of version when you use "commercial_foo" in the whitelist.
Finally, you can be completely specific about the package and version and specify
"commercial_foo_1.2" package and version.
</para> </para>
</section> </section>
@ -1006,7 +1016,7 @@
COMMERCIAL_QT = "" COMMERCIAL_QT = ""
</literallayout> </literallayout>
If you want to enable these components, you can do so by making sure you have If you want to enable these components, you can do so by making sure you have
statements similar to the following statements similar to the following
in your <filename>local.conf</filename> configuration file: in your <filename>local.conf</filename> configuration file:
<literallayout class='monospaced'> <literallayout class='monospaced'>
COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \ COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \