diff --git a/documentation/poky-ref-manual/technical-details.xml b/documentation/poky-ref-manual/technical-details.xml index 19ce9ab224..b0c0f4659e 100644 --- a/documentation/poky-ref-manual/technical-details.xml +++ b/documentation/poky-ref-manual/technical-details.xml @@ -685,44 +685,190 @@ Enabling Commercially Licensed Recipes - By default, the Yocto Project build system disables components that - have commercial licensing requirements. - The following four statements in the - $HOME/poky/meta/conf/distro/poky.conf file - disable components: + By default, the Yocto Project build system disables + components that have commercial or other special licensing + requirements. + Such requirements are defined on a + recipe-by-recipe basis through the LICENSE_FLAGS variable + definition in the affected recipe. + For instance, the + $HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly + recipe contains the following statement: - COMMERCIAL_LICENSE ?= "lame gst-fluendo-mp3 libmad mpeg2dec ffmpeg qmmp" + LICENSE_FLAGS = "commercial" + + This next example shows a recipe in another layer: + + LICENSE_FLAGS = "license_${PN}_${PV}" + + In order for a component restricted by a LICENSE_FLAGS + definition to be enabled and included in an image, it + needs to have a matching entry in the global + LICENSE_FLAGS_WHITELIST variable, which is a variable + typically defined in your local.conf file. + For example, to enable + the $HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly + package, you could add either the string + "commercial_gst-plugins-ugly" or the more general string + "commercial" to LICENSE_FLAGS_WHITELIST. + See the + "License Flag Matching" section + for a full explanation of how LICENSE_FLAGS matching works. + Here is the example: + + LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly" + + Likewise, to additionally enable the package containing + LICENSE_FLAGS = "license_${PN}_${PV}", and assuming + that the actual recipe name was emgd_1.10.bb, + the following string would enable that package as well as + the original gst-plugins-ugly package: + + LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10" + + As a convenience, you do not need to specify the complete license string + in the whitelist for every package. + you can use an abbreviated form, which consists + of just the first portion or portions of the license string before + the initial underscore character or characters. + A partial string will match + any license that contains the given string as the first + portion of its license. + For example, the following + whitelist string will also match both of the packages + previously mentioned as well as any other packages that have + licenses starting with "commercial" or "license". + + LICENSE_FLAGS_WHITELIST = "commercial license" + + + +
+ License Flag Matching + + + The definition of 'matching' in reference to a + recipe's LICENSE_FLAGS setting is simple. + However, some things exist that you should know about in order to + correctly and effectively use it. + + + + Before a flag + defined by a particular recipe is tested against the + contents of the LICENSE_FLAGS_WHITELIST variable, the + string _${PN} (with + PN expanded of course) is + appended to the flag, thus automatically making each + LICENSE_FLAGS value recipe-specific. + That string is + then matched against the whitelist. + So if you specify LICENSE_FLAGS = "commercial" in recipe + "foo" for example, the string "commercial_foo" + would normally be what is specified in the whitelist in order for it to + match. + + + + You can broaden the match by + putting any "_"-separated beginning subset of a + LICENSE_FLAGS flag in the whitelist, which will also + match. + For example, simply specifying "commercial" in + the whitelist would match any expanded LICENSE_FLAGS + definition starting with "commercial" such as + "commercial_foo" and "commercial_bar", which are the + strings that would be automatically generated for + hypothetical "foo" and "bar" recipes assuming those + recipes had simply specified the following: + + LICENSE_FLAGS = "commercial" + + + + + 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 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.1" package and version. + +
+ +