summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-09-21 09:42:31 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-09-28 15:02:32 +0100
commit39639ad3eaf8e2841324017d69a819ccef0492db (patch)
tree24aa02dad79466648e9245ae563d4f90592b4fed /documentation/dev-manual
parentfe8d57543313cd6ef79141ed374ac4f708f4e810 (diff)
downloadpoky-39639ad3eaf8e2841324017d69a819ccef0492db.tar.gz
dev-manual: Updates to the "Writing a New Recipe" section.
Made several improvements to this section. * fixed a typo where a YP release was referred to as 7.1 instead of 1.7 * Added a note box to the "Using Variables" list item elaborating on the expansion behavior. * Removed the detail around the WORKDIR discussion. * In the "Loccate or Automatically Create a Base Recipe", I added the devtool add method to the list of ways to create a base recipe. (From yocto-docs rev: 79c86fc3653c747ae42f08528063a8984cdd3b4d) 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.xml89
1 files changed, 58 insertions, 31 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 74deac5452..9521c7cd56 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1254,21 +1254,52 @@
1254 1254
1255 <para> 1255 <para>
1256 You can always write a recipe from scratch. 1256 You can always write a recipe from scratch.
1257 However, two choices exist that can help you quickly get a 1257 However, three choices exist that can help you quickly get a
1258 start on a new recipe: 1258 start on a new recipe:
1259 <itemizedlist> 1259 <itemizedlist>
1260 <listitem><para><emphasis><filename>recipetool</filename>:</emphasis> 1260 <listitem><para>
1261 <emphasis><filename>devtool add</filename>:</emphasis>
1262 A command that assists in creating a recipe and
1263 an environment condusive to development.
1264 </para></listitem>
1265 <listitem><para>
1266 <emphasis><filename>recipetool</filename>:</emphasis>
1261 A tool provided by the Yocto Project that automates 1267 A tool provided by the Yocto Project that automates
1262 creation of a base recipe based on the source 1268 creation of a base recipe based on the source
1263 files. 1269 files.
1264 </para></listitem> 1270 </para></listitem>
1265 <listitem><para><emphasis>Existing Recipes:</emphasis> 1271 <listitem><para>
1272 <emphasis>Existing Recipes:</emphasis>
1266 Location and modification of an existing recipe that is 1273 Location and modification of an existing recipe that is
1267 similar in function to the recipe you need. 1274 similar in function to the recipe you need.
1268 </para></listitem> 1275 </para></listitem>
1269 </itemizedlist> 1276 </itemizedlist>
1270 </para> 1277 </para>
1271 1278
1279 <section id='new-recipe-creating-the-base-recipe-using-devtool'>
1280 <title>Creating the Base Recipe Using <filename>devtool add</filename></title>
1281
1282 <para>
1283 The <filename>devtool add</filename> command uses the same
1284 logic for auto-creating the recipe as
1285 <filename>recipetool create</filename>, which is listed
1286 below.
1287 Additionally, however, <filename>devtool add</filename>
1288 sets up an environment that makes it easy for you to
1289 patch the source and to make changes to the recipe as
1290 is often necessary when adding a recipe to build a new
1291 piece of software to be included in a build.
1292 </para>
1293
1294 <para>
1295 You can find a complete description of the
1296 <filename>devtool add</filename> command in the
1297 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-use-devtool-to-add-an-application'>Use <filename>devtool add</filename> to Add an Application</ulink>"
1298 section in the Yocto Project Software Development Kit (SDK)
1299 Developer's Guide.
1300 </para>
1301 </section>
1302
1272 <section id='new-recipe-creating-the-base-recipe-using-recipetool'> 1303 <section id='new-recipe-creating-the-base-recipe-using-recipetool'>
1273 <title>Creating the Base Recipe Using <filename>recipetool</filename></title> 1304 <title>Creating the Base Recipe Using <filename>recipetool</filename></title>
1274 1305
@@ -1566,12 +1597,29 @@
1566 or tabs after the slash character. 1597 or tabs after the slash character.
1567 </note> 1598 </note>
1568 </para></listitem> 1599 </para></listitem>
1569 <listitem><para><emphasis>Using Variables: <filename>${...}</filename></emphasis> - 1600 <listitem><para>
1601 <emphasis>Using Variables: <filename>${...}</filename></emphasis> -
1570 Use the <filename>${<replaceable>VARNAME</replaceable>}</filename> syntax to 1602 Use the <filename>${<replaceable>VARNAME</replaceable>}</filename> syntax to
1571 access the contents of a variable: 1603 access the contents of a variable:
1572 <literallayout class='monospaced'> 1604 <literallayout class='monospaced'>
1573 SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz" 1605 SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz"
1574 </literallayout> 1606 </literallayout>
1607 <note>
1608 It is important to understand that the value of a
1609 variable expressed in this form does not get
1610 substituted automatically.
1611 The expansion of these expressions happens
1612 on-demand later (e.g. usually when a function that
1613 makes reference to the variable executes).
1614 This behavior ensures that the values are most
1615 appropriate for the context in which they are
1616 finally used.
1617 On the rare occasion that you do need the variable
1618 expression to be expanded immediately, you can use
1619 the <filename>:=</filename> operator instead of
1620 <filename>=</filename> when you make the
1621 assignment, but this is not generally needed.
1622 </note>
1575 </para></listitem> 1623 </para></listitem>
1576 <listitem><para><emphasis>Quote All Assignments: <filename>"<replaceable>value</replaceable>"</filename></emphasis> - 1624 <listitem><para><emphasis>Quote All Assignments: <filename>"<replaceable>value</replaceable>"</filename></emphasis> -
1577 Use double quotes around the value in all variable 1625 Use double quotes around the value in all variable
@@ -1779,11 +1827,12 @@
1779 </para> 1827 </para>
1780 1828
1781 <para> 1829 <para>
1782 The per-recipe temporary work directory is constructed as follows and 1830 The path to the per-recipe temporary work directory depends
1783 depends on several factors: 1831 on the context in which it is being built.
1832 The quickest way to find this path is to have BitBake return it
1833 by running the following:
1784 <literallayout class='monospaced'> 1834 <literallayout class='monospaced'>
1785 BASE_WORKDIR ?= "${TMPDIR}/work" 1835 $ bitbake -e recipename | grep ^WORKDIR=
1786 WORKDIR = "${BASE_WORKDIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
1787 </literallayout> 1836 </literallayout>
1788 As an example, assume a Source Directory top-level folder named 1837 As an example, assume a Source Directory top-level folder named
1789 <filename>poky</filename>, a default Build Directory at 1838 <filename>poky</filename>, a default Build Directory at
@@ -1817,28 +1866,6 @@
1817 "<ulink url='&YOCTO_DOCS_REF_URL;#closer-look'>A Closer Look at the Yocto Project Development Environment</ulink>" 1866 "<ulink url='&YOCTO_DOCS_REF_URL;#closer-look'>A Closer Look at the Yocto Project Development Environment</ulink>"
1818 chapter of the Yocto Project Reference Manual. 1867 chapter of the Yocto Project Reference Manual.
1819 </para> 1868 </para>
1820
1821 <para>
1822 You can also reference the following variables in the
1823 Yocto Project Reference Manual's glossary for more information:
1824 <itemizedlist>
1825 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>:
1826 The top-level build output directory</listitem>
1827 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink>:
1828 The target system identifier</listitem>
1829 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>:
1830 The recipe name</listitem>
1831 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>:
1832 The epoch - (if
1833 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>
1834 is not specified, which is usually the case for most
1835 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
1836 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
1837 The recipe version</listitem>
1838 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
1839 The recipe revision</listitem>
1840 </itemizedlist>
1841 </para>
1842 </section> 1869 </section>
1843 1870
1844 <section id='new-recipe-fetching-code'> 1871 <section id='new-recipe-fetching-code'>
@@ -2251,7 +2278,7 @@
2251 configure script with some options, or by modifying a build 2278 configure script with some options, or by modifying a build
2252 configuration file. 2279 configuration file.
2253 <note> 2280 <note>
2254 As of Yocto Project Release 7.1, some of the core recipes 2281 As of Yocto Project Release 1.7, some of the core recipes
2255 that package binary configuration scripts now disable the 2282 that package binary configuration scripts now disable the
2256 scripts due to the scripts previously requiring error-prone 2283 scripts due to the scripts previously requiring error-prone
2257 path substitution. 2284 path substitution.