diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2014-01-08 14:04:45 -0600 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2014-01-21 21:57:58 +0000 |
commit | a1cb6dbc366f48adb5e05fcf8fee26f5e6cc9525 (patch) | |
tree | 214a85e59f8a3dcb44084e3a8df6aeeaf4fa8b45 /documentation | |
parent | 32d69605c6525a4dcfbda2a81a736229223d0d78 (diff) | |
download | ast2050-yocto-poky-a1cb6dbc366f48adb5e05fcf8fee26f5e6cc9525.zip ast2050-yocto-poky-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')
-rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 192 |
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 28ff9c0..36f67f1 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -1407,38 +1407,64 @@ </para> <para> - The <filename>do_fetch</filename> task uses the - <filename>SRC_URI</filename> variable and its prefix to - determine what fetcher to use to get your source files. + The <filename>do_fetch</filename> task uses the prefix of + each entry in the <filename>SRC_URI</filename> variable value + to determine what fetcher to use to get your source files. It is the <filename>SRC_URI</filename> variable that triggers the fetcher. The <filename>do_patch</filename> task uses the variable after source is fetched to apply patches. The OpenEmbedded build system uses <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></ulink> - when scanning directory names for files in + for scanning directory locations for local files in <filename>SRC_URI</filename>. </para> <para> - The instance of the <filename>SRC_URI</filename> - variable in your recipe must define each unique location - for your source files. + The <filename>SRC_URI</filename> variable in your recipe must + define each unique location for your source files. + It is good practice to not hard-code pathnames in an URL used + in <filename>SRC_URI</filename>. + Rather than hard-code these paths, use + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink><filename>}</filename>, + which causes the fetch process to use the version specified in + the recipe filename. + Specifying the version in this manner means that upgrading the + recipe to a future version is as simple as renaming the recipe + to match the new version. + </para> + + <para> Here is a simple example from the <filename>meta/recipes-devtools/cdrtools/cdrtools-native_3.01a17.bb</filename> - recipe where the source comes from a single tarball: + recipe where the source comes from a single tarball. + Notice the use of the + <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> + variable: <literallayout class='monospaced'> SRC_URI = "ftp://ftp.berlios.de/pub/cdrecord/alpha/cdrtools-${PV}.tar.bz2" </literallayout> </para> <para> + Files mentioned in <filename>SRC_URI</filename> whose names end + in a typical archive extension (e.g. <filename>.tar</filename>, + <filename>.tar.gz</filename>, <filename>.tar.bz2</filename>, + <filename>.zip</filename>, and so forth), are automatically + extracted during the <filename>do_unpack</filename> task. + For another example that specifies these types of files, see + the + "<link linkend='usingpoky-extend-addpkg-autotools'>Autotooled Package</link>" + section. + </para> + + <para> This next example is more complicated and is from the <filename>meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.19.bb</filename> recipe. The example uses a <filename>SRC_URI</filename> statement - that identifies a tarball, a patch file, a desktop file, and a - figure all as source code. + that identifies a tarball, a patch file, a desktop file, and an + icon as the source files for the recipe. <literallayout class='monospaced'> SRC_URI = "http://dist.schmorp.de/rxvt-unicode/Attic/rxvt-unicode-${PV}.tar.bz2 \ file://xwc.patch \ @@ -1448,83 +1474,54 @@ </para> <para> - The following list discusses some information worth noting when - you provide the <filename>SRC_URI</filename> variable in your - recipe: - <itemizedlist> - <listitem><para><emphasis>Avoid hard-coding URLs:</emphasis> - Rather than hard-coding the version in an URL, it is - good practice to use - <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink><filename>}</filename>, - which causes the fetch process to use the version - specified in the recipe filename. - Specifying the version in this manner means that - upgrading the recipe to a future version is as simple - as renaming the recipe to match the new version. - Notice that the two examples in the previous paragraph - both use <filename>${PV}</filename>.</para></listitem> - <listitem><para><emphasis>Using the <filename>file://</filename> URI protocol:</emphasis> - When you specify local files using the - <filename>file://</filename> URI protocol, the build - system fetches files from the local machine. - The path is relative to the - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> - variable and searches specific directories in a - certain order: - <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink><filename>}</filename>, - <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink><filename>}</filename>, - and <filename>files</filename>. - The directories are assumed to be subdirectories of - the directory in which the recipe or append file - resides.</para> - <para>For more information, see the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - variable. - You can also reference the - "<link linkend='usingpoky-extend-addpkg-singlec'>Single .c File Package (Hello World!)</link>" - section for an example recipe.</para></listitem> - <listitem><para><emphasis>Specifying patch files:</emphasis> - Files mentioned in <filename>SRC_URI</filename> whose - names end in <filename>.patch</filename> or - <filename>.diff</filename> are treated as patches and - are automatically applied during the - <filename>do_patch</filename> task.</para> - <para>The build system should be able to apply patches - with the "-p1" option (i.e. one directory level in the - path will be stripped off). - If your patch needs to have more directory levels - stripped off, specify the number of levels using the - "striplevel" option in the <filename>SRC_URI</filename> - entry for the patch. - Alternatively, if your patch needs to be applied in a - specific subdirectory that is not specified in the patch - file, use the "patchdir" option in the entry. - </para></listitem> - <listitem><para><emphasis>Extracting archived source files:</emphasis> - Files mentioned in <filename>SRC_URI</filename> whose - names end in a typical archive extension - (e.g. <filename>.tar</filename>, - <filename>.tar.gz</filename>, - <filename>.tar.bz2</filename>, - <filename>.zip</filename>, and so forth), - are automatically extracted during - the <filename>do_unpack</filename> task. - </para> - <para>See the - "<link linkend='usingpoky-extend-addpkg-autotools'>Autotooled Package</link>" - section for an example recipe that uses Autotools and - whose <filename>SRC_URI</filename> points to archived - source files.</para></listitem> - <listitem><para><emphasis>Specifying source from an SCM:</emphasis> - For Git repositories, you must specify - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink> - and you should specify - <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> - to include the revision with - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>. - Here is an example from the recipe - <filename>meta/recipes-kernel/blktrace/blktrace_git.bb</filename>: - <literallayout class='monospaced'> + When you specify local files using the + <filename>file://</filename> URI protocol, the build system + fetches files from the local machine. + The path is relative to the + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> + variable and searches specific directories in a certain order: + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink><filename>}</filename>, + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink><filename>}</filename>, + and <filename>files</filename>. + The directories are assumed to be subdirectories of the + directory in which the recipe or append file resides. + For another example that specifies these types of files, see the + "<link linkend='usingpoky-extend-addpkg-singlec'>Single .c File Package (Hello World!)</link>" + section. + </para> + + <para> + The previous example also specifies a patch file. + Patch files are files whose names end in + <filename>.patch</filename> or <filename>.diff</filename>. + The build system automatically applies patches as described + in the + "<link linkend='new-recipe-patching-code'>Patching Code</link>" section. + </para> + + <para> + The build system should be able to apply patches with the "-p1" + option (i.e. one directory level in the path will be stripped + off). + If your patch needs to have more directory levels stripped off, + specify the number of levels using the "striplevel" option in + the <filename>SRC_URI</filename> entry for the patch. + Alternatively, if your patch needs to be applied in a specific + subdirectory that is not specified in the patch file, use the + "patchdir" option in the entry. + </para> + + <para> + A final way of specifying source is from an SCM. + For Git repositories, you must specify + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink> + and you should specify + <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> + to include the revision with + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>. + Here is an example from the recipe + <filename>meta/recipes-kernel/blktrace/blktrace_git.bb</filename>: + <literallayout class='monospaced'> SRCREV = "d6918c8832793b4205ed3bfede78c2f915c23385" PR = "r6" @@ -1532,8 +1529,7 @@ SRC_URI = "git://git.kernel.dk/blktrace.git \ file://ldflags.patch" - </literallayout></para></listitem> - </itemizedlist> + </literallayout> </para> <para> @@ -1544,8 +1540,8 @@ ensure they have not been tampered with or otherwise modified since the recipe was written. Two checksums are used: - <filename>SRC_URI[md5sum] = ""</filename> and - <filename>SRC_URI[sha256sum] = ""</filename>. + <filename>SRC_URI[md5sum]</filename> and + <filename>SRC_URI[sha256sum]</filename>. </para> <para> @@ -1580,6 +1576,20 @@ </para> </section> + <section id='new-recipe-patching-code'> + <title>Patching Code</title> + + <para> + Sometimes it is necessary to patch code after it has been + fetched. + Any files mentioned in <filename>SRC_URI</filename> whose + names end in <filename>.patch</filename> or + <filename>.diff</filename> are treated as patches. + The <filename>do_patch</filename> task automatically applies + these patches. + </para> + </section> + <section id='new-recipe-unpacking-code'> <title>Unpacking Code</title> |