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>

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
-                        &lt;Need some path for a good recipe to use&gt; 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
index 2c05e94..96c14bb 100644
--- a/documentation/dev-manual/figures/recipe-workflow.png
+++ b/documentation/dev-manual/figures/recipe-workflow.png