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 @@
- The do_fetch task uses the
- SRC_URI variable and its prefix to
- determine what fetcher to use to get your source files.
+ The do_fetch task uses the prefix of
+ each entry in the SRC_URI variable value
+ to determine what fetcher to use to get your source files.
It is the SRC_URI variable that triggers
the fetcher.
The do_patch task uses the variable after
source is fetched to apply patches.
The OpenEmbedded build system uses
FILESOVERRIDES
- when scanning directory names for files in
+ for scanning directory locations for local files in
SRC_URI.
- The instance of the SRC_URI
- variable in your recipe must define each unique location
- for your source files.
+ The SRC_URI 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 SRC_URI.
+ Rather than hard-code these paths, use
+ ${PV},
+ 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.
+
+
+
Here is a simple example from the
meta/recipes-devtools/cdrtools/cdrtools-native_3.01a17.bb
- recipe where the source comes from a single tarball:
+ recipe where the source comes from a single tarball.
+ Notice the use of the
+ PV
+ variable:
SRC_URI = "ftp://ftp.berlios.de/pub/cdrecord/alpha/cdrtools-${PV}.tar.bz2"
+
+ Files mentioned in SRC_URI whose names end
+ in a typical archive extension (e.g. .tar,
+ .tar.gz, .tar.bz2,
+ .zip, and so forth), are automatically
+ extracted during the do_unpack task.
+ For another example that specifies these types of files, see
+ the
+ "Autotooled Package"
+ section.
+
+
This next example is more complicated and is from the
meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.19.bb
recipe.
The example uses a SRC_URI 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.
SRC_URI = "http://dist.schmorp.de/rxvt-unicode/Attic/rxvt-unicode-${PV}.tar.bz2 \
file://xwc.patch \
@@ -1448,83 +1474,54 @@
- The following list discusses some information worth noting when
- you provide the SRC_URI variable in your
- recipe:
-
- Avoid hard-coding URLs:
- Rather than hard-coding the version in an URL, it is
- good practice to use
- ${PV},
- 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 ${PV}.
- Using the file:// URI protocol:
- When you specify local files using the
- file:// URI protocol, the build
- system fetches files from the local machine.
- The path is relative to the
- FILESPATH
- variable and searches specific directories in a
- certain order:
- ${BPN},
- ${BP},
- and files.
- The directories are assumed to be subdirectories of
- the directory in which the recipe or append file
- resides.
- For more information, see the
- SRC_URI
- variable.
- You can also reference the
- "Single .c File Package (Hello World!)"
- section for an example recipe.
- Specifying patch files:
- Files mentioned in SRC_URI whose
- names end in .patch or
- .diff are treated as patches and
- are automatically applied during the
- do_patch task.
- 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 SRC_URI
- 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.
-
- Extracting archived source files:
- Files mentioned in SRC_URI whose
- names end in a typical archive extension
- (e.g. .tar,
- .tar.gz,
- .tar.bz2,
- .zip, and so forth),
- are automatically extracted during
- the do_unpack task.
-
- See the
- "Autotooled Package"
- section for an example recipe that uses Autotools and
- whose SRC_URI points to archived
- source files.
- Specifying source from an SCM:
- For Git repositories, you must specify
- SRCREV
- and you should specify
- PV
- to include the revision with
- SRCPV.
- Here is an example from the recipe
- meta/recipes-kernel/blktrace/blktrace_git.bb:
-
+ When you specify local files using the
+ file:// URI protocol, the build system
+ fetches files from the local machine.
+ The path is relative to the
+ FILESPATH
+ variable and searches specific directories in a certain order:
+ ${BPN},
+ ${BP},
+ and files.
+ 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
+ "Single .c File Package (Hello World!)"
+ section.
+
+
+
+ The previous example also specifies a patch file.
+ Patch files are files whose names end in
+ .patch or .diff.
+ The build system automatically applies patches as described
+ in the
+ "Patching Code" section.
+
+
+
+ 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 SRC_URI 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.
+
+
+
+ A final way of specifying source is from an SCM.
+ For Git repositories, you must specify
+ SRCREV
+ and you should specify
+ PV
+ to include the revision with
+ SRCPV.
+ Here is an example from the recipe
+ meta/recipes-kernel/blktrace/blktrace_git.bb:
+
SRCREV = "d6918c8832793b4205ed3bfede78c2f915c23385"
PR = "r6"
@@ -1532,8 +1529,7 @@
SRC_URI = "git://git.kernel.dk/blktrace.git \
file://ldflags.patch"
-
-
+
@@ -1544,8 +1540,8 @@
ensure they have not been tampered with or otherwise modified
since the recipe was written.
Two checksums are used:
- SRC_URI[md5sum] = "" and
- SRC_URI[sha256sum] = "".
+ SRC_URI[md5sum] and
+ SRC_URI[sha256sum].
@@ -1580,6 +1576,20 @@
+
+ Patching Code
+
+
+ Sometimes it is necessary to patch code after it has been
+ fetched.
+ Any files mentioned in SRC_URI whose
+ names end in .patch or
+ .diff are treated as patches.
+ The do_patch task automatically applies
+ these patches.
+
+
+
Unpacking Code