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