Thus, the build system can build the corresponding recipe and include
the component in the image.
See the
- "<ulink url='&YOCTO_DOCS_REF_URL;#enabling-commercially-licensed-recipes'>Enabling
- Commercially Licensed Recipes</ulink>" section in the Yocto Project Reference
- Manual for details on how to use these variables.</para>
+ "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
+ section in the Yocto Project Overview Manual for details on how
+ to use these variables.</para>
<para>If you build as you normally would, without
specifying any recipes in the
<filename>LICENSE_FLAGS_WHITELIST</filename>, the build stops and
containing the current checksum.
For more explanation and examples of how to set the
<filename>LIC_FILES_CHKSUM</filename> variable, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
- section in the Yocto Project Reference Manual.</para>
+ "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
+ section in the Yocto Project Overview Manual.</para>
<para>To determine the correct checksum string, you
can list the appropriate files in the
<filename>LIC_FILES_CHKSUM</filename> variable with
The variable
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename>
is used to track source license changes as described in the
- "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" section.
+ "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
+ section in the Yocto Project Overview Manual.
You can quickly create Autotool-based recipes in a manner similar to the previous example.
</para>
</section>
</section>
</section>
+ <section id="overview-licenses">
+ <title>Licenses</title>
+
+ <para>
+ This section describes the mechanism by which the OpenEmbedded
+ build system tracks changes to licensing text.
+ The section also describes how to enable commercially licensed
+ recipes, which by default are disabled.
+ </para>
+
+ <para>
+ For information that can help you maintain compliance with
+ various open source licensing during the lifecycle of the product,
+ see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Project's Lifecycle</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+
+ <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
+ <title>Tracking License Changes</title>
+
+ <para>
+ The license of an upstream project might change in the future.
+ In order to prevent these changes going unnoticed, the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
+ variable tracks changes to the license text. The checksums are
+ validated at the end of the configure step, and if the
+ checksums do not match, the build will fail.
+ </para>
+
+ <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
+ <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
+
+ <para>
+ The <filename>LIC_FILES_CHKSUM</filename>
+ variable contains checksums of the license text in the
+ source code for the recipe.
+ Following is an example of how to specify
+ <filename>LIC_FILES_CHKSUM</filename>:
+ <literallayout class='monospaced'>
+ LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
+ file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
+ file://licfile2.txt;endline=50;md5=zzzz \
+ ..."
+ </literallayout>
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ When using "beginline" and "endline", realize
+ that line numbering begins with one and not
+ zero.
+ Also, the included lines are inclusive (i.e.
+ lines five through and including 29 in the
+ previous example for
+ <filename>licfile1.txt</filename>).
+ </para></listitem>
+ <listitem><para>
+ When a license check fails, the selected license
+ text is included as part of the QA message.
+ Using this output, you can determine the exact
+ start and finish for the needed license text.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+
+ <para>
+ The build system uses the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
+ variable as the default directory when searching files
+ listed in <filename>LIC_FILES_CHKSUM</filename>.
+ The previous example employs the default directory.
+ </para>
+
+ <para>
+ Consider this next example:
+ <literallayout class='monospaced'>
+ LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\
+ md5=bb14ed3c4cda583abc85401304b5cd4e"
+ LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
+ </literallayout>
+ </para>
+
+ <para>
+ The first line locates a file in
+ <filename>${S}/src/ls.c</filename> and isolates lines five
+ through 16 as license text.
+ The second line refers to a file in
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>.
+ </para>
+
+ <para>
+ Note that <filename>LIC_FILES_CHKSUM</filename> variable is
+ mandatory for all recipes, unless the
+ <filename>LICENSE</filename> variable is set to "CLOSED".
+ </para>
+ </section>
+
+ <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
+ <title>Explanation of Syntax</title>
+
+ <para>
+ As mentioned in the previous section, the
+ <filename>LIC_FILES_CHKSUM</filename> variable lists all
+ the important files that contain the license text for the
+ source code.
+ It is possible to specify a checksum for an entire file,
+ or a specific section of a file (specified by beginning and
+ ending line numbers with the "beginline" and "endline"
+ parameters, respectively).
+ The latter is useful for source files with a license
+ notice header, README documents, and so forth.
+ If you do not use the "beginline" parameter, then it is
+ assumed that the text begins on the first line of the file.
+ Similarly, if you do not use the "endline" parameter,
+ it is assumed that the license text ends with the last
+ line of the file.
+ </para>
+
+ <para>
+ The "md5" parameter stores the md5 checksum of the license
+ text.
+ If the license text changes in any way as compared to
+ this parameter then a mismatch occurs.
+ This mismatch triggers a build failure and notifies
+ the developer.
+ Notification allows the developer to review and address
+ the license text changes.
+ Also note that if a mismatch occurs during the build,
+ the correct md5 checksum is placed in the build log and
+ can be easily copied to the recipe.
+ </para>
+
+ <para>
+ There is no limit to how many files you can specify using
+ the <filename>LIC_FILES_CHKSUM</filename> variable.
+ Generally, however, every project requires a few
+ specifications for license tracking.
+ Many projects have a "COPYING" file that stores the
+ license information for all the source code files.
+ This practice allows you to just track the "COPYING"
+ file as long as it is kept up to date.
+ <note><title>Tips</title>
+ <itemizedlist>
+ <listitem><para>
+ If you specify an empty or invalid "md5"
+ parameter, BitBake returns an md5 mis-match
+ error and displays the correct "md5" parameter
+ value during the build.
+ The correct parameter is also captured in
+ the build log.
+ </para></listitem>
+ <listitem><para>
+ If the whole file contains only license text,
+ you do not need to use the "beginline" and
+ "endline" parameters.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+ </section>
+ </section>
+
+ <section id="enabling-commercially-licensed-recipes">
+ <title>Enabling Commercially Licensed Recipes</title>
+
+ <para>
+ By default, the OpenEmbedded build system disables
+ components that have commercial or other special licensing
+ requirements.
+ Such requirements are defined on a
+ recipe-by-recipe basis through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
+ variable definition in the affected recipe.
+ For instance, the
+ <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
+ recipe contains the following statement:
+ <literallayout class='monospaced'>
+ LICENSE_FLAGS = "commercial"
+ </literallayout>
+ Here is a slightly more complicated example that contains both
+ an explicit recipe name and version (after variable expansion):
+ <literallayout class='monospaced'>
+ LICENSE_FLAGS = "license_${PN}_${PV}"
+ </literallayout>
+ In order for a component restricted by a
+ <filename>LICENSE_FLAGS</filename> definition to be enabled and
+ included in an image, it needs to have a matching entry in the
+ global
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>
+ variable, which is a variable typically defined in your
+ <filename>local.conf</filename> file.
+ For example, to enable the
+ <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
+ package, you could add either the string
+ "commercial_gst-plugins-ugly" or the more general string
+ "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>.
+ See the
+ "<link linkend='license-flag-matching'>License Flag Matching</link>"
+ section for a full
+ explanation of how <filename>LICENSE_FLAGS</filename> matching
+ works.
+ Here is the example:
+ <literallayout class='monospaced'>
+ LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
+ </literallayout>
+ Likewise, to additionally enable the package built from the
+ recipe containing
+ <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>,
+ and assuming that the actual recipe name was
+ <filename>emgd_1.10.bb</filename>, the following string would
+ enable that package as well as the original
+ <filename>gst-plugins-ugly</filename> package:
+ <literallayout class='monospaced'>
+ LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
+ </literallayout>
+ 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".
+ <literallayout class='monospaced'>
+ LICENSE_FLAGS_WHITELIST = "commercial license"
+ </literallayout>
+ </para>
+
+ <section id="license-flag-matching">
+ <title>License Flag Matching</title>
+
+ <para>
+ License flag matching allows you to control what recipes
+ the OpenEmbedded build system includes in the build.
+ Fundamentally, the build system attempts to match
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
+ strings found in recipes against
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>
+ 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 exclude a recipe.
+ </para>
+
+ <para>
+ In general, license flag matching is simple.
+ However, understanding some concepts will help you
+ correctly and effectively use matching.
+ </para>
+
+ <para>
+ Before a flag
+ defined by a particular recipe is tested against the
+ 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
+ <filename>"commercial_foo"</filename>.
+ 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 including or excluding
+ recipes based on licensing.
+ For example, you can broaden the matching capabilities by
+ 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
+ the whitelist matches any expanded
+ <filename>LICENSE_FLAGS</filename> 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
+ following:
+ <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>
+ This scheme works even if the
+ <filename>LICENSE_FLAGS</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>
+ 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>
+
+ <section id="other-variables-related-to-commercial-licenses">
+ <title>Other Variables Related to Commercial Licenses</title>
+
+ <para>
+ Other helpful variables related to commercial
+ license handling exist and are defined in the
+ <filename>poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
+ <literallayout class='monospaced'>
+ COMMERCIAL_AUDIO_PLUGINS ?= ""
+ COMMERCIAL_VIDEO_PLUGINS ?= ""
+ </literallayout>
+ If you want to enable these components, you can do so by
+ making sure you have statements similar to the following
+ in your <filename>local.conf</filename> 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"
+ 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
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
+ 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
+ (along with the enabling
+ <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the
+ plug-ins or components into built images, thus adding
+ support for media formats or components.
+ </para>
+ </section>
+ </section>
+ </section>
+
<section id='x32'>
<title>x32 psABI</title>
<link linkend='var-LICENSE'><filename>LICENSE</filename></link>
is set to "CLOSED").</para>
<para>For more information, see the
- "<link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
- Tracking License Changes</link>" section.
+ "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
+ section in the Yocto Project Overview Manual.
</para>
</glossdef>
</glossentry>
require additional licenses in order to be used in a
commercial product.
For more information, see the
- "<link linkend='enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
+ section in the Yocto Project Overview Manual.
</para>
</glossdef>
</glossentry>
This practice is otherwise known as "whitelisting"
license flags.
For more information, see the
- <link linkend='enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</link>"
- section.
+ <ulink url='&YOCTO_DOCS_OVERVIEW_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
+ section in the Yocto Project Overview Manual.
</para>
</glossdef>
</glossentry>
x32, Wayland support, and Licenses.
</para>
-<section id="licenses">
- <title>Licenses</title>
-
- <para>
- This section describes the mechanism by which the OpenEmbedded build system
- tracks changes to licensing text.
- The section also describes how to enable commercially licensed recipes,
- which by default are disabled.
- </para>
-
- <para>
- For information that can help you maintain compliance with various open
- source licensing during the lifecycle of the product, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Project's Lifecycle</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para>
-
- <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
- <title>Tracking License Changes</title>
-
- <para>
- The license of an upstream project might change in the future.
- In order to prevent these changes going unnoticed, the
- <filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></filename>
- variable tracks changes to the license text. The checksums are validated at the end of the
- configure step, and if the checksums do not match, the build will fail.
- </para>
-
- <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
- <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
-
- <para>
- The <filename>LIC_FILES_CHKSUM</filename>
- variable contains checksums of the license text in the source
- code for the recipe.
- Following is an example of how to specify
- <filename>LIC_FILES_CHKSUM</filename>:
- <literallayout class='monospaced'>
- LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
- file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
- file://licfile2.txt;endline=50;md5=zzzz \
- ..."
- </literallayout>
- <note><title>Notes</title>
- <itemizedlist>
- <listitem><para>
- When using "beginline" and "endline", realize that
- line numbering begins with one and not zero.
- Also, the included lines are inclusive (i.e. lines
- five through and including 29 in the previous
- example for <filename>licfile1.txt</filename>).
- </para></listitem>
- <listitem><para>
- When a license check fails, the selected license
- text is included as part of the QA message.
- Using this output, you can determine the exact
- start and finish for the needed license text.
- </para></listitem>
- </itemizedlist>
- </note>
- </para>
-
- <para>
- The build system uses the
- <filename><link linkend='var-S'>S</link></filename> variable as
- the default directory when searching files listed in
- <filename>LIC_FILES_CHKSUM</filename>.
- The previous example employs the default directory.
- </para>
-
- <para>
- Consider this next example:
- <literallayout class='monospaced'>
- LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\
- md5=bb14ed3c4cda583abc85401304b5cd4e"
- LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
- </literallayout>
- </para>
-
- <para>
- The first line locates a file in
- <filename>${S}/src/ls.c</filename> and isolates lines five
- through 16 as license text.
- The second line refers to a file in
- <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>.
- </para>
- <para>
- Note that <filename>LIC_FILES_CHKSUM</filename> variable is
- mandatory for all recipes, unless the
- <filename>LICENSE</filename> variable is set to "CLOSED".
- </para>
- </section>
-
- <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
- <title>Explanation of Syntax</title>
- <para>
- As mentioned in the previous section, the
- <filename>LIC_FILES_CHKSUM</filename> variable lists all the
- important files that contain the license text for the source code.
- It is possible to specify a checksum for an entire file, or a specific section of a
- file (specified by beginning and ending line numbers with the "beginline" and "endline"
- parameters, respectively).
- The latter is useful for source files with a license notice header,
- README documents, and so forth.
- If you do not use the "beginline" parameter, then it is assumed that the text begins on the
- first line of the file.
- Similarly, if you do not use the "endline" parameter, it is assumed that the license text
- ends with the last line of the file.
- </para>
-
- <para>
- The "md5" parameter stores the md5 checksum of the license text.
- If the license text changes in any way as compared to this parameter
- then a mismatch occurs.
- This mismatch triggers a build failure and notifies the developer.
- Notification allows the developer to review and address the license text changes.
- Also note that if a mismatch occurs during the build, the correct md5
- checksum is placed in the build log and can be easily copied to the recipe.
- </para>
-
- <para>
- There is no limit to how many files you can specify using the
- <filename>LIC_FILES_CHKSUM</filename> variable.
- Generally, however, every project requires a few specifications for license tracking.
- Many projects have a "COPYING" file that stores the license information for all the source
- code files.
- This practice allows you to just track the "COPYING" file as long as it is kept up to date.
- </para>
-
- <tip>
- If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match
- error and displays the correct "md5" parameter value during the build.
- The correct parameter is also captured in the build log.
- </tip>
-
- <tip>
- If the whole file contains only license text, you do not need to use the "beginline" and
- "endline" parameters.
- </tip>
- </section>
- </section>
-
- <section id="enabling-commercially-licensed-recipes">
- <title>Enabling Commercially Licensed Recipes</title>
-
- <para>
- By default, the OpenEmbedded build system disables
- components that have commercial or other special licensing
- requirements.
- Such requirements are defined on a
- recipe-by-recipe basis through the
- <link linkend='var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></link>
- variable definition in the affected recipe.
- For instance, the
- <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
- recipe contains the following statement:
- <literallayout class='monospaced'>
- LICENSE_FLAGS = "commercial"
- </literallayout>
- Here is a slightly more complicated example that contains both an
- explicit recipe name and version (after variable expansion):
- <literallayout class='monospaced'>
- LICENSE_FLAGS = "license_${PN}_${PV}"
- </literallayout>
- In order for a component restricted by a <filename>LICENSE_FLAGS</filename>
- definition to be enabled and included in an image, it
- needs to have a matching entry in the global
- <link linkend='var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></link>
- variable, which is a variable
- typically defined in your <filename>local.conf</filename> file.
- For example, to enable
- the <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
- package, you could add either the string
- "commercial_gst-plugins-ugly" or the more general string
- "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>.
- See the
- "<link linkend='license-flag-matching'>License Flag Matching</link>" section
- for a full explanation of how <filename>LICENSE_FLAGS</filename> matching works.
- Here is the example:
- <literallayout class='monospaced'>
- LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
- </literallayout>
- Likewise, to additionally enable the package built from the recipe containing
- <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>, and assuming
- that the actual recipe name was <filename>emgd_1.10.bb</filename>,
- the following string would enable that package as well as
- the original <filename>gst-plugins-ugly</filename> package:
- <literallayout class='monospaced'>
- LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
- </literallayout>
- 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".
- <literallayout class='monospaced'>
- LICENSE_FLAGS_WHITELIST = "commercial license"
- </literallayout>
- </para>
-
- <section id="license-flag-matching">
- <title>License Flag Matching</title>
-
- <para>
- License flag matching allows you to control what recipes the
- OpenEmbedded build system includes in the build.
- Fundamentally, the build system attempts to match
- <link linkend='var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></link>
- strings found in recipes against
- <link linkend='var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></link>
- 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
- exclude a recipe.
- </para>
-
- <para>
- In general, license flag matching is simple.
- However, understanding some concepts will help you
- correctly and effectively use matching.
- </para>
-
- <para>
- Before a flag
- defined by a particular recipe is tested against the
- 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
- <filename>"commercial_foo"</filename>.
- 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 including or excluding
- recipes based on licensing.
- For example, you can broaden the matching capabilities by
- 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
- the whitelist matches any expanded
- <filename>LICENSE_FLAGS</filename> 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
- following:
- <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>
- This scheme works even if the
- <filename>LICENSE_FLAGS</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>
- 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>
-
- <section id="other-variables-related-to-commercial-licenses">
- <title>Other Variables Related to Commercial Licenses</title>
-
- <para>
- Other helpful variables related to commercial
- license handling exist and are defined in the
- <filename>poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
- <literallayout class='monospaced'>
- COMMERCIAL_AUDIO_PLUGINS ?= ""
- COMMERCIAL_VIDEO_PLUGINS ?= ""
- </literallayout>
- If you want to enable these components, you can do so by making sure you have
- statements similar to the following
- in your <filename>local.conf</filename> 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"
- 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
- <link linkend='var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></link>
- 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
- (along with the enabling
- <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the
- plug-ins or components into built images, thus adding
- support for media formats or components.
- </para>
- </section>
- </section>
-</section>
</chapter>
<!--
vim: expandtab tw=80 ts=4
projects / thirdparty / openembedded / openembedded-core-contrib.git / commitdiff
