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:
parent
30cdf93d0c
commit
cf6887d914
|
@ -902,7 +902,19 @@
|
|||
<title>License Flag Matching</title>
|
||||
|
||||
<para>
|
||||
In general, license flag matching is simple.
|
||||
License flag matching allows you to control what recipes the
|
||||
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.
|
||||
</para>
|
||||
|
@ -910,33 +922,31 @@
|
|||
<para>
|
||||
Before a flag
|
||||
defined by a particular recipe is tested against the
|
||||
contents of the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, the
|
||||
expanded string <filename>_${PN}</filename> is
|
||||
appended to the flag.
|
||||
contents of the whitelist, the expanded string
|
||||
<filename>_${PN}</filename> is appended to the flag.
|
||||
This expansion makes each <filename>LICENSE_FLAGS</filename>
|
||||
value recipe-specific.
|
||||
After expansion, the string is then matched against the
|
||||
whitelist.
|
||||
Thus, specifying <filename>LICENSE_FLAGS = "commercial"</filename>
|
||||
in recipe "foo" for example, results in the string
|
||||
Thus, specifying
|
||||
<filename>LICENSE_FLAGS = "commercial"</filename>
|
||||
in recipe "foo", for example, results in the string
|
||||
<filename>"commercial_foo"</filename>.
|
||||
And that string would normally be appears in the whitelist
|
||||
in order for a match to occur.
|
||||
And, to create a match, that string must appear in the
|
||||
whitelist.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Judicious use of the <filename>LICENSE_FLAGS</filename>
|
||||
strings and the contents of the
|
||||
<filename>LICENSE_FLAGS_WHITELIST</filename> variable
|
||||
allows you a lot of flexibility for matching license
|
||||
flags.
|
||||
allows you a lot of flexibility for including or excluding
|
||||
recipes based on licensing.
|
||||
For example, you can broaden the matching capabilities by
|
||||
using string subsets from the <filename>LICENSE_FLAGS</filename>
|
||||
variables in the whitelist.
|
||||
<note>Be sure to use the part of the expanded
|
||||
string that precedes
|
||||
the underscore character (e.g.
|
||||
<filename>usethispart_1.3</filename>,
|
||||
using license flags string subsets in the whitelist.
|
||||
<note>When using a string subset, be sure to use the part of
|
||||
the expanded string that precedes the appended underscore
|
||||
character (e.g. <filename>usethispart_1.3</filename>,
|
||||
<filename>usethispart_1.4</filename>, and so forth).
|
||||
</note>
|
||||
For example, simply specifying the string "commercial" in
|
||||
|
@ -950,46 +960,46 @@
|
|||
<literallayout class='monospaced'>
|
||||
LICENSE_FLAGS = "commercial"
|
||||
</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>
|
||||
Judicious use of the strings with the
|
||||
<filename>LICENSE_FLAGS</filename> variable and the Broadening the match allows for a range of specificity for the
|
||||
items in the whitelist, from more general to perfectly
|
||||
specific.
|
||||
So you have the choice of exhaustively
|
||||
enumerating each license flag in the whitelist to
|
||||
allow only those specific recipes into the image, or
|
||||
of using a more general string to pick up anything
|
||||
matching just the first component or components of the specified
|
||||
string.
|
||||
This scheme works even if the
|
||||
<filename>LICENSE_FLAG</filename> string already
|
||||
has <filename>_${PN}</filename> appended.
|
||||
For example, the build system turns the license flag
|
||||
"commercial_1.2_foo" into "commercial_1.2_foo_foo" and would
|
||||
match both the general "commercial" and the specific
|
||||
"commercial_1.2_foo" strings found in the whitelist, as
|
||||
expected.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This scheme works even if the flag already
|
||||
has <filename>_${PN}</filename> appended - the extra <filename>_${PN}</filename> is
|
||||
redundant, but does not affect the outcome.
|
||||
For example, a license flag of "commercial_1.2_foo" would
|
||||
turn into "commercial_1.2_foo_foo" and would match
|
||||
both the general "commercial" and the specific
|
||||
"commercial_1.2_foo", as expected.
|
||||
The flag would also match
|
||||
"commercial_1.2_foo_foo" and "commercial_1.2", which
|
||||
does not make much sense regarding use in the whitelist.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For a versioned string, you could instead specify
|
||||
"commercial_foo_1.2", which would turn into
|
||||
"commercial_foo_1.2_foo".
|
||||
And, as expected, this flag allows
|
||||
you to pick up this package along with
|
||||
anything else "commercial" when you specify "commercial"
|
||||
in the whitelist.
|
||||
Or, the flag allows you to pick up this package along with anything "commercial_foo"
|
||||
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.
|
||||
Here are some other scenarios:
|
||||
<itemizedlist>
|
||||
<listitem><para>You can specify a versioned string in the
|
||||
recipe such as "commercial_foo_1.2" in a "foo" recipe.
|
||||
The build system expands this string to
|
||||
"commercial_foo_1.2_foo".
|
||||
Combine this license flag with a whitelist that has
|
||||
the string "commercial" and you match the flag along
|
||||
with any other flag that starts with the string
|
||||
"commercial".</para></listitem>
|
||||
<listitem><para>Under the same circumstances, you can
|
||||
use "commercial_foo" in the whitelist and the
|
||||
build system not only matches "commercial_foo_1.2" but
|
||||
also matches any license flag with the string
|
||||
"commercial_foo", regardless of the version.
|
||||
</para></listitem>
|
||||
<listitem><para>You can be very specific and use both the
|
||||
package and version parts in the whitelist (e.g.
|
||||
"commercial_foo_1.2") to specifically match a
|
||||
versioned recipe.</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
|
|
Loading…
Reference in New Issue