[yocto] [PATCH 1/2] documentation/poky-ref-manual/technical-details.xml: update 'Enabling Commercially Licensed Recipes' section
tom.zanussi at intel.com
tom.zanussi at intel.com
Tue Mar 20 20:41:49 PDT 2012
From: Tom Zanussi <tom.zanussi at intel.com>
The COMMERCIAL_LICENSE mechanism has been removed in Yocto 1.2 and
replaced by an equivalent mechanism, LICENSE_FLAGS. Update the
documentation to reflect the change.
Also update and fix a couple inaccuracies in a couple related
variables (COMMERCIAL_QT, etc).
Signed-off-by: Tom Zanussi <tom.zanussi at intel.com>
---
.../poky-ref-manual/technical-details.xml | 189 ++++++++++++++++----
1 files changed, 155 insertions(+), 34 deletions(-)
diff --git a/documentation/poky-ref-manual/technical-details.xml b/documentation/poky-ref-manual/technical-details.xml
index 19ce9ab..a1669f1 100644
--- a/documentation/poky-ref-manual/technical-details.xml
+++ b/documentation/poky-ref-manual/technical-details.xml
@@ -685,44 +685,165 @@
<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:
+ 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 via a LICENSE_FLAGS variable
+ definition in the affected recipe. For instance, the
+ <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
+ recipe contains the statement:
<literallayout class='monospaced'>
- COMMERCIAL_LICENSE ?= "lame gst-fluendo-mp3 libmad mpeg2dec ffmpeg qmmp"
- COMMERCIAL_AUDIO_PLUGINS ?= ""
- COMMERCIAL_VIDEO_PLUGINS ?= ""
- COMMERCIAL_QT ?= "qmmp"
+ LICENSE_FLAGS = "commercial"
</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:
+ Another example would be the following from a recipe in another layer:
<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 = ""
+ LICENSE_FLAGS = "license_${PN}_${PV}"
</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>
+ 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 instance,
+ to enable
+ the <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
+ package, you could add either the string
+ "commercial_gst-plugins-ugly" or the more general
+ "commercial" to LICENSE_FLAGS_WHITELIST (see section
+ 3.3.2.1 for a full explanation of LICENSE_FLAGS matching):
+ <literallayout class='monospaced'>
+ LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
+ </literallayout>
+ Likewise, to additionally enable the package containing
+ LICENSE_FLAGS = "license_${PN}_${PV}", and assuming for
+ example 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:
+ <literallayout class='monospaced'>
+ LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
+ </literallayout>
+ As a convenience to the user, the complete license string
+ doesn't need to be specified in the whitelist for every
+ package - an abbreviated form can be used, which consists
+ of just the first portion(s) of the license string before
+ the initial underscore(s). 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
+ mentioned above (as well as any other packages that have
+ licenses starting with "commercial" or "license").
+ <literallayout class='monospaced'>
+ LICENSE_FLAGS_WHITELIST = "commercial license"
+ </literallayout>
+ <section id="enabling-commercially-licensed-recipes-matching">
+ <title>Explanation of how LICENSE_FLAGS matching works</title>
+ <para>
+ The definition of 'matching' in reference to a
+ recipe's LICENSE_FLAGS setting is simple, but there
+ are a couple things users need to know 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 the user
+ specifies LICENSE_FLAGS = 'commercial' in recipe
+ 'foo', the string 'commercial_foo' would normally be
+ what is specified in the whitelist in order for it to
+ match.
+ </para>
+ <para>
+ However, the user can also 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 LICENSE_FLAGS =
+ 'commercial'.
+ </para>
+ <para>
+ This allows for a range of specificity for the items
+ in the whitelist, from more general to perfectly
+ specific. So users 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(s) of the specified
+ string.
+ </para>
+ <para>
+ Note that this scheme works even if the flag already
+ has '_${PN}' appended - the extra '_${PN}' is
+ redundant, but doesn't 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 (it would also match
+ commercial_1.2_foo_foo' and 'commercial_1.2', which
+ don't make much sense as far as something a user would
+ think of specifying in the whitelist). For a
+ versioned string, the user could instead specify
+ 'commercial_foo_1.2', which would turn into
+ 'commercial_foo_1.2_foo', but which would as expected
+ allow the user to pick up this package along with
+ anything else 'commercial' by specifying 'commercial'
+ in the whitelist, or anything with a 'commercial_foo'
+ license regardless of version by using
+ 'commercial_foo' in the whitelist, or
+ 'commercial_foo_1.1' to be completely specific about
+ package and version.
+ </para>
+ </section>
+ </para>
+ <para>
+ <section id="enabling-commercially-licensed-recipes-helpers">
+ <title>Other Variables Related to Commercial Licenses</title>
+ <para>
+ There are a few other variables related to commercial
+ license handling defined in the
+ <filename>$HOME/poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
+ <literallayout class='monospaced'>
+ COMMERCIAL_AUDIO_PLUGINS ?= ""
+ COMMERCIAL_VIDEO_PLUGINS ?= ""
+ COMMERCIAL_QT = ""
+ </literallayout>
+ </para>
+ <para>
+ If you want to enable these components, you can do so by making sure you have
+ the following statements in your local.conf 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_QT ?= "qmmp"
+ LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
+ </literallayout>
+ Of course, you could also create a matching whitelist
+ for those components using the more general "commercial"
+ in the whitelist, but that would also enable all the
+ other packages with LICENSE_FLAGS containing
+ "commercial", which you may or may not want:
+ <literallayout class='monospaced'>
+ LICENSE_FLAGS_WHITELIST = "commercial"
+ </literallayout>
+ </para>
+ <para>
+ Specifying audio and video plug-ins as part of the
+ <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and
+ <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements
+ or commercial qt components as part of
+ the <filename>COMMERCIAL_QT</filename> statement (along
+ with the enabling LICENSE_FLAGS_WHITELIST) includes the
+ plug-ins or components into built images, thus adding
+ support for media formats or components.
+ </para>
+ </section>
+ </para>
</section>
</section>
</chapter>
--
1.7.0.4
More information about the yocto
mailing list