summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2014-01-08 14:04:45 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-01-21 21:57:58 +0000
commita1cb6dbc366f48adb5e05fcf8fee26f5e6cc9525 (patch)
tree214a85e59f8a3dcb44084e3a8df6aeeaf4fa8b45 /documentation/dev-manual
parent32d69605c6525a4dcfbda2a81a736229223d0d78 (diff)
downloadpoky-a1cb6dbc366f48adb5e05fcf8fee26f5e6cc9525.tar.gz
dev-manual: Edits to "Fetching Code" section.
Applied review comments to this section. Specifically, I addressed the organization and got rid of the bullet list. I integrated this information into the examples used for the various SRC_URI snippits. Also, part of the feedback including separating out the patching information into an isolated section. I set up the section and moved minimal information into it. (From yocto-docs rev: 0a16977c2125402cdd04e24ad5bce074859eb28a) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.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.xml192
1 files changed, 101 insertions, 91 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 28ff9c08e9..36f67f10c3 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1407,38 +1407,64 @@
1407 </para> 1407 </para>
1408 1408
1409 <para> 1409 <para>
1410 The <filename>do_fetch</filename> task uses the 1410 The <filename>do_fetch</filename> task uses the prefix of
1411 <filename>SRC_URI</filename> variable and its prefix to 1411 each entry in the <filename>SRC_URI</filename> variable value
1412 determine what fetcher to use to get your source files. 1412 to determine what fetcher to use to get your source files.
1413 It is the <filename>SRC_URI</filename> variable that triggers 1413 It is the <filename>SRC_URI</filename> variable that triggers
1414 the fetcher. 1414 the fetcher.
1415 The <filename>do_patch</filename> task uses the variable after 1415 The <filename>do_patch</filename> task uses the variable after
1416 source is fetched to apply patches. 1416 source is fetched to apply patches.
1417 The OpenEmbedded build system uses 1417 The OpenEmbedded build system uses
1418 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></ulink> 1418 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></ulink>
1419 when scanning directory names for files in 1419 for scanning directory locations for local files in
1420 <filename>SRC_URI</filename>. 1420 <filename>SRC_URI</filename>.
1421 </para> 1421 </para>
1422 1422
1423 <para> 1423 <para>
1424 The instance of the <filename>SRC_URI</filename> 1424 The <filename>SRC_URI</filename> variable in your recipe must
1425 variable in your recipe must define each unique location 1425 define each unique location for your source files.
1426 for your source files. 1426 It is good practice to not hard-code pathnames in an URL used
1427 in <filename>SRC_URI</filename>.
1428 Rather than hard-code these paths, use
1429 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink><filename>}</filename>,
1430 which causes the fetch process to use the version specified in
1431 the recipe filename.
1432 Specifying the version in this manner means that upgrading the
1433 recipe to a future version is as simple as renaming the recipe
1434 to match the new version.
1435 </para>
1436
1437 <para>
1427 Here is a simple example from the 1438 Here is a simple example from the
1428 <filename>meta/recipes-devtools/cdrtools/cdrtools-native_3.01a17.bb</filename> 1439 <filename>meta/recipes-devtools/cdrtools/cdrtools-native_3.01a17.bb</filename>
1429 recipe where the source comes from a single tarball: 1440 recipe where the source comes from a single tarball.
1441 Notice the use of the
1442 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
1443 variable:
1430 <literallayout class='monospaced'> 1444 <literallayout class='monospaced'>
1431 SRC_URI = "ftp://ftp.berlios.de/pub/cdrecord/alpha/cdrtools-${PV}.tar.bz2" 1445 SRC_URI = "ftp://ftp.berlios.de/pub/cdrecord/alpha/cdrtools-${PV}.tar.bz2"
1432 </literallayout> 1446 </literallayout>
1433 </para> 1447 </para>
1434 1448
1435 <para> 1449 <para>
1450 Files mentioned in <filename>SRC_URI</filename> whose names end
1451 in a typical archive extension (e.g. <filename>.tar</filename>,
1452 <filename>.tar.gz</filename>, <filename>.tar.bz2</filename>,
1453 <filename>.zip</filename>, and so forth), are automatically
1454 extracted during the <filename>do_unpack</filename> task.
1455 For another example that specifies these types of files, see
1456 the
1457 "<link linkend='usingpoky-extend-addpkg-autotools'>Autotooled Package</link>"
1458 section.
1459 </para>
1460
1461 <para>
1436 This next example is more complicated and is from the 1462 This next example is more complicated and is from the
1437 <filename>meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.19.bb</filename> 1463 <filename>meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.19.bb</filename>
1438 recipe. 1464 recipe.
1439 The example uses a <filename>SRC_URI</filename> statement 1465 The example uses a <filename>SRC_URI</filename> statement
1440 that identifies a tarball, a patch file, a desktop file, and a 1466 that identifies a tarball, a patch file, a desktop file, and an
1441 figure all as source code. 1467 icon as the source files for the recipe.
1442 <literallayout class='monospaced'> 1468 <literallayout class='monospaced'>
1443 SRC_URI = "http://dist.schmorp.de/rxvt-unicode/Attic/rxvt-unicode-${PV}.tar.bz2 \ 1469 SRC_URI = "http://dist.schmorp.de/rxvt-unicode/Attic/rxvt-unicode-${PV}.tar.bz2 \
1444 file://xwc.patch \ 1470 file://xwc.patch \
@@ -1448,83 +1474,54 @@
1448 </para> 1474 </para>
1449 1475
1450 <para> 1476 <para>
1451 The following list discusses some information worth noting when 1477 When you specify local files using the
1452 you provide the <filename>SRC_URI</filename> variable in your 1478 <filename>file://</filename> URI protocol, the build system
1453 recipe: 1479 fetches files from the local machine.
1454 <itemizedlist> 1480 The path is relative to the
1455 <listitem><para><emphasis>Avoid hard-coding URLs:</emphasis> 1481 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
1456 Rather than hard-coding the version in an URL, it is 1482 variable and searches specific directories in a certain order:
1457 good practice to use 1483 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink><filename>}</filename>,
1458 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink><filename>}</filename>, 1484 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink><filename>}</filename>,
1459 which causes the fetch process to use the version 1485 and <filename>files</filename>.
1460 specified in the recipe filename. 1486 The directories are assumed to be subdirectories of the
1461 Specifying the version in this manner means that 1487 directory in which the recipe or append file resides.
1462 upgrading the recipe to a future version is as simple 1488 For another example that specifies these types of files, see the
1463 as renaming the recipe to match the new version. 1489 "<link linkend='usingpoky-extend-addpkg-singlec'>Single .c File Package (Hello World!)</link>"
1464 Notice that the two examples in the previous paragraph 1490 section.
1465 both use <filename>${PV}</filename>.</para></listitem> 1491 </para>
1466 <listitem><para><emphasis>Using the <filename>file://</filename> URI protocol:</emphasis> 1492
1467 When you specify local files using the 1493 <para>
1468 <filename>file://</filename> URI protocol, the build 1494 The previous example also specifies a patch file.
1469 system fetches files from the local machine. 1495 Patch files are files whose names end in
1470 The path is relative to the 1496 <filename>.patch</filename> or <filename>.diff</filename>.
1471 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> 1497 The build system automatically applies patches as described
1472 variable and searches specific directories in a 1498 in the
1473 certain order: 1499 "<link linkend='new-recipe-patching-code'>Patching Code</link>" section.
1474 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink><filename>}</filename>, 1500 </para>
1475 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink><filename>}</filename>, 1501
1476 and <filename>files</filename>. 1502 <para>
1477 The directories are assumed to be subdirectories of 1503 The build system should be able to apply patches with the "-p1"
1478 the directory in which the recipe or append file 1504 option (i.e. one directory level in the path will be stripped
1479 resides.</para> 1505 off).
1480 <para>For more information, see the 1506 If your patch needs to have more directory levels stripped off,
1481 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> 1507 specify the number of levels using the "striplevel" option in
1482 variable. 1508 the <filename>SRC_URI</filename> entry for the patch.
1483 You can also reference the 1509 Alternatively, if your patch needs to be applied in a specific
1484 "<link linkend='usingpoky-extend-addpkg-singlec'>Single .c File Package (Hello World!)</link>" 1510 subdirectory that is not specified in the patch file, use the
1485 section for an example recipe.</para></listitem> 1511 "patchdir" option in the entry.
1486 <listitem><para><emphasis>Specifying patch files:</emphasis> 1512 </para>
1487 Files mentioned in <filename>SRC_URI</filename> whose 1513
1488 names end in <filename>.patch</filename> or 1514 <para>
1489 <filename>.diff</filename> are treated as patches and 1515 A final way of specifying source is from an SCM.
1490 are automatically applied during the 1516 For Git repositories, you must specify
1491 <filename>do_patch</filename> task.</para> 1517 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
1492 <para>The build system should be able to apply patches 1518 and you should specify
1493 with the "-p1" option (i.e. one directory level in the 1519 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
1494 path will be stripped off). 1520 to include the revision with
1495 If your patch needs to have more directory levels 1521 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>.
1496 stripped off, specify the number of levels using the 1522 Here is an example from the recipe
1497 "striplevel" option in the <filename>SRC_URI</filename> 1523 <filename>meta/recipes-kernel/blktrace/blktrace_git.bb</filename>:
1498 entry for the patch. 1524 <literallayout class='monospaced'>
1499 Alternatively, if your patch needs to be applied in a
1500 specific subdirectory that is not specified in the patch
1501 file, use the "patchdir" option in the entry.
1502 </para></listitem>
1503 <listitem><para><emphasis>Extracting archived source files:</emphasis>
1504 Files mentioned in <filename>SRC_URI</filename> whose
1505 names end in a typical archive extension
1506 (e.g. <filename>.tar</filename>,
1507 <filename>.tar.gz</filename>,
1508 <filename>.tar.bz2</filename>,
1509 <filename>.zip</filename>, and so forth),
1510 are automatically extracted during
1511 the <filename>do_unpack</filename> task.
1512 </para>
1513 <para>See the
1514 "<link linkend='usingpoky-extend-addpkg-autotools'>Autotooled Package</link>"
1515 section for an example recipe that uses Autotools and
1516 whose <filename>SRC_URI</filename> points to archived
1517 source files.</para></listitem>
1518 <listitem><para><emphasis>Specifying source from an SCM:</emphasis>
1519 For Git repositories, you must specify
1520 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
1521 and you should specify
1522 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
1523 to include the revision with
1524 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>.
1525 Here is an example from the recipe
1526 <filename>meta/recipes-kernel/blktrace/blktrace_git.bb</filename>:
1527 <literallayout class='monospaced'>
1528 SRCREV = "d6918c8832793b4205ed3bfede78c2f915c23385" 1525 SRCREV = "d6918c8832793b4205ed3bfede78c2f915c23385"
1529 1526
1530 PR = "r6" 1527 PR = "r6"
@@ -1532,8 +1529,7 @@
1532 1529
1533 SRC_URI = "git://git.kernel.dk/blktrace.git \ 1530 SRC_URI = "git://git.kernel.dk/blktrace.git \
1534 file://ldflags.patch" 1531 file://ldflags.patch"
1535 </literallayout></para></listitem> 1532 </literallayout>
1536 </itemizedlist>
1537 </para> 1533 </para>
1538 1534
1539 <para> 1535 <para>
@@ -1544,8 +1540,8 @@
1544 ensure they have not been tampered with or otherwise modified 1540 ensure they have not been tampered with or otherwise modified
1545 since the recipe was written. 1541 since the recipe was written.
1546 Two checksums are used: 1542 Two checksums are used:
1547 <filename>SRC_URI[md5sum] = ""</filename> and 1543 <filename>SRC_URI[md5sum]</filename> and
1548 <filename>SRC_URI[sha256sum] = ""</filename>. 1544 <filename>SRC_URI[sha256sum]</filename>.
1549 </para> 1545 </para>
1550 1546
1551 <para> 1547 <para>
@@ -1580,6 +1576,20 @@
1580 </para> 1576 </para>
1581 </section> 1577 </section>
1582 1578
1579 <section id='new-recipe-patching-code'>
1580 <title>Patching Code</title>
1581
1582 <para>
1583 Sometimes it is necessary to patch code after it has been
1584 fetched.
1585 Any files mentioned in <filename>SRC_URI</filename> whose
1586 names end in <filename>.patch</filename> or
1587 <filename>.diff</filename> are treated as patches.
1588 The <filename>do_patch</filename> task automatically applies
1589 these patches.
1590 </para>
1591 </section>
1592
1583 <section id='new-recipe-unpacking-code'> 1593 <section id='new-recipe-unpacking-code'>
1584 <title>Unpacking Code</title> 1594 <title>Unpacking Code</title>
1585 1595