diff options
Diffstat (limited to 'documentation/overview-manual')
-rw-r--r-- | documentation/overview-manual/overview-concepts.xml | 390 |
1 files changed, 390 insertions, 0 deletions
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 | ||