From cf6887d91485ffbf6f94978627296234a2d37a5f Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 27 Mar 2013 08:11:41 -0700 Subject: [PATCH] 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 Signed-off-by: Richard Purdie --- .../ref-manual/technical-details.xml | 156 ++++++++++-------- 1 file changed, 83 insertions(+), 73 deletions(-) diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml index d66d7050a1..58a6b53744 100644 --- a/documentation/ref-manual/technical-details.xml +++ b/documentation/ref-manual/technical-details.xml @@ -7,7 +7,7 @@ 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. @@ -17,7 +17,7 @@ The BitBake task executor together with various types of configuration files form the 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. @@ -126,8 +126,8 @@ Classes - Class files (.bbclass) contain information that - is useful to share between + Class files (.bbclass) contain information that + is useful to share between Metadata files. An example is the Autotools class, which contains 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 code. 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 Build Directory. The checksum (or signature) for a particular task needs to add the hashes of all the tasks on which the particular task depends. @@ -366,7 +366,7 @@ The "OEBasicHash" BB_SIGNATURE_HANDLER is the same as the "OEBasic" version but adds the task hash to the stamp files. - This results in any + This results in any Metadata change that changes the task hash, automatically causing the task to be run again. @@ -543,7 +543,7 @@ information in the file. If you specify two files, BitBake compares the two files and dumps out 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?" @@ -560,9 +560,9 @@ into the checksum calculation, but do affect a task's output. A good example is perhaps when a tool changes its output. Assume that the output of rpmdeps needed to change. - The result of the change should be that all the + The result of the change should be that all the package, package_write_rpm, - and package_deploy-rpm shared state cache + and package_deploy-rpm shared state cache items would become invalid. 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. @@ -780,8 +780,8 @@ of S. - Note that LIC_FILES_CHKSUM variable is - mandatory for all recipes, unless the + Note that LIC_FILES_CHKSUM variable is + mandatory for all recipes, unless the LICENSE variable is set to "CLOSED". @@ -902,94 +902,104 @@ License Flag Matching - In general, license flag matching is simple. - However, understanding some concepts will help you + License flag matching allows you to control what recipes the + OpenEmbedded build system includes in the build. + Fundamentally, the build system attempts to match + LICENSE_FLAG strings found in + recipes against LICENSE_FLAGS_WHITELIST + 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. + + + + In general, license flag matching is simple. + However, understanding some concepts will help you correctly and effectively use matching. Before a flag defined by a particular recipe is tested against the - contents of the LICENSE_FLAGS_WHITELIST variable, the - expanded string _${PN} is - appended to the flag. - This expansion makes each LICENSE_FLAGS + contents of the whitelist, the expanded string + _${PN} is appended to the flag. + This expansion makes each LICENSE_FLAGS value recipe-specific. - After expansion, the string is then matched against the + After expansion, the string is then matched against the whitelist. - Thus, specifying LICENSE_FLAGS = "commercial" - in recipe "foo" for example, results in the string + Thus, specifying + LICENSE_FLAGS = "commercial" + in recipe "foo", for example, results in the string "commercial_foo". - 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. - Judicious use of the LICENSE_FLAGS - strings and the contents of the + Judicious use of the LICENSE_FLAGS + strings and the contents of the LICENSE_FLAGS_WHITELIST variable - allows you a lot of flexibility for matching license - flags. - For example, you can broaden the matching capabilities by - using string subsets from the LICENSE_FLAGS - variables in the whitelist. - Be sure to use the part of the expanded - string that precedes - the underscore character (e.g. - usethispart_1.3, + allows you a lot of flexibility for including or excluding + recipes based on licensing. + For example, you can broaden the matching capabilities by + using license flags string subsets in the whitelist. + When using a string subset, be sure to use the part of + the expanded string that precedes the appended underscore + character (e.g. usethispart_1.3, usethispart_1.4, and so forth). For example, simply specifying the string "commercial" in - the whitelist matches any expanded - LICENSE_FLAGS definition that starts with - the string "commercial" such as "commercial_foo" and - "commercial_bar", which are the strings the build system + the whitelist matches any expanded + LICENSE_FLAGS definition that starts with + the string "commercial" such as "commercial_foo" and + "commercial_bar", which are the strings the build system 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: LICENSE_FLAGS = "commercial" + 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. - Judicious use of the strings with the - LICENSE_FLAGS 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 + LICENSE_FLAG string already + has _${PN} 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. - This scheme works even if the flag already - has _${PN} appended - the extra _${PN} 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. - - - - 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: + + 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". + 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. + + 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. + @@ -1006,7 +1016,7 @@ COMMERCIAL_QT = "" 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 local.conf configuration file: COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \