summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/bsp-guide/bsp.xml6
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml7
-rw-r--r--documentation/overview-manual/overview-concepts.xml390
-rw-r--r--documentation/ref-manual/ref-variables.xml12
-rw-r--r--documentation/ref-manual/technical-details.xml357
5 files changed, 403 insertions, 369 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 6ae3ff9804..7d3345e06a 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -1415,9 +1415,9 @@
1415 Thus, the build system can build the corresponding recipe and include 1415 Thus, the build system can build the corresponding recipe and include
1416 the component in the image. 1416 the component in the image.
1417 See the 1417 See the
1418 "<ulink url='&YOCTO_DOCS_REF_URL;#enabling-commercially-licensed-recipes'>Enabling 1418 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
1419 Commercially Licensed Recipes</ulink>" section in the Yocto Project Reference 1419 section in the Yocto Project Overview Manual for details on how
1420 Manual for details on how to use these variables.</para> 1420 to use these variables.</para>
1421 <para>If you build as you normally would, without 1421 <para>If you build as you normally would, without
1422 specifying any recipes in the 1422 specifying any recipes in the
1423 <filename>LICENSE_FLAGS_WHITELIST</filename>, the build stops and 1423 <filename>LICENSE_FLAGS_WHITELIST</filename>, the build stops and
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index b141498763..075d0f6fdf 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -2128,8 +2128,8 @@
2128 containing the current checksum. 2128 containing the current checksum.
2129 For more explanation and examples of how to set the 2129 For more explanation and examples of how to set the
2130 <filename>LIC_FILES_CHKSUM</filename> variable, see the 2130 <filename>LIC_FILES_CHKSUM</filename> variable, see the
2131 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" 2131 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
2132 section in the Yocto Project Reference Manual.</para> 2132 section in the Yocto Project Overview Manual.</para>
2133 <para>To determine the correct checksum string, you 2133 <para>To determine the correct checksum string, you
2134 can list the appropriate files in the 2134 can list the appropriate files in the
2135 <filename>LIC_FILES_CHKSUM</filename> variable with 2135 <filename>LIC_FILES_CHKSUM</filename> variable with
@@ -3211,7 +3211,8 @@
3211 The variable 3211 The variable
3212 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename> 3212 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename>
3213 is used to track source license changes as described in the 3213 is used to track source license changes as described in the
3214 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" section. 3214 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
3215 section in the Yocto Project Overview Manual.
3215 You can quickly create Autotool-based recipes in a manner similar to the previous example. 3216 You can quickly create Autotool-based recipes in a manner similar to the previous example.
3216 </para> 3217 </para>
3217 </section> 3218 </section>
diff --git a/documentation/overview-manual/overview-concepts.xml b/documentation/overview-manual/overview-concepts.xml
index a7d6d2f6fb..2f5c14eef6 100644
--- a/documentation/overview-manual/overview-concepts.xml
+++ b/documentation/overview-manual/overview-concepts.xml
@@ -1460,6 +1460,396 @@
1460 </section> 1460 </section>
1461 </section> 1461 </section>
1462 1462
1463 <section id="overview-licenses">
1464 <title>Licenses</title>
1465
1466 <para>
1467 This section describes the mechanism by which the OpenEmbedded
1468 build system tracks changes to licensing text.
1469 The section also describes how to enable commercially licensed
1470 recipes, which by default are disabled.
1471 </para>
1472
1473 <para>
1474 For information that can help you maintain compliance with
1475 various open source licensing during the lifecycle of the product,
1476 see the
1477 "<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>"
1478 section in the Yocto Project Development Tasks Manual.
1479 </para>
1480
1481 <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
1482 <title>Tracking License Changes</title>
1483
1484 <para>
1485 The license of an upstream project might change in the future.
1486 In order to prevent these changes going unnoticed, the
1487 <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
1488 variable tracks changes to the license text. The checksums are
1489 validated at the end of the configure step, and if the
1490 checksums do not match, the build will fail.
1491 </para>
1492
1493 <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
1494 <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
1495
1496 <para>
1497 The <filename>LIC_FILES_CHKSUM</filename>
1498 variable contains checksums of the license text in the
1499 source code for the recipe.
1500 Following is an example of how to specify
1501 <filename>LIC_FILES_CHKSUM</filename>:
1502 <literallayout class='monospaced'>
1503 LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
1504 file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
1505 file://licfile2.txt;endline=50;md5=zzzz \
1506 ..."
1507 </literallayout>
1508 <note><title>Notes</title>
1509 <itemizedlist>
1510 <listitem><para>
1511 When using "beginline" and "endline", realize
1512 that line numbering begins with one and not
1513 zero.
1514 Also, the included lines are inclusive (i.e.
1515 lines five through and including 29 in the
1516 previous example for
1517 <filename>licfile1.txt</filename>).
1518 </para></listitem>
1519 <listitem><para>
1520 When a license check fails, the selected license
1521 text is included as part of the QA message.
1522 Using this output, you can determine the exact
1523 start and finish for the needed license text.
1524 </para></listitem>
1525 </itemizedlist>
1526 </note>
1527 </para>
1528
1529 <para>
1530 The build system uses the
1531 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
1532 variable as the default directory when searching files
1533 listed in <filename>LIC_FILES_CHKSUM</filename>.
1534 The previous example employs the default directory.
1535 </para>
1536
1537 <para>
1538 Consider this next example:
1539 <literallayout class='monospaced'>
1540 LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\
1541 md5=bb14ed3c4cda583abc85401304b5cd4e"
1542 LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
1543 </literallayout>
1544 </para>
1545
1546 <para>
1547 The first line locates a file in
1548 <filename>${S}/src/ls.c</filename> and isolates lines five
1549 through 16 as license text.
1550 The second line refers to a file in
1551 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>.
1552 </para>
1553
1554 <para>
1555 Note that <filename>LIC_FILES_CHKSUM</filename> variable is
1556 mandatory for all recipes, unless the
1557 <filename>LICENSE</filename> variable is set to "CLOSED".
1558 </para>
1559 </section>
1560
1561 <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
1562 <title>Explanation of Syntax</title>
1563
1564 <para>
1565 As mentioned in the previous section, the
1566 <filename>LIC_FILES_CHKSUM</filename> variable lists all
1567 the important files that contain the license text for the
1568 source code.
1569 It is possible to specify a checksum for an entire file,
1570 or a specific section of a file (specified by beginning and
1571 ending line numbers with the "beginline" and "endline"
1572 parameters, respectively).
1573 The latter is useful for source files with a license
1574 notice header, README documents, and so forth.
1575 If you do not use the "beginline" parameter, then it is
1576 assumed that the text begins on the first line of the file.
1577 Similarly, if you do not use the "endline" parameter,
1578 it is assumed that the license text ends with the last
1579 line of the file.
1580 </para>
1581
1582 <para>
1583 The "md5" parameter stores the md5 checksum of the license
1584 text.
1585 If the license text changes in any way as compared to
1586 this parameter then a mismatch occurs.
1587 This mismatch triggers a build failure and notifies
1588 the developer.
1589 Notification allows the developer to review and address
1590 the license text changes.
1591 Also note that if a mismatch occurs during the build,
1592 the correct md5 checksum is placed in the build log and
1593 can be easily copied to the recipe.
1594 </para>
1595
1596 <para>
1597 There is no limit to how many files you can specify using
1598 the <filename>LIC_FILES_CHKSUM</filename> variable.
1599 Generally, however, every project requires a few
1600 specifications for license tracking.
1601 Many projects have a "COPYING" file that stores the
1602 license information for all the source code files.
1603 This practice allows you to just track the "COPYING"
1604 file as long as it is kept up to date.
1605 <note><title>Tips</title>
1606 <itemizedlist>
1607 <listitem><para>
1608 If you specify an empty or invalid "md5"
1609 parameter, BitBake returns an md5 mis-match
1610 error and displays the correct "md5" parameter
1611 value during the build.
1612 The correct parameter is also captured in
1613 the build log.
1614 </para></listitem>
1615 <listitem><para>
1616 If the whole file contains only license text,
1617 you do not need to use the "beginline" and
1618 "endline" parameters.
1619 </para></listitem>
1620 </itemizedlist>
1621 </note>
1622 </para>
1623 </section>
1624 </section>
1625
1626 <section id="enabling-commercially-licensed-recipes">
1627 <title>Enabling Commercially Licensed Recipes</title>
1628
1629 <para>
1630 By default, the OpenEmbedded build system disables
1631 components that have commercial or other special licensing
1632 requirements.
1633 Such requirements are defined on a
1634 recipe-by-recipe basis through the
1635 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
1636 variable definition in the affected recipe.
1637 For instance, the
1638 <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
1639 recipe contains the following statement:
1640 <literallayout class='monospaced'>
1641 LICENSE_FLAGS = "commercial"
1642 </literallayout>
1643 Here is a slightly more complicated example that contains both
1644 an explicit recipe name and version (after variable expansion):
1645 <literallayout class='monospaced'>
1646 LICENSE_FLAGS = "license_${PN}_${PV}"
1647 </literallayout>
1648 In order for a component restricted by a
1649 <filename>LICENSE_FLAGS</filename> definition to be enabled and
1650 included in an image, it needs to have a matching entry in the
1651 global
1652 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>
1653 variable, which is a variable typically defined in your
1654 <filename>local.conf</filename> file.
1655 For example, to enable the
1656 <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
1657 package, you could add either the string
1658 "commercial_gst-plugins-ugly" or the more general string
1659 "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>.
1660 See the
1661 "<link linkend='license-flag-matching'>License Flag Matching</link>"
1662 section for a full
1663 explanation of how <filename>LICENSE_FLAGS</filename> matching
1664 works.
1665 Here is the example:
1666 <literallayout class='monospaced'>
1667 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
1668 </literallayout>
1669 Likewise, to additionally enable the package built from the
1670 recipe containing
1671 <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>,
1672 and assuming that the actual recipe name was
1673 <filename>emgd_1.10.bb</filename>, the following string would
1674 enable that package as well as the original
1675 <filename>gst-plugins-ugly</filename> package:
1676 <literallayout class='monospaced'>
1677 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
1678 </literallayout>
1679 As a convenience, you do not need to specify the complete
1680 license string in the whitelist for every package.
1681 You can use an abbreviated form, which consists
1682 of just the first portion or portions of the license
1683 string before the initial underscore character or characters.
1684 A partial string will match any license that contains the
1685 given string as the first portion of its license.
1686 For example, the following whitelist string will also match
1687 both of the packages previously mentioned as well as any other
1688 packages that have licenses starting with "commercial" or
1689 "license".
1690 <literallayout class='monospaced'>
1691 LICENSE_FLAGS_WHITELIST = "commercial license"
1692 </literallayout>
1693 </para>
1694
1695 <section id="license-flag-matching">
1696 <title>License Flag Matching</title>
1697
1698 <para>
1699 License flag matching allows you to control what recipes
1700 the OpenEmbedded build system includes in the build.
1701 Fundamentally, the build system attempts to match
1702 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
1703 strings found in recipes against
1704 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>
1705 strings found in the whitelist.
1706 A match causes the build system to include a recipe in the
1707 build, while failure to find a match causes the build
1708 system to exclude a recipe.
1709 </para>
1710
1711 <para>
1712 In general, license flag matching is simple.
1713 However, understanding some concepts will help you
1714 correctly and effectively use matching.
1715 </para>
1716
1717 <para>
1718 Before a flag
1719 defined by a particular recipe is tested against the
1720 contents of the whitelist, the expanded string
1721 <filename>_${PN}</filename> is appended to the flag.
1722 This expansion makes each
1723 <filename>LICENSE_FLAGS</filename> value recipe-specific.
1724 After expansion, the string is then matched against the
1725 whitelist.
1726 Thus, specifying
1727 <filename>LICENSE_FLAGS = "commercial"</filename>
1728 in recipe "foo", for example, results in the string
1729 <filename>"commercial_foo"</filename>.
1730 And, to create a match, that string must appear in the
1731 whitelist.
1732 </para>
1733
1734 <para>
1735 Judicious use of the <filename>LICENSE_FLAGS</filename>
1736 strings and the contents of the
1737 <filename>LICENSE_FLAGS_WHITELIST</filename> variable
1738 allows you a lot of flexibility for including or excluding
1739 recipes based on licensing.
1740 For example, you can broaden the matching capabilities by
1741 using license flags string subsets in the whitelist.
1742 <note>
1743 When using a string subset, be sure to use the part of
1744 the expanded string that precedes the appended
1745 underscore character (e.g.
1746 <filename>usethispart_1.3</filename>,
1747 <filename>usethispart_1.4</filename>, and so forth).
1748 </note>
1749 For example, simply specifying the string "commercial" in
1750 the whitelist matches any expanded
1751 <filename>LICENSE_FLAGS</filename> definition that starts
1752 with the string "commercial" such as "commercial_foo" and
1753 "commercial_bar", which are the strings the build system
1754 automatically generates for hypothetical recipes named
1755 "foo" and "bar" assuming those recipes simply specify the
1756 following:
1757 <literallayout class='monospaced'>
1758 LICENSE_FLAGS = "commercial"
1759 </literallayout>
1760 Thus, you can choose to exhaustively
1761 enumerate each license flag in the whitelist and
1762 allow only specific recipes into the image, or
1763 you can use a string subset that causes a broader range of
1764 matches to allow a range of recipes into the image.
1765 </para>
1766
1767 <para>
1768 This scheme works even if the
1769 <filename>LICENSE_FLAGS</filename> string already
1770 has <filename>_${PN}</filename> appended.
1771 For example, the build system turns the license flag
1772 "commercial_1.2_foo" into "commercial_1.2_foo_foo" and
1773 would match both the general "commercial" and the specific
1774 "commercial_1.2_foo" strings found in the whitelist, as
1775 expected.
1776 </para>
1777
1778 <para>
1779 Here are some other scenarios:
1780 <itemizedlist>
1781 <listitem><para>
1782 You can specify a versioned string in the recipe
1783 such as "commercial_foo_1.2" in a "foo" recipe.
1784 The build system expands this string to
1785 "commercial_foo_1.2_foo".
1786 Combine this license flag with a whitelist that has
1787 the string "commercial" and you match the flag
1788 along with any other flag that starts with the
1789 string "commercial".
1790 </para></listitem>
1791 <listitem><para>
1792 Under the same circumstances, you can use
1793 "commercial_foo" in the whitelist and the build
1794 system not only matches "commercial_foo_1.2" but
1795 also matches any license flag with the string
1796 "commercial_foo", regardless of the version.
1797 </para></listitem>
1798 <listitem><para>
1799 You can be very specific and use both the
1800 package and version parts in the whitelist (e.g.
1801 "commercial_foo_1.2") to specifically match a
1802 versioned recipe.
1803 </para></listitem>
1804 </itemizedlist>
1805 </para>
1806 </section>
1807
1808 <section id="other-variables-related-to-commercial-licenses">
1809 <title>Other Variables Related to Commercial Licenses</title>
1810
1811 <para>
1812 Other helpful variables related to commercial
1813 license handling exist and are defined in the
1814 <filename>poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
1815 <literallayout class='monospaced'>
1816 COMMERCIAL_AUDIO_PLUGINS ?= ""
1817 COMMERCIAL_VIDEO_PLUGINS ?= ""
1818 </literallayout>
1819 If you want to enable these components, you can do so by
1820 making sure you have statements similar to the following
1821 in your <filename>local.conf</filename> configuration file:
1822 <literallayout class='monospaced'>
1823 COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
1824 gst-plugins-ugly-mpegaudioparse"
1825 COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
1826 gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
1827 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
1828 </literallayout>
1829 Of course, you could also create a matching whitelist
1830 for those components using the more general "commercial"
1831 in the whitelist, but that would also enable all the
1832 other packages with
1833 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
1834 containing "commercial", which you may or may not want:
1835 <literallayout class='monospaced'>
1836 LICENSE_FLAGS_WHITELIST = "commercial"
1837 </literallayout>
1838 </para>
1839
1840 <para>
1841 Specifying audio and video plug-ins as part of the
1842 <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and
1843 <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements
1844 (along with the enabling
1845 <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the
1846 plug-ins or components into built images, thus adding
1847 support for media formats or components.
1848 </para>
1849 </section>
1850 </section>
1851 </section>
1852
1463 <section id='x32'> 1853 <section id='x32'>
1464 <title>x32 psABI</title> 1854 <title>x32 psABI</title>
1465 1855
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index a971e2a8f9..8baa0c0f07 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -7908,8 +7908,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
7908 <link linkend='var-LICENSE'><filename>LICENSE</filename></link> 7908 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
7909 is set to "CLOSED").</para> 7909 is set to "CLOSED").</para>
7910 <para>For more information, see the 7910 <para>For more information, see the
7911 "<link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'> 7911 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
7912 Tracking License Changes</link>" section. 7912 section in the Yocto Project Overview Manual.
7913 </para> 7913 </para>
7914 </glossdef> 7914 </glossdef>
7915 </glossentry> 7915 </glossentry>
@@ -8044,8 +8044,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
8044 require additional licenses in order to be used in a 8044 require additional licenses in order to be used in a
8045 commercial product. 8045 commercial product.
8046 For more information, see the 8046 For more information, see the
8047 "<link linkend='enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</link>" 8047 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
8048 section. 8048 section in the Yocto Project Overview Manual.
8049 </para> 8049 </para>
8050 </glossdef> 8050 </glossdef>
8051 </glossentry> 8051 </glossentry>
@@ -8064,8 +8064,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
8064 This practice is otherwise known as "whitelisting" 8064 This practice is otherwise known as "whitelisting"
8065 license flags. 8065 license flags.
8066 For more information, see the 8066 For more information, see the
8067 <link linkend='enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</link>" 8067 <ulink url='&YOCTO_DOCS_OVERVIEW_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
8068 section. 8068 section in the Yocto Project Overview Manual.
8069 </para> 8069 </para>
8070 </glossdef> 8070 </glossdef>
8071 </glossentry> 8071 </glossentry>
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index ba0b27ddc9..3827366dcb 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -13,363 +13,6 @@
13 x32, Wayland support, and Licenses. 13 x32, Wayland support, and Licenses.
14 </para> 14 </para>
15 15
16<section id="licenses">
17 <title>Licenses</title>
18
19 <para>
20 This section describes the mechanism by which the OpenEmbedded build system
21 tracks changes to licensing text.
22 The section also describes how to enable commercially licensed recipes,
23 which by default are disabled.
24 </para>
25
26 <para>
27 For information that can help you maintain compliance with various open
28 source licensing during the lifecycle of the product, see the
29 "<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>"
30 section in the Yocto Project Development Tasks Manual.
31 </para>
32
33 <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
34 <title>Tracking License Changes</title>
35
36 <para>
37 The license of an upstream project might change in the future.
38 In order to prevent these changes going unnoticed, the
39 <filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></filename>
40 variable tracks changes to the license text. The checksums are validated at the end of the
41 configure step, and if the checksums do not match, the build will fail.
42 </para>
43
44 <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
45 <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
46
47 <para>
48 The <filename>LIC_FILES_CHKSUM</filename>
49 variable contains checksums of the license text in the source
50 code for the recipe.
51 Following is an example of how to specify
52 <filename>LIC_FILES_CHKSUM</filename>:
53 <literallayout class='monospaced'>
54 LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
55 file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
56 file://licfile2.txt;endline=50;md5=zzzz \
57 ..."
58 </literallayout>
59 <note><title>Notes</title>
60 <itemizedlist>
61 <listitem><para>
62 When using "beginline" and "endline", realize that
63 line numbering begins with one and not zero.
64 Also, the included lines are inclusive (i.e. lines
65 five through and including 29 in the previous
66 example for <filename>licfile1.txt</filename>).
67 </para></listitem>
68 <listitem><para>
69 When a license check fails, the selected license
70 text is included as part of the QA message.
71 Using this output, you can determine the exact
72 start and finish for the needed license text.
73 </para></listitem>
74 </itemizedlist>
75 </note>
76 </para>
77
78 <para>
79 The build system uses the
80 <filename><link linkend='var-S'>S</link></filename> variable as
81 the default directory when searching files listed in
82 <filename>LIC_FILES_CHKSUM</filename>.
83 The previous example employs the default directory.
84 </para>
85
86 <para>
87 Consider this next example:
88 <literallayout class='monospaced'>
89 LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\
90 md5=bb14ed3c4cda583abc85401304b5cd4e"
91 LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
92 </literallayout>
93 </para>
94
95 <para>
96 The first line locates a file in
97 <filename>${S}/src/ls.c</filename> and isolates lines five
98 through 16 as license text.
99 The second line refers to a file in
100 <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>.
101 </para>
102 <para>
103 Note that <filename>LIC_FILES_CHKSUM</filename> variable is
104 mandatory for all recipes, unless the
105 <filename>LICENSE</filename> variable is set to "CLOSED".
106 </para>
107 </section>
108
109 <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
110 <title>Explanation of Syntax</title>
111 <para>
112 As mentioned in the previous section, the
113 <filename>LIC_FILES_CHKSUM</filename> variable lists all the
114 important files that contain the license text for the source code.
115 It is possible to specify a checksum for an entire file, or a specific section of a
116 file (specified by beginning and ending line numbers with the "beginline" and "endline"
117 parameters, respectively).
118 The latter is useful for source files with a license notice header,
119 README documents, and so forth.
120 If you do not use the "beginline" parameter, then it is assumed that the text begins on the
121 first line of the file.
122 Similarly, if you do not use the "endline" parameter, it is assumed that the license text
123 ends with the last line of the file.
124 </para>
125
126 <para>
127 The "md5" parameter stores the md5 checksum of the license text.
128 If the license text changes in any way as compared to this parameter
129 then a mismatch occurs.
130 This mismatch triggers a build failure and notifies the developer.
131 Notification allows the developer to review and address the license text changes.
132 Also note that if a mismatch occurs during the build, the correct md5
133 checksum is placed in the build log and can be easily copied to the recipe.
134 </para>
135
136 <para>
137 There is no limit to how many files you can specify using the
138 <filename>LIC_FILES_CHKSUM</filename> variable.
139 Generally, however, every project requires a few specifications for license tracking.
140 Many projects have a "COPYING" file that stores the license information for all the source
141 code files.
142 This practice allows you to just track the "COPYING" file as long as it is kept up to date.
143 </para>
144
145 <tip>
146 If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match
147 error and displays the correct "md5" parameter value during the build.
148 The correct parameter is also captured in the build log.
149 </tip>
150
151 <tip>
152 If the whole file contains only license text, you do not need to use the "beginline" and
153 "endline" parameters.
154 </tip>
155 </section>
156 </section>
157
158 <section id="enabling-commercially-licensed-recipes">
159 <title>Enabling Commercially Licensed Recipes</title>
160
161 <para>
162 By default, the OpenEmbedded build system disables
163 components that have commercial or other special licensing
164 requirements.
165 Such requirements are defined on a
166 recipe-by-recipe basis through the
167 <link linkend='var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></link>
168 variable definition in the affected recipe.
169 For instance, the
170 <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
171 recipe contains the following statement:
172 <literallayout class='monospaced'>
173 LICENSE_FLAGS = "commercial"
174 </literallayout>
175 Here is a slightly more complicated example that contains both an
176 explicit recipe name and version (after variable expansion):
177 <literallayout class='monospaced'>
178 LICENSE_FLAGS = "license_${PN}_${PV}"
179 </literallayout>
180 In order for a component restricted by a <filename>LICENSE_FLAGS</filename>
181 definition to be enabled and included in an image, it
182 needs to have a matching entry in the global
183 <link linkend='var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></link>
184 variable, which is a variable
185 typically defined in your <filename>local.conf</filename> file.
186 For example, to enable
187 the <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
188 package, you could add either the string
189 "commercial_gst-plugins-ugly" or the more general string
190 "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>.
191 See the
192 "<link linkend='license-flag-matching'>License Flag Matching</link>" section
193 for a full explanation of how <filename>LICENSE_FLAGS</filename> matching works.
194 Here is the example:
195 <literallayout class='monospaced'>
196 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
197 </literallayout>
198 Likewise, to additionally enable the package built from the recipe containing
199 <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>, and assuming
200 that the actual recipe name was <filename>emgd_1.10.bb</filename>,
201 the following string would enable that package as well as
202 the original <filename>gst-plugins-ugly</filename> package:
203 <literallayout class='monospaced'>
204 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
205 </literallayout>
206 As a convenience, you do not need to specify the complete license string
207 in the whitelist for every package.
208 You can use an abbreviated form, which consists
209 of just the first portion or portions of the license string before
210 the initial underscore character or characters.
211 A partial string will match
212 any license that contains the given string as the first
213 portion of its license.
214 For example, the following
215 whitelist string will also match both of the packages
216 previously mentioned as well as any other packages that have
217 licenses starting with "commercial" or "license".
218 <literallayout class='monospaced'>
219 LICENSE_FLAGS_WHITELIST = "commercial license"
220 </literallayout>
221 </para>
222
223 <section id="license-flag-matching">
224 <title>License Flag Matching</title>
225
226 <para>
227 License flag matching allows you to control what recipes the
228 OpenEmbedded build system includes in the build.
229 Fundamentally, the build system attempts to match
230 <link linkend='var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></link>
231 strings found in recipes against
232 <link linkend='var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></link>
233 strings found in the whitelist.
234 A match causes the build system to include a recipe in the
235 build, while failure to find a match causes the build system to
236 exclude a recipe.
237 </para>
238
239 <para>
240 In general, license flag matching is simple.
241 However, understanding some concepts will help you
242 correctly and effectively use matching.
243 </para>
244
245 <para>
246 Before a flag
247 defined by a particular recipe is tested against the
248 contents of the whitelist, the expanded string
249 <filename>_${PN}</filename> is appended to the flag.
250 This expansion makes each <filename>LICENSE_FLAGS</filename>
251 value recipe-specific.
252 After expansion, the string is then matched against the
253 whitelist.
254 Thus, specifying
255 <filename>LICENSE_FLAGS = "commercial"</filename>
256 in recipe "foo", for example, results in the string
257 <filename>"commercial_foo"</filename>.
258 And, to create a match, that string must appear in the
259 whitelist.
260 </para>
261
262 <para>
263 Judicious use of the <filename>LICENSE_FLAGS</filename>
264 strings and the contents of the
265 <filename>LICENSE_FLAGS_WHITELIST</filename> variable
266 allows you a lot of flexibility for including or excluding
267 recipes based on licensing.
268 For example, you can broaden the matching capabilities by
269 using license flags string subsets in the whitelist.
270 <note>When using a string subset, be sure to use the part of
271 the expanded string that precedes the appended underscore
272 character (e.g. <filename>usethispart_1.3</filename>,
273 <filename>usethispart_1.4</filename>, and so forth).
274 </note>
275 For example, simply specifying the string "commercial" in
276 the whitelist matches any expanded
277 <filename>LICENSE_FLAGS</filename> definition that starts with
278 the string "commercial" such as "commercial_foo" and
279 "commercial_bar", which are the strings the build system
280 automatically generates for hypothetical recipes named
281 "foo" and "bar" assuming those recipes simply specify the
282 following:
283 <literallayout class='monospaced'>
284 LICENSE_FLAGS = "commercial"
285 </literallayout>
286 Thus, you can choose to exhaustively
287 enumerate each license flag in the whitelist and
288 allow only specific recipes into the image, or
289 you can use a string subset that causes a broader range of
290 matches to allow a range of recipes into the image.
291 </para>
292
293 <para>
294 This scheme works even if the
295 <filename>LICENSE_FLAGS</filename> string already
296 has <filename>_${PN}</filename> appended.
297 For example, the build system turns the license flag
298 "commercial_1.2_foo" into "commercial_1.2_foo_foo" and would
299 match both the general "commercial" and the specific
300 "commercial_1.2_foo" strings found in the whitelist, as
301 expected.
302 </para>
303
304 <para>
305 Here are some other scenarios:
306 <itemizedlist>
307 <listitem><para>You can specify a versioned string in the
308 recipe such as "commercial_foo_1.2" in a "foo" recipe.
309 The build system expands this string to
310 "commercial_foo_1.2_foo".
311 Combine this license flag with a whitelist that has
312 the string "commercial" and you match the flag along
313 with any other flag that starts with the string
314 "commercial".</para></listitem>
315 <listitem><para>Under the same circumstances, you can
316 use "commercial_foo" in the whitelist and the
317 build system not only matches "commercial_foo_1.2" but
318 also matches any license flag with the string
319 "commercial_foo", regardless of the version.
320 </para></listitem>
321 <listitem><para>You can be very specific and use both the
322 package and version parts in the whitelist (e.g.
323 "commercial_foo_1.2") to specifically match a
324 versioned recipe.</para></listitem>
325 </itemizedlist>
326 </para>
327 </section>
328
329 <section id="other-variables-related-to-commercial-licenses">
330 <title>Other Variables Related to Commercial Licenses</title>
331
332 <para>
333 Other helpful variables related to commercial
334 license handling exist and are defined in the
335 <filename>poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
336 <literallayout class='monospaced'>
337 COMMERCIAL_AUDIO_PLUGINS ?= ""
338 COMMERCIAL_VIDEO_PLUGINS ?= ""
339 </literallayout>
340 If you want to enable these components, you can do so by making sure you have
341 statements similar to the following
342 in your <filename>local.conf</filename> configuration file:
343 <literallayout class='monospaced'>
344 COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
345 gst-plugins-ugly-mpegaudioparse"
346 COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
347 gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
348 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
349 </literallayout>
350 Of course, you could also create a matching whitelist
351 for those components using the more general "commercial"
352 in the whitelist, but that would also enable all the
353 other packages with
354 <link linkend='var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></link>
355 containing "commercial", which you may or may not want:
356 <literallayout class='monospaced'>
357 LICENSE_FLAGS_WHITELIST = "commercial"
358 </literallayout>
359 </para>
360
361 <para>
362 Specifying audio and video plug-ins as part of the
363 <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and
364 <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements
365 (along with the enabling
366 <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the
367 plug-ins or components into built images, thus adding
368 support for media formats or components.
369 </para>
370 </section>
371 </section>
372</section>
373</chapter> 16</chapter>
374<!-- 17<!--
375vim: expandtab tw=80 ts=4 18vim: expandtab tw=80 ts=4