From b55ffe73568e6cf0f07b6212a75b78a5d5a011f1 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 16 Dec 2013 14:27:50 -0600 Subject: dev-manual: Updates to "Writing a Recipe" section. Updated the recipe creation figure. I had to re-order the flow and also generalize the supporting services installation part of the diagram. Fleshed out the "Fecthing" section with SRC_URI examples and much more detail. (From yocto-docs rev: 6a23ab2beb90376c11c426ac8bf5618994585a9d) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 193 +++++++++++++++++---- .../dev-manual/figures/recipe-workflow.png | Bin 33081 -> 38483 bytes 2 files changed, 157 insertions(+), 36 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 2e011724c3..9fb2b1c550 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -1155,7 +1155,7 @@ The following figure shows the basic process for creating a new recipe. Subsequent sections provide details for each step. - + @@ -1180,14 +1180,17 @@ have to add from scratch, and so forth. All these risks stem from unfamiliarity with the existing recipe space. - Use and modify a skeleton - recipe: - Using the skeleton recipe located at - <Need some path for a good recipe to use> is the - recommended method for creating a new recipe. - The skeleton recipe provides the fundamental areas - that you need to include, exclude, or alter to fit - your needs. + Use and modify the following + skeleton recipe: + + I need a simple + skeleton recipe + here + + Modifying this recipe is the recommended method for + creating a new recipe. + The recipe provides the fundamental areas that you need + to include, exclude, or alter to fit your needs. @@ -1197,40 +1200,140 @@ Fetching Code - The first thing your recipe must do is fetch the source files. + The first thing your recipe must do is specify how to fetch + the source files. Fetching is controlled mainly through the SRC_URI variable. Your recipe must have a SRC_URI variable that points to where the source is located. + For a graphical representation of source locations, see the + "Sources" + section in the Yocto Project Reference Manual. + + + The do_fetch task uses the - variable and its prefix to determine what fetcher to use to - get your source files. + SRC_URI variable and its prefix 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 + FILESOVERRIDES when scanning directory names for files in SRC_URI. - The instance (or instances) of the SRC_URI + The instance of the SRC_URI variable in your recipe must define each unique location for your source files. - For example, if you need a tarball, and two patches, then your - SRC_URI statement(s) must point to the - tarball and the patches. + 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: + + SRC_URI = "ftp://ftp.berlios.de/pub/cdrecord/alpha/cdrtools-${PV}.tar.bz2" + - I need some good examples here. - I also need some sample error messages you get when you don't - have the correct SRC_URI locations. - We can describe how you can copy and past the lines from the - error message and use the correct values. + 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. + + SRC_URI = "http://dist.schmorp.de/rxvt-unicode/Attic/rxvt-unicode-${PV}.tar.bz2 \ + file://xwc.patch \ + file://rxvt.desktop \ + file://rxvt.png" + + + + + The following list discusses some information worth noting when + you provide the SRC_URI variable in your + recipe: + + + 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}. + + 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. + + 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. + + + 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. + + Patches should be applicable with the "-p1" option to + patch (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. + + + 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" + PV = "1.0.5+git${SRCPV}" + + SRC_URI = "git://git.kernel.dk/blktrace.git \ + file://ldflags.patch" + + @@ -1263,18 +1366,6 @@ license shipped with the source. -
- Supporting Services - - - We'll probably also need some subsections on specific extra functions needed in -some recipes e.g. how to add support for services (sysvinit and systemd), -adding PACKAGECONFIG options, dealing with alternatives, etc. There's a -question in my mind on how some of these will overlap with the class reference -section though. - -
-
Configuring the Recipe @@ -1302,8 +1393,8 @@ the target, etc.
-
- Optionally Installing +
+ Installing install: for autotools/cmake recipes, if the recipe passes through do_install @@ -1313,6 +1404,36 @@ failure. For non-autotools recipes you need to define your own do_install
+
+ Supporting Services + + + We'll probably also need some subsections on specific extra functions needed in +some recipes e.g. how to add support for services (sysvinit and systemd), +adding PACKAGECONFIG options, dealing with alternatives, etc. There's a +question in my mind on how some of these will overlap with the class reference +section though. + + + + If you are adding services and the service initialization + script or the service file itself is not installed, you must + provide for that installation in your recipe. + If your recipe already has a do_install + function, you will need to create a + do_install_append function to handle the + installation of your services. + + + + When you create the installation for your services, you need + to accomplish what is normally done by "make install". + In other words, make sure your installation puts the output + in a layout that is similar to how they will be laid out on the + target system. + +
+
Packaging diff --git a/documentation/dev-manual/figures/recipe-workflow.png b/documentation/dev-manual/figures/recipe-workflow.png index 2c05e94745..96c14bbcbf 100644 Binary files a/documentation/dev-manual/figures/recipe-workflow.png and b/documentation/dev-manual/figures/recipe-workflow.png differ -- cgit v1.2.3-54-g00ecf