From e987fa8e489a1392b0faa1b362cbc720b9ba3551 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 10 Jan 2014 17:24:54 -0600 Subject: dev-manual: Edits to the "Writing a New Recipe" section. Implemented some third review feedback from Paul Eggleton. (From yocto-docs rev: 3fd9c3cc4cf2aba876f0ad2ab36660ec32ea4c08) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 206 +++++++++------------ 1 file changed, 89 insertions(+), 117 deletions(-) diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 1f552d8d3b..331700bdea 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -1172,11 +1172,10 @@ Before writing a recipe from scratch, it is often useful to discover whether someone else has already written one that meets (or comes close to meeting) your needs. - The Yocto Project and OpenEmbedded communities contain - and maintain many recipes that might be candidates for what - you are doing. + The Yocto Project and OpenEmbedded communities maintain many + recipes that might be candidates for what you are doing. You can find a good central index of these recipes in the - OpenEmbedded metadata index. + OpenEmbedded metadata index. @@ -1221,47 +1220,6 @@ - - - Regardless of where you get a base recipe, you will need to - make changes to support your needs. - When you do, you need to be aware of how BitBake parses curly - braces. - If a recipe uses a closing curly brace within the function and - the character has no leading spaces, BitBake produces a parsing - error. - If you use a pair of curly brace in a shell function, the - closing curly brace must not be located at the start of the line - without leading spaces. - - - - Here is an example that causes BitBake to produce a parsing - error: - - fakeroot create_shar() { - cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh - usage() - { - echo "test" - ###### The following "}" at the start of the line causes a parsing error ###### - } - EOF - } - - Writing the recipe this way avoids the error: - - fakeroot create_shar() { - cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh - usage() - { - echo "test" - ######The following "}" with a leading space at the start of the line avoids the error ###### - } - EOF - } - -
@@ -1278,7 +1236,8 @@ Storing Your Recipe: The OpenEmbedded build system locates your recipe - through the layer.conf file and the + through the layer's conf/layer.conf + file and the BBFILES variable. This variable sets up a path from which the build system can @@ -1303,7 +1262,8 @@ Use lower-cased characters and do not include the reserved suffixes -native, -cross, -initial, - or -dev. + or -dev casually (i.e. do not use them + as part of your recipe name unless the string applies). Here are some examples: cups_1.7.0.bb @@ -1331,19 +1291,21 @@ and you are in the Build Directory, use BitBake to process your recipe. - All you need to provide is the base name of your recipe: + All you need to provide is the + <basename> of the recipe as described + in the previous section: $ bitbake <basename> + During the build, the OpenEmbedded build system creates a temporary work directory for the recipe (${WORKDIR}) - where it keeps extracted source files, log files, images, and - so forth. - You can find individual logs in this area for each task. + where it keeps extracted source files, log files, intermediate + compilation and packaging files, and so forth. @@ -1368,6 +1330,15 @@ and temp. After the build, you can examine these to determine how well the build went. + + You can find individual log files for individual recipes in + their temp directory (e.g. + poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0/temp). + Log files are named log.do_<taskname> + (e.g. log.do_configure, + log.do_fetch, and + log.do_compile). + @@ -1381,9 +1352,10 @@ Yocto Project Reference Manual's glossary for more information: The temporary directory - TMPDIR - The machine architecture - MULTIMACH_TARGET_SYS + The target architecture - MULTIMACH_TARGET_SYS The recipe name - PN - The epoch - EXTENDPE + The epoch - EXTENDPE + (if specified - blank for most recipes) The recipe version - PV The recipe revision - PR @@ -1459,60 +1431,7 @@ - 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 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 \ - file://rxvt.desktop \ - file://rxvt.png" - - - - - 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. + Another way of specifying source is from an SCM. For Git repositories, you must specify SRCREV and you should specify @@ -1574,19 +1493,46 @@ Once you have the correct checksums, simply copy them into your recipe for a subsequent build. -
-
- Patching Code + + This final example is a bit more complicated and is from the + meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.19.bb + recipe. + The example's SRC_URI statement identifies + multiple files as the source files for the recipe: a tarball, a + patch file, a desktop file, and an icon. + + SRC_URI = "http://dist.schmorp.de/rxvt-unicode/Attic/rxvt-unicode-${PV}.tar.bz2 \ + file://xwc.patch \ + file://rxvt.desktop \ + file://rxvt.png" + + - 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. + 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.
@@ -1620,6 +1566,32 @@ +
+ 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. + + + + 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. + +
+
Licensing -- cgit v1.2.3-54-g00ecf