summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-08-09 17:15:15 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-09-02 00:52:47 +0100
commitd369f333836b70e4109113f41bad4fddf49e3aaa (patch)
tree07a1e72da50be7055f11c614f5a2f46d8a74a46d /documentation/dev-manual
parentf3e80da1a7fab5a3bca0425ab868690804669fe9 (diff)
downloadpoky-d369f333836b70e4109113f41bad4fddf49e3aaa.tar.gz
dev-manual, ref-manual: Moved recipe syntax section to ref-manual
The section on recipe syntax that was buried in the creating a new recipe section was really a reference on syntax. I have moved it to the ref-manual. (From yocto-docs rev: cb55d1b5832cca6faa6e2a5b26f3add3032cade2) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml302
1 files changed, 5 insertions, 297 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index e4cfdcdef2..cc69d641c5 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1482,6 +1482,11 @@
1482 similar in function to the recipe you need. 1482 similar in function to the recipe you need.
1483 </para></listitem> 1483 </para></listitem>
1484 </itemizedlist> 1484 </itemizedlist>
1485 <note>
1486 For information on recipe syntax, see the
1487 "<ulink url='&YOCTO_DOCS_REF_URL;#recipe-syntax'>Recipe Syntax</ulink>"
1488 section in the Yocto Project Reference Manual.
1489 </note>
1485 </para> 1490 </para>
1486 1491
1487 <section id='new-recipe-creating-the-base-recipe-using-devtool'> 1492 <section id='new-recipe-creating-the-base-recipe-using-devtool'>
@@ -1702,303 +1707,6 @@
1702 </itemizedlist> 1707 </itemizedlist>
1703 </section> 1708 </section>
1704 1709
1705 <section id='understanding-recipe-syntax'>
1706 <title>Understanding Recipe Syntax</title>
1707
1708 <para>
1709 Understanding recipe file syntax is important for
1710 writing recipes.
1711 The following list overviews the basic items that make up a
1712 BitBake recipe file.
1713 For more complete BitBake syntax descriptions, see the
1714 "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>"
1715 chapter of the BitBake User Manual.
1716 <itemizedlist>
1717 <listitem><para><emphasis>Variable Assignments and Manipulations:</emphasis>
1718 Variable assignments allow a value to be assigned to a
1719 variable.
1720 The assignment can be static text or might include
1721 the contents of other variables.
1722 In addition to the assignment, appending and prepending
1723 operations are also supported.</para>
1724 <para>The following example shows some of the ways
1725 you can use variables in recipes:
1726 <literallayout class='monospaced'>
1727 S = "${WORKDIR}/postfix-${PV}"
1728 CFLAGS += "-DNO_ASM"
1729 SRC_URI_append = " file://fixup.patch"
1730 </literallayout>
1731 </para></listitem>
1732 <listitem><para><emphasis>Functions:</emphasis>
1733 Functions provide a series of actions to be performed.
1734 You usually use functions to override the default
1735 implementation of a task function or to complement
1736 a default function (i.e. append or prepend to an
1737 existing function).
1738 Standard functions use <filename>sh</filename> shell
1739 syntax, although access to OpenEmbedded variables and
1740 internal methods are also available.</para>
1741 <para>The following is an example function from the
1742 <filename>sed</filename> recipe:
1743 <literallayout class='monospaced'>
1744 do_install () {
1745 autotools_do_install
1746 install -d ${D}${base_bindir}
1747 mv ${D}${bindir}/sed ${D}${base_bindir}/sed
1748 rmdir ${D}${bindir}/
1749 }
1750 </literallayout>
1751 It is also possible to implement new functions that
1752 are called between existing tasks as long as the
1753 new functions are not replacing or complementing the
1754 default functions.
1755 You can implement functions in Python
1756 instead of shell.
1757 Both of these options are not seen in the majority of
1758 recipes.</para></listitem>
1759 <listitem><para><emphasis>Keywords:</emphasis>
1760 BitBake recipes use only a few keywords.
1761 You use keywords to include common
1762 functions (<filename>inherit</filename>), load parts
1763 of a recipe from other files
1764 (<filename>include</filename> and
1765 <filename>require</filename>) and export variables
1766 to the environment (<filename>export</filename>).</para>
1767 <para>The following example shows the use of some of
1768 these keywords:
1769 <literallayout class='monospaced'>
1770 export POSTCONF = "${STAGING_BINDIR}/postconf"
1771 inherit autoconf
1772 require otherfile.inc
1773 </literallayout>
1774 </para></listitem>
1775 <listitem><para><emphasis>Comments:</emphasis>
1776 Any lines that begin with the hash character
1777 (<filename>#</filename>) are treated as comment lines
1778 and are ignored:
1779 <literallayout class='monospaced'>
1780 # This is a comment
1781 </literallayout>
1782 </para></listitem>
1783 </itemizedlist>
1784 </para>
1785
1786 <para>
1787 This next list summarizes the most important and most commonly
1788 used parts of the recipe syntax.
1789 For more information on these parts of the syntax, you can
1790 reference the
1791 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>
1792 chapter in the BitBake User Manual.
1793 <itemizedlist>
1794 <listitem><para><emphasis>Line Continuation: <filename>\</filename></emphasis> -
1795 Use the backward slash (<filename>\</filename>)
1796 character to split a statement over multiple lines.
1797 Place the slash character at the end of the line that
1798 is to be continued on the next line:
1799 <literallayout class='monospaced'>
1800 VAR = "A really long \
1801 line"
1802 </literallayout>
1803 <note>
1804 You cannot have any characters including spaces
1805 or tabs after the slash character.
1806 </note>
1807 </para></listitem>
1808 <listitem><para>
1809 <emphasis>Using Variables: <filename>${...}</filename></emphasis> -
1810 Use the <filename>${<replaceable>VARNAME</replaceable>}</filename> syntax to
1811 access the contents of a variable:
1812 <literallayout class='monospaced'>
1813 SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz"
1814 </literallayout>
1815 <note>
1816 It is important to understand that the value of a
1817 variable expressed in this form does not get
1818 substituted automatically.
1819 The expansion of these expressions happens
1820 on-demand later (e.g. usually when a function that
1821 makes reference to the variable executes).
1822 This behavior ensures that the values are most
1823 appropriate for the context in which they are
1824 finally used.
1825 On the rare occasion that you do need the variable
1826 expression to be expanded immediately, you can use
1827 the <filename>:=</filename> operator instead of
1828 <filename>=</filename> when you make the
1829 assignment, but this is not generally needed.
1830 </note>
1831 </para></listitem>
1832 <listitem><para><emphasis>Quote All Assignments: <filename>"<replaceable>value</replaceable>"</filename></emphasis> -
1833 Use double quotes around the value in all variable
1834 assignments.
1835 <literallayout class='monospaced'>
1836 VAR1 = "${OTHERVAR}"
1837 VAR2 = "The version is ${PV}"
1838 </literallayout>
1839 </para></listitem>
1840 <listitem><para><emphasis>Conditional Assignment: <filename>?=</filename></emphasis> -
1841 Conditional assignment is used to assign a value to
1842 a variable, but only when the variable is currently
1843 unset.
1844 Use the question mark followed by the equal sign
1845 (<filename>?=</filename>) to make a "soft" assignment
1846 used for conditional assignment.
1847 Typically, "soft" assignments are used in the
1848 <filename>local.conf</filename> file for variables
1849 that are allowed to come through from the external
1850 environment.
1851 </para>
1852 <para>Here is an example where
1853 <filename>VAR1</filename> is set to "New value" if
1854 it is currently empty.
1855 However, if <filename>VAR1</filename> has already been
1856 set, it remains unchanged:
1857 <literallayout class='monospaced'>
1858 VAR1 ?= "New value"
1859 </literallayout>
1860 In this next example, <filename>VAR1</filename>
1861 is left with the value "Original value":
1862 <literallayout class='monospaced'>
1863 VAR1 = "Original value"
1864 VAR1 ?= "New value"
1865 </literallayout>
1866 </para></listitem>
1867 <listitem><para><emphasis>Appending: <filename>+=</filename></emphasis> -
1868 Use the plus character followed by the equals sign
1869 (<filename>+=</filename>) to append values to existing
1870 variables.
1871 <note>
1872 This operator adds a space between the existing
1873 content of the variable and the new content.
1874 </note></para>
1875 <para>Here is an example:
1876 <literallayout class='monospaced'>
1877 SRC_URI += "file://fix-makefile.patch"
1878 </literallayout>
1879 </para></listitem>
1880 <listitem><para><emphasis>Prepending: <filename>=+</filename></emphasis> -
1881 Use the equals sign followed by the plus character
1882 (<filename>=+</filename>) to prepend values to existing
1883 variables.
1884 <note>
1885 This operator adds a space between the new content
1886 and the existing content of the variable.
1887 </note></para>
1888 <para>Here is an example:
1889 <literallayout class='monospaced'>
1890 VAR =+ "Starts"
1891 </literallayout>
1892 </para></listitem>
1893 <listitem><para><emphasis>Appending: <filename>_append</filename></emphasis> -
1894 Use the <filename>_append</filename> operator to
1895 append values to existing variables.
1896 This operator does not add any additional space.
1897 Also, the operator is applied after all the
1898 <filename>+=</filename>, and
1899 <filename>=+</filename> operators have been applied and
1900 after all <filename>=</filename> assignments have
1901 occurred.
1902 </para>
1903 <para>The following example shows the space being
1904 explicitly added to the start to ensure the appended
1905 value is not merged with the existing value:
1906 <literallayout class='monospaced'>
1907 SRC_URI_append = " file://fix-makefile.patch"
1908 </literallayout>
1909 You can also use the <filename>_append</filename>
1910 operator with overrides, which results in the actions
1911 only being performed for the specified target or
1912 machine:
1913 <literallayout class='monospaced'>
1914 SRC_URI_append_sh4 = " file://fix-makefile.patch"
1915 </literallayout>
1916 </para></listitem>
1917 <listitem><para><emphasis>Prepending: <filename>_prepend</filename></emphasis> -
1918 Use the <filename>_prepend</filename> operator to
1919 prepend values to existing variables.
1920 This operator does not add any additional space.
1921 Also, the operator is applied after all the
1922 <filename>+=</filename>, and
1923 <filename>=+</filename> operators have been applied and
1924 after all <filename>=</filename> assignments have
1925 occurred.
1926 </para>
1927 <para>The following example shows the space being
1928 explicitly added to the end to ensure the prepended
1929 value is not merged with the existing value:
1930 <literallayout class='monospaced'>
1931 CFLAGS_prepend = "-I${S}/myincludes "
1932 </literallayout>
1933 You can also use the <filename>_prepend</filename>
1934 operator with overrides, which results in the actions
1935 only being performed for the specified target or
1936 machine:
1937 <literallayout class='monospaced'>
1938 CFLAGS_prepend_sh4 = "-I${S}/myincludes "
1939 </literallayout>
1940 </para></listitem>
1941 <listitem><para><emphasis>Overrides:</emphasis> -
1942 You can use overrides to set a value conditionally,
1943 typically based on how the recipe is being built.
1944 For example, to set the
1945 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>
1946 variable's value to "standard/base" for any target
1947 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>,
1948 except for qemuarm where it should be set to
1949 "standard/arm-versatile-926ejs", you would do the
1950 following:
1951 <literallayout class='monospaced'>
1952 KBRANCH = "standard/base"
1953 KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
1954 </literallayout>
1955 Overrides are also used to separate alternate values
1956 of a variable in other situations.
1957 For example, when setting variables such as
1958 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
1959 and
1960 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
1961 that are specific to individual packages produced by
1962 a recipe, you should always use an override that
1963 specifies the name of the package.
1964 </para></listitem>
1965 <listitem><para><emphasis>Indentation:</emphasis>
1966 Use spaces for indentation rather than than tabs.
1967 For shell functions, both currently work.
1968 However, it is a policy decision of the Yocto Project
1969 to use tabs in shell functions.
1970 Realize that some layers have a policy to use spaces
1971 for all indentation.
1972 </para></listitem>
1973 <listitem><para><emphasis>Using Python for Complex Operations: <filename>${@<replaceable>python_code</replaceable>}</filename></emphasis> -
1974 For more advanced processing, it is possible to use
1975 Python code during variable assignments (e.g.
1976 search and replacement on a variable).</para>
1977 <para>You indicate Python code using the
1978 <filename>${@<replaceable>python_code</replaceable>}</filename>
1979 syntax for the variable assignment:
1980 <literallayout class='monospaced'>
1981 SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz
1982 </literallayout>
1983 </para></listitem>
1984 <listitem><para><emphasis>Shell Function Syntax:</emphasis>
1985 Write shell functions as if you were writing a shell
1986 script when you describe a list of actions to take.
1987 You should ensure that your script works with a generic
1988 <filename>sh</filename> and that it does not require
1989 any <filename>bash</filename> or other shell-specific
1990 functionality.
1991 The same considerations apply to various system
1992 utilities (e.g. <filename>sed</filename>,
1993 <filename>grep</filename>, <filename>awk</filename>,
1994 and so forth) that you might wish to use.
1995 If in doubt, you should check with multiple
1996 implementations - including those from BusyBox.
1997 </para></listitem>
1998 </itemizedlist>
1999 </para>
2000 </section>
2001
2002 <section id='new-recipe-running-a-build-on-the-recipe'> 1710 <section id='new-recipe-running-a-build-on-the-recipe'>
2003 <title>Running a Build on the Recipe</title> 1711 <title>Running a Build on the Recipe</title>
2004 1712
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-08 14:18:56 +0000