mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-06-01 13:09:50 +00:00
Code Issues Projects Releases Wiki Activity

dev-manual: Edits to "Fetching Code" section.

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