summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2014-01-10 17:24:54 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-01-21 21:58:00 +0000
commite987fa8e489a1392b0faa1b362cbc720b9ba3551 (patch)
treeb2579076b104cfd063ed2e5d3fff335fbc0e289f
parenta66675e2833dd1340963bd825956f67221b516d6 (diff)
downloadpoky-e987fa8e489a1392b0faa1b362cbc720b9ba3551.tar.gz
dev-manual: Edits to the "Writing a New Recipe" section.
Implemented some third review feedback from Paul Eggleton. (From yocto-docs rev: 3fd9c3cc4cf2aba876f0ad2ab36660ec32ea4c08) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml206
1 files changed, 89 insertions, 117 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 1f552d8d3b..331700bdea 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1172,11 +1172,10 @@
1172 Before writing a recipe from scratch, it is often useful to 1172 Before writing a recipe from scratch, it is often useful to
1173 discover whether someone else has already written one that 1173 discover whether someone else has already written one that
1174 meets (or comes close to meeting) your needs. 1174 meets (or comes close to meeting) your needs.
1175 The Yocto Project and OpenEmbedded communities contain 1175 The Yocto Project and OpenEmbedded communities maintain many
1176 and maintain many recipes that might be candidates for what 1176 recipes that might be candidates for what you are doing.
1177 you are doing.
1178 You can find a good central index of these recipes in the 1177 You can find a good central index of these recipes in the
1179 <ulink url='http://layers.openembedded.org/layerindex/branch/master/layer/meta-oe/'>OpenEmbedded metadata index</ulink>. 1178 <ulink url='http://layers.openembedded.org'>OpenEmbedded metadata index</ulink>.
1180 </para> 1179 </para>
1181 1180
1182 <para> 1181 <para>
@@ -1221,47 +1220,6 @@
1221 </para></listitem> 1220 </para></listitem>
1222 </itemizedlist> 1221 </itemizedlist>
1223 </para> 1222 </para>
1224
1225 <para>
1226 Regardless of where you get a base recipe, you will need to
1227 make changes to support your needs.
1228 When you do, you need to be aware of how BitBake parses curly
1229 braces.
1230 If a recipe uses a closing curly brace within the function and
1231 the character has no leading spaces, BitBake produces a parsing
1232 error.
1233 If you use a pair of curly brace in a shell function, the
1234 closing curly brace must not be located at the start of the line
1235 without leading spaces.
1236 </para>
1237
1238 <para>
1239 Here is an example that causes BitBake to produce a parsing
1240 error:
1241 <literallayout class='monospaced'>
1242 fakeroot create_shar() {
1243 cat &lt;&lt; "EOF" &gt; ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
1244 usage()
1245 {
1246 echo "test"
1247 ###### The following "}" at the start of the line causes a parsing error ######
1248 }
1249 EOF
1250 }
1251 </literallayout>
1252 Writing the recipe this way avoids the error:
1253 <literallayout class='monospaced'>
1254 fakeroot create_shar() {
1255 cat &lt;&lt; "EOF" &gt; ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
1256 usage()
1257 {
1258 echo "test"
1259 ######The following "}" with a leading space at the start of the line avoids the error ######
1260 }
1261 EOF
1262 }
1263 </literallayout>
1264 </para>
1265 </section> 1223 </section>
1266 1224
1267 <section id='new-recipe-storing-and-naming-the-recipe'> 1225 <section id='new-recipe-storing-and-naming-the-recipe'>
@@ -1278,7 +1236,8 @@
1278 <itemizedlist> 1236 <itemizedlist>
1279 <listitem><para><emphasis>Storing Your Recipe:</emphasis> 1237 <listitem><para><emphasis>Storing Your Recipe:</emphasis>
1280 The OpenEmbedded build system locates your recipe 1238 The OpenEmbedded build system locates your recipe
1281 through the <filename>layer.conf</filename> file and the 1239 through the layer's <filename>conf/layer.conf</filename>
1240 file and the
1282 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'><filename>BBFILES</filename></ulink> 1241 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'><filename>BBFILES</filename></ulink>
1283 variable. 1242 variable.
1284 This variable sets up a path from which the build system can 1243 This variable sets up a path from which the build system can
@@ -1303,7 +1262,8 @@
1303 Use lower-cased characters and do not include the reserved 1262 Use lower-cased characters and do not include the reserved
1304 suffixes <filename>-native</filename>, 1263 suffixes <filename>-native</filename>,
1305 <filename>-cross</filename>, <filename>-initial</filename>, 1264 <filename>-cross</filename>, <filename>-initial</filename>,
1306 or <filename>-dev</filename>. 1265 or <filename>-dev</filename> casually (i.e. do not use them
1266 as part of your recipe name unless the string applies).
1307 Here are some examples: 1267 Here are some examples:
1308 <literallayout class='monospaced'> 1268 <literallayout class='monospaced'>
1309 cups_1.7.0.bb 1269 cups_1.7.0.bb
@@ -1331,19 +1291,21 @@
1331 and you are in the 1291 and you are in the
1332 <link linkend='build-directory'>Build Directory</link>, 1292 <link linkend='build-directory'>Build Directory</link>,
1333 use BitBake to process your recipe. 1293 use BitBake to process your recipe.
1334 All you need to provide is the base name of your recipe: 1294 All you need to provide is the
1295 <filename>&lt;basename&gt;</filename> of the recipe as described
1296 in the previous section:
1335 <literallayout class='monospaced'> 1297 <literallayout class='monospaced'>
1336 $ bitbake &lt;basename&gt; 1298 $ bitbake &lt;basename&gt;
1337 </literallayout> 1299 </literallayout>
1300
1338 </para> 1301 </para>
1339 1302
1340 <para> 1303 <para>
1341 During the build, the OpenEmbedded build system creates a 1304 During the build, the OpenEmbedded build system creates a
1342 temporary work directory for the recipe 1305 temporary work directory for the recipe
1343 (<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>) 1306 (<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>)
1344 where it keeps extracted source files, log files, images, and 1307 where it keeps extracted source files, log files, intermediate
1345 so forth. 1308 compilation and packaging files, and so forth.
1346 You can find individual logs in this area for each task.
1347 </para> 1309 </para>
1348 1310
1349 <para> 1311 <para>
@@ -1368,6 +1330,15 @@
1368 and <filename>temp</filename>. 1330 and <filename>temp</filename>.
1369 After the build, you can examine these to determine how well 1331 After the build, you can examine these to determine how well
1370 the build went. 1332 the build went.
1333 <note>
1334 You can find individual log files for individual recipes in
1335 their <filename>temp</filename> directory (e.g.
1336 <filename>poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0/temp</filename>).
1337 Log files are named <filename>log.do_&lt;taskname&gt;</filename>
1338 (e.g. <filename>log.do_configure</filename>,
1339 <filename>log.do_fetch</filename>, and
1340 <filename>log.do_compile</filename>).
1341 </note>
1371 </para> 1342 </para>
1372 1343
1373 <para> 1344 <para>
@@ -1381,9 +1352,10 @@
1381 Yocto Project Reference Manual's glossary for more information: 1352 Yocto Project Reference Manual's glossary for more information:
1382 <itemizedlist> 1353 <itemizedlist>
1383 <listitem>The temporary directory - <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink></listitem> 1354 <listitem>The temporary directory - <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink></listitem>
1384 <listitem>The machine architecture - <ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink></listitem> 1355 <listitem>The target architecture - <ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink></listitem>
1385 <listitem>The recipe name - <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink></listitem> 1356 <listitem>The recipe name - <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink></listitem>
1386 <listitem>The epoch - <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink></listitem> 1357 <listitem>The epoch - <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>
1358 (if specified - blank for most recipes)</listitem>
1387 <listitem>The recipe version - <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink></listitem> 1359 <listitem>The recipe version - <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink></listitem>
1388 <listitem>The recipe revision - <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink></listitem> 1360 <listitem>The recipe revision - <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink></listitem>
1389 </itemizedlist> 1361 </itemizedlist>
@@ -1459,60 +1431,7 @@
1459 </para> 1431 </para>
1460 1432
1461 <para> 1433 <para>
1462 This next example is more complicated and is from the 1434 Another way of specifying source is from an SCM.
1463 <filename>meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.19.bb</filename>
1464 recipe.
1465 The example uses a <filename>SRC_URI</filename> statement
1466 that identifies a tarball, a patch file, a desktop file, and an
1467 icon as the source files for the recipe.
1468 <literallayout class='monospaced'>
1469 SRC_URI = "http://dist.schmorp.de/rxvt-unicode/Attic/rxvt-unicode-${PV}.tar.bz2 \
1470 file://xwc.patch \
1471 file://rxvt.desktop \
1472 file://rxvt.png"
1473 </literallayout>
1474 </para>
1475
1476 <para>
1477 When you specify local files using the
1478 <filename>file://</filename> URI protocol, the build system
1479 fetches files from the local machine.
1480 The path is relative to the
1481 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
1482 variable and searches specific directories in a certain order:
1483 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink><filename>}</filename>,
1484 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink><filename>}</filename>,
1485 and <filename>files</filename>.
1486 The directories are assumed to be subdirectories of the
1487 directory in which the recipe or append file resides.
1488 For another example that specifies these types of files, see the
1489 "<link linkend='usingpoky-extend-addpkg-singlec'>Single .c File Package (Hello World!)</link>"
1490 section.
1491 </para>
1492
1493 <para>
1494 The previous example also specifies a patch file.
1495 Patch files are files whose names end in
1496 <filename>.patch</filename> or <filename>.diff</filename>.
1497 The build system automatically applies patches as described
1498 in the
1499 "<link linkend='new-recipe-patching-code'>Patching Code</link>" section.
1500 </para>
1501
1502 <para>
1503 The build system should be able to apply patches with the "-p1"
1504 option (i.e. one directory level in the path will be stripped
1505 off).
1506 If your patch needs to have more directory levels stripped off,
1507 specify the number of levels using the "striplevel" option in
1508 the <filename>SRC_URI</filename> entry for the patch.
1509 Alternatively, if your patch needs to be applied in a specific
1510 subdirectory that is not specified in the patch file, use the
1511 "patchdir" option in the entry.
1512 </para>
1513
1514 <para>
1515 A final way of specifying source is from an SCM.
1516 For Git repositories, you must specify 1435 For Git repositories, you must specify
1517 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink> 1436 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
1518 and you should specify 1437 and you should specify
@@ -1574,19 +1493,46 @@
1574 Once you have the correct checksums, simply copy them into your 1493 Once you have the correct checksums, simply copy them into your
1575 recipe for a subsequent build. 1494 recipe for a subsequent build.
1576 </para> 1495 </para>
1577 </section>
1578 1496
1579 <section id='new-recipe-patching-code'> 1497 <para>
1580 <title>Patching Code</title> 1498 This final example is a bit more complicated and is from the
1499 <filename>meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.19.bb</filename>
1500 recipe.
1501 The example's <filename>SRC_URI</filename> statement identifies
1502 multiple files as the source files for the recipe: a tarball, a
1503 patch file, a desktop file, and an icon.
1504 <literallayout class='monospaced'>
1505 SRC_URI = "http://dist.schmorp.de/rxvt-unicode/Attic/rxvt-unicode-${PV}.tar.bz2 \
1506 file://xwc.patch \
1507 file://rxvt.desktop \
1508 file://rxvt.png"
1509 </literallayout>
1510 </para>
1581 1511
1582 <para> 1512 <para>
1583 Sometimes it is necessary to patch code after it has been 1513 When you specify local files using the
1584 fetched. 1514 <filename>file://</filename> URI protocol, the build system
1585 Any files mentioned in <filename>SRC_URI</filename> whose 1515 fetches files from the local machine.
1586 names end in <filename>.patch</filename> or 1516 The path is relative to the
1587 <filename>.diff</filename> are treated as patches. 1517 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
1588 The <filename>do_patch</filename> task automatically applies 1518 variable and searches specific directories in a certain order:
1589 these patches. 1519 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink><filename>}</filename>,
1520 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink><filename>}</filename>,
1521 and <filename>files</filename>.
1522 The directories are assumed to be subdirectories of the
1523 directory in which the recipe or append file resides.
1524 For another example that specifies these types of files, see the
1525 "<link linkend='usingpoky-extend-addpkg-singlec'>Single .c File Package (Hello World!)</link>"
1526 section.
1527 </para>
1528
1529 <para>
1530 The previous example also specifies a patch file.
1531 Patch files are files whose names end in
1532 <filename>.patch</filename> or <filename>.diff</filename>.
1533 The build system automatically applies patches as described
1534 in the
1535 "<link linkend='new-recipe-patching-code'>Patching Code</link>" section.
1590 </para> 1536 </para>
1591 </section> 1537 </section>
1592 1538
@@ -1620,6 +1566,32 @@
1620 </para> 1566 </para>
1621 </section> 1567 </section>
1622 1568
1569 <section id='new-recipe-patching-code'>
1570 <title>Patching Code</title>
1571
1572 <para>
1573 Sometimes it is necessary to patch code after it has been
1574 fetched.
1575 Any files mentioned in <filename>SRC_URI</filename> whose
1576 names end in <filename>.patch</filename> or
1577 <filename>.diff</filename> are treated as patches.
1578 The <filename>do_patch</filename> task automatically applies
1579 these patches.
1580 </para>
1581
1582 <para>
1583 The build system should be able to apply patches with the "-p1"
1584 option (i.e. one directory level in the path will be stripped
1585 off).
1586 If your patch needs to have more directory levels stripped off,
1587 specify the number of levels using the "striplevel" option in
1588 the <filename>SRC_URI</filename> entry for the patch.
1589 Alternatively, if your patch needs to be applied in a specific
1590 subdirectory that is not specified in the patch file, use the
1591 "patchdir" option in the entry.
1592 </para>
1593 </section>
1594
1623 <section id='new-recipe-licensing'> 1595 <section id='new-recipe-licensing'>
1624 <title>Licensing</title> 1596 <title>Licensing</title>
1625 1597