diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2013-12-16 14:27:50 -0600 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2014-01-02 13:16:11 +0000 |
commit | b55ffe73568e6cf0f07b6212a75b78a5d5a011f1 (patch) | |
tree | 084bc4a586b719cc2fa11f4b6e05bfa953196b21 | |
parent | 4abc384f253fab140324ac9e243b000dc5d6ae8c (diff) | |
download | ast2050-yocto-poky-b55ffe73568e6cf0f07b6212a75b78a5d5a011f1.zip ast2050-yocto-poky-b55ffe73568e6cf0f07b6212a75b78a5d5a011f1.tar.gz |
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 <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 193 | ||||
-rw-r--r-- | documentation/dev-manual/figures/recipe-workflow.png | bin | 33081 -> 38483 bytes |
2 files changed, 157 insertions, 36 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 2e01172..9fb2b1c 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. - <imagedata fileref="figures/recipe-workflow.png" width="4in" depth="7in" align="center" scalefit="1" /> + <imagedata fileref="figures/recipe-workflow.png" width="6in" depth="7in" align="center" scalefit="1" /> </para> </section> @@ -1180,14 +1180,17 @@ have to add from scratch, and so forth. All these risks stem from unfamiliarity with the existing recipe space.</para></listitem> - <listitem><para><emphasis>Use and modify a skeleton - recipe:</emphasis> - 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. + <listitem><para><emphasis>Use and modify the following + skeleton recipe:</emphasis> + <literallayout class='monospaced'> + I need a simple + skeleton recipe + here + </literallayout> + 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. </para></listitem> </itemizedlist> </para> @@ -1197,40 +1200,140 @@ <title>Fetching Code</title> <para> - 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 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> variable. Your recipe must have a <filename>SRC_URI</filename> variable that points to where the source is located. + For a graphical representation of source locations, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#sources-dev-environment'>Sources</ulink>" + section in the Yocto Project Reference Manual. + </para> + + <para> The <filename>do_fetch</filename> task uses the - variable and its prefix to determine what fetcher to use to - get your source files. + <filename>SRC_URI</filename> variable and its prefix to + determine what fetcher to use to get your source files. It is the <filename>SRC_URI</filename> variable that triggers the fetcher. The <filename>do_patch</filename> task uses the variable after source is fetched to apply patches. The OpenEmbedded build system uses - <ulink url='&YOCOT_DOCS_REF_URL;#var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></ulink> + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></ulink> when scanning directory names for files in <filename>SRC_URI</filename>. </para> <para> - The instance (or instances) of the <filename>SRC_URI</filename> + The instance of the <filename>SRC_URI</filename> 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 - <filename>SRC_URI</filename> statement(s) must point to the - tarball and the patches. + Here is a simple example from the + <filename>meta/recipes-devtools/cdrtools/cdrtools-native_3.01a17.bb</filename> + recipe where the source comes from a single tarball: + <literallayout class='monospaced'> + SRC_URI = "ftp://ftp.berlios.de/pub/cdrecord/alpha/cdrtools-${PV}.tar.bz2" + </literallayout> </para> <para> - I need some good examples here. - I also need some sample error messages you get when you don't - have the correct <filename>SRC_URI</filename> 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 + <filename>meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.19.bb</filename> + recipe. + The example uses a <filename>SRC_URI</filename> statement + that identifies a tarball, a patch file, a desktop file, and a + figure all as source code. + <literallayout class='monospaced'> + SRC_URI = "http://dist.schmorp.de/rxvt-unicode/Attic/rxvt-unicode-${PV}.tar.bz2 \ + file://xwc.patch \ + file://rxvt.desktop \ + file://rxvt.png" + </literallayout> + </para> + + <para> + The following list discusses some information worth noting when + you provide the <filename>SRC_URI</filename> variable in your + recipe: + <itemizedlist> + <listitem><para> + Rather than hard-coding the version in an URL, it is + good practice to use + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink><filename>}</filename>, + 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 <filename>${PV}</filename>.</para></listitem> + <listitem><para> + When you specify local files using the + <filename>file://</filename> URI protocol, the build + system fetches files from the local machine. + The path is relative to the + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> + variable and searches specific directories in a + certain order: + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink><filename>}</filename>, + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink><filename>}</filename>, + and + <filename>files</filename>. + The directories are assumed to be subdirectories of + the directory in which the recipe or append file + resides. + For more information, see the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + variable.</para></listitem> + <listitem><para> + Files mentioned in <filename>SRC_URI</filename> whose + names end in a typical archive extension + (e.g. <filename>.tar</filename>, + <filename>.tar.gz</filename>, + <filename>.tar.bz2</filename>, + <filename>.zip</filename>, and so forth), + are automatically extracted during + the <filename>do_unpack</filename> task. + </para></listitem> + <listitem><para> + Files mentioned in <filename>SRC_URI</filename> whose + names end in <filename>.patch</filename> or + <filename>.diff</filename> are treated as patches and + are automatically applied during the + <filename>do_patch</filename> task.</para></listitem> + <listitem><para> + 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 <filename>SRC_URI</filename> + 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. + </para></listitem> + <listitem><para> + For Git repositories, you must specify + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink> + and you should specify + <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> + to include the revision with + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>. + Here is an example from the recipe + <filename>meta/recipes-kernel/blktrace/blktrace_git.bb</filename>: + <literallayout class='monospaced'> + SRCREV = "d6918c8832793b4205ed3bfede78c2f915c23385" + + PR = "r6" + PV = "1.0.5+git${SRCPV}" + + SRC_URI = "git://git.kernel.dk/blktrace.git \ + file://ldflags.patch" + </literallayout></para></listitem> + </itemizedlist> </para> </section> @@ -1263,18 +1366,6 @@ license shipped with the source. </para> </section> - <section id='new-recipe-optionally-supporting-services'> - <title>Supporting Services</title> - - <para> - 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. - </para> - </section> - <section id='new-recipe-configuring-the-recipe'> <title>Configuring the Recipe</title> @@ -1302,8 +1393,8 @@ the target, etc. </para> </section> - <section id='new-recipe-optionally-installing'> - <title>Optionally Installing</title> + <section id='new-recipe-installing'> + <title>Installing</title> <para> 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 </para> </section> + <section id='new-recipe-optionally-supporting-services'> + <title>Supporting Services</title> + + <para> + 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. + </para> + + <para> + 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 <filename>do_install</filename> + function, you will need to create a + <filename>do_install_append</filename> function to handle the + installation of your services. + </para> + + <para> + 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. + </para> + </section> + <section id='new-recipe-packaging'> <title>Packaging</title> diff --git a/documentation/dev-manual/figures/recipe-workflow.png b/documentation/dev-manual/figures/recipe-workflow.png Binary files differindex 2c05e94..96c14bb 100644 --- a/documentation/dev-manual/figures/recipe-workflow.png +++ b/documentation/dev-manual/figures/recipe-workflow.png |