From a1cb6dbc366f48adb5e05fcf8fee26f5e6cc9525 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 8 Jan 2014 14:04:45 -0600 Subject: 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 Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 192 +++++++++++---------- 1 file changed, 101 insertions(+), 91 deletions(-) (limited to 'documentation') 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 @@ - 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 -- cgit v1.1