* [PATCH 1/2] documentation/poky-ref-manual/technical-details.xml: update 'Enabling Commercially Licensed Recipes' section
2012-03-21 3:41 [PATCH 0/2] yocto-docs updates tom.zanussi
@ 2012-03-21 3:41 ` tom.zanussi
2012-03-21 3:41 ` [PATCH 2/2] documentation/bsp-guide/bsp.xml: update 'BSP Licensing' section tom.zanussi
1 sibling, 0 replies; 3+ messages in thread
From: tom.zanussi @ 2012-03-21 3:41 UTC (permalink / raw)
To: scott.m.rifenbark, yocto
From: Tom Zanussi <tom.zanussi@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@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
^ permalink raw reply related [flat|nested] 3+ messages in thread* [PATCH 2/2] documentation/bsp-guide/bsp.xml: update 'BSP Licensing' section
2012-03-21 3:41 [PATCH 0/2] yocto-docs updates tom.zanussi
2012-03-21 3:41 ` [PATCH 1/2] documentation/poky-ref-manual/technical-details.xml: update 'Enabling Commercially Licensed Recipes' section tom.zanussi
@ 2012-03-21 3:41 ` tom.zanussi
1 sibling, 0 replies; 3+ messages in thread
From: tom.zanussi @ 2012-03-21 3:41 UTC (permalink / raw)
To: scott.m.rifenbark, yocto
From: Tom Zanussi <tom.zanussi@intel.com>
The LICENSE_FLAGS mechanism can now be used to meet the special
license requirements needed by some BSPs. Update the documentation to
reflect the current BSP licensing mechanisms.
Also add a new blurb about the time-limited kernel.
Signed-off-by: Tom Zanussi <tom.zanussi@intel.com>
---
documentation/bsp-guide/bsp.xml | 192 ++++++++++++++++++--------------------
1 files changed, 91 insertions(+), 101 deletions(-)
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index a8d571c..40d994a 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -656,135 +656,125 @@
</section>
</section>
- <section id='bsp-click-through-licensing'>
- <title>BSP 'Click-Through' Licensing Procedure</title>
-
- <note> This section describes how
- click-through licensing is expected to work.
- Currently, this functionality is not yet implemented.
- </note>
-
+ <section id='bsp-licensing'>
+ <title>BSP Licensing Considerations</title>
<para>
In some cases, a BSP contains separately licensed IP
- (Intellectual Property) for a component that imposes
- upon the user a requirement to accept the terms of a
- 'click-through' license.
- Once the license is accepted the
- Yocto Project build system can then build and include the
- corresponding component in the final BSP image.
- Some affected components might be essential to the normal
- functioning of the system and have no 'free' replacement
- (i.e. the resulting system would be non-functional
- without them).
- On the other hand, other components might be simply
- 'good-to-have' or purely elective, or if essential
- nonetheless have a 'free' (possibly less-capable)
- version that could be used as a in the BSP recipe.
+ (Intellectual Property) for a component or components
+ that impose upon the user a requirement to accept the
+ terms of a commercial or other type of license that
+ requires some kind of explicit EULA (End User License
+ Agreement). Once the license is accepted the Yocto
+ Project build system can then build and include the
+ corresponding component in the final BSP image, or if
+ the BSP is available in the form of an already built
+ image, the user will be able to download the image after
+ agreeing to the license or EULA.
+ </para>
+ <para>
+ Some affected components might be essential to the
+ normal functioning of the system and have no 'free'
+ replacement (i.e. the resulting system would be
+ non-functional without them). On the other hand, other
+ components might be simply 'good-to-have' or purely
+ elective, or if essential nonetheless have a 'free'
+ (possibly less-capable) version that could be used as a
+ in the BSP recipe.
</para>
<para>
- For cases where you can substitute something and still maintain functionality,
- the Yocto Project website's
- <ulink url='&YOCTO_HOME_URL;/download/all?keys=&download_type=1&download_version='>BSP Download Page</ulink>
- makes available 'de-featured' BSPs that are completely free of any IP encumbrances.
- For these cases you can use the substitution directly and without any further licensing
- requirements.
- If present, these fully 'de-featured' BSPs are named appropriately different
- as compared to the names of the respective encumbered BSPs.
- If available, these substitutions are the simplest and most preferred options.
- This, of course, assumes the resulting functionality meets requirements.
+ For cases where you can substitute something and still
+ maintain functionality, the Yocto Project website's
+ <ulink url='&YOCTO_HOME_URL;/download/all?keys=&download_type=1&download_version='>BSP
+ Download Page</ulink> makes available 'de-featured' BSPs
+ that are completely free of any IP encumbrances. For
+ these cases you can use the substitution directly and
+ without any further licensing requirements. If present,
+ these fully 'de-featured' BSPs are named appropriately
+ different as compared to the names of the respective
+ encumbered BSPs. If available, these substitutions are
+ the simplest and most preferred options. This, of
+ course, assumes the resulting functionality meets
+ requirements.
</para>
<para>
- If however, a non-encumbered version is unavailable or the 'free' version
- would provide unsuitable functionality or quality, you can use
- an encumbered version.
+ If however, a non-encumbered version is unavailable or
+ the 'free' version would provide unsuitable
+ functionality or quality, you can use an encumbered
+ version.
</para>
- <para>
- Several methods exist within the Yocto Project build system to satisfy the licensing
- requirements for an encumbered BSP.
- The following list describes them in preferential order:
+ <para> A couple different methods exist within the Yocto
+ Project build system to satisfy the licensing
+ requirements for an encumbered BSP. The following list
+ describes them in order of preference:
</para>
<orderedlist>
<listitem>
-
<para>
- Get a license key (or keys) for the encumbered BSP by visiting
- a website and providing the name of the BSP and your email address
- through a web form.
+ Yocto recipes that have commercial or other types of
+ specially-licensed packages define a variable named
+ LICENSE_FLAGS. For each of those recipes, a user
+ can specify a matching license string in a
+ local.conf variable named LICENSE_FLAGS_WHITELIST.
+ This signifies that the user agrees to the license,
+ and the corresponding recipe can then be built and
+ included in the image. See Section 3.3.2. in The
+ Yocto Project Reference Manual for details on these
+ variables and how to make use of them.
</para>
-
- <para>
- After agreeing to any applicable license terms, the
- BSP key(s) will be immediately sent to the address
- you gave and you can use them by specifying BSPKEY_<keydomain>
- environment variables when building the image:
- </para>
-
- <literallayout class='monospaced'>
- $ BSPKEY_<keydomain>=<key> bitbake core-image-sato
- </literallayout>
<para>
- These steps allow the encumbered image to be built
- with no change at all to the normal build process.
+ If you build as you normally would, without
+ specifying any recipes in the
+ LICENSE_FLAGS_WHITELIST, the build will stop and
+ provide you with the list of recipes that you've
+ tried to include in the image which need entries in
+ the LICENSE_FLAGS_WHITELIST. Once the appropriate
+ license flags have been entered into the whitelist,
+ restart the build to continue where it left off.
+ During the build the prompt will not appear again
+ since you have satisfied the requirement.
</para>
-
- <para>
- Equivalently and probably more conveniently, a line
- for each key can instead be put into the user's
- <filename>local.conf</filename> file found in the Yocto Project file's
- build directory.
- </para>
-
+
<para>
- The <keydomain> component of the
- BSPKEY_<keydomain> is required because there
- might be multiple licenses in effect for a given BSP.
- In such cases, a given <keydomain> corresponds to
- a particular license. In order for an encumbered
- BSP that encompasses multiple key domains to be built
- successfully, a <keydomain> entry for each
- applicable license must be present in <filename>local.conf</filename> or
- supplied on the command-line.
+ Once the appropriate license flags are whitelisted
+ in the LICENSE_FLAGS_WHITELIST variable, the
+ encumbered image can be built with no change at all
+ to the normal build process.
</para>
</listitem>
<listitem>
<para>
- Do nothing - build as you normally would.
- When a license is needed the build will stop and prompt you with instructions.
- Follow the license prompts that originate from the
- encumbered BSP.
- These prompts usually take the form of instructions
- needed to manually fetch the encumbered package(s)
- and md5 sums into the required directory
- (e.g. the <filename>yocto/build/downloads</filename>).
- Once the manual package fetch has been
- completed, restart the build to continue where
- it left off.
- During the build the prompt will not appear again since you have satisfied the
- requirement.
- </para>
- </listitem>
- <listitem>
- <para>
- Get a full-featured BSP recipe rather than a key.
- You can do this by visiting the Yocto Project website's
- <ulink url='&YOCTO_HOME_URL;/download'>Download</ulink> page and
- clicking on "BSP Downloads".
- BSP tarballs that have proprietary information can be downloaded after agreeing
- to licensing requirements as part of the download process.
- Obtaining the code this way allows you to build an encumbered image with
- no changes at all as compared to the normal build.
+ Get a pre-built version of the BSP. You can do this
+ by visiting the Yocto Project website's
+ <ulink url='&YOCTO_HOME_URL;/download'>Download</ulink>
+ page and clicking on "BSP Downloads". BSP tarballs
+ that contain proprietary components can be
+ downloaded after agreeing to the licensing
+ requirements of each of the individually encumbered
+ packages as part of the download process. Obtaining
+ the BSP this way allows you to access an encumbered
+ image immediately after agreeing to the
+ click-through license agreements presented by the
+ website. Note that if you want to build the image
+ yourself using the recipes contained within the BSP
+ tarball, you will still need to create an
+ appropriate LICENSE_FLAGS_WHITELIST to match the
+ encumbered recipes in the BSP.
</para>
</listitem>
</orderedlist>
<para>
- Note that the third method is also the only option available
- when downloading pre-compiled images generated from non-free BSPs.
- Those images are likewise available at from the Yocto Project website.
+ Note also that the pre-compiled images are bundled with
+ a time-limited kernel which will run for only a
+ predetermined amount of time (10 days) before it forces
+ the system to reboot. This is meant as a discouragement
+ to directly redistributing the image as-is, and means
+ that you'll have to eventually rebuild the image if you
+ want to remove that restriction.
</para>
</section>
--
1.7.0.4
^ permalink raw reply related [flat|nested] 3+ messages in thread