dev-manual: Edits to "Writing a New Recipe"

Received and implemented some feedback from Paul Eggleton
on this section.  These were unsolicited observations.

Reported-by: Paul Eggleton <paul.eggleton@intel.com>
(From yocto-docs rev: 48ecc543d9f614b5258ab2573f0406aa3c778647)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 127 insertions, 59 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 2968b4d3c0..44fb9ff63a 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1896,6 +1896,16 @@
                 subdirectory that is not specified in the patch file, use the
                 "patchdir" option in the entry.
             </para>
+
+            <para>
+                As with all local files referenced in
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                using <filename>file://</filename>, you should place
+                patch files in a directory next to the recipe either
+                named the same as the base name of the recipe
+                (<ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink>),
+                or "files".
+            </para>
         </section>
 
         <section id='new-recipe-licensing'>
@@ -2190,9 +2200,23 @@
                         In these cases, you need to go back and add additional
                         options to the configure script as well as possibly
                         add additional build-time dependencies to
-                        <filename>DEPENDS</filename>.
-                        Occasionally, it is necessary to apply a patch to the
-                        source to ensure the correct paths are used.
+                        <filename>DEPENDS</filename>.</para>
+                        <para>Occasionally, it is necessary to apply a patch
+                        to the source to ensure the correct paths are used.
+                        If you need to specify paths to find files staged
+                        into the sysroot from other recipes, use the variables
+                        that the OpenEmbedded build system provides
+                        (e.g.
+                        <filename>STAGING_BINDIR</filename>,
+                        <filename>STAGING_INCDIR</filename>,
+                        <filename>STAGING_DATADIR</filename>, and so forth).
+<!--
+                        (e.g.
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_BINDIR'><filename>STAGING_BINDIR</filename></ulink>,
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_INCDIR'><filename>STAGING_INCDIR</filename></ulink>,
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_DATADIR'><filename>STAGING_DATADIR</filename></ulink>,
+                        and so forth).
+-->
                         </para></listitem>
                 </itemizedlist>
             </para>
@@ -2263,7 +2287,8 @@
                         recipe.
                         The function must first use
                         <filename>install -d</filename> to create the
-                        directories.
+                        directories under
+                        <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>.
                         Once the directories exist, your function can use
                         <filename>install</filename> to manually install the
                         built software into the directories.</para>
@@ -2398,56 +2423,100 @@
             <title>Packaging</title>
 
             <para>
-                The <filename>do_package</filename> task splits the files
-                produced by the recipe into logical components.
-                Even software that produces a single binary might still have
-                debug symbols, documentation, and other logical components
-                that should be split out.
-                The <filename>do_package</filename> task ensures that files
-                are split up and packaged correctly.
-            </para>
-
-            <para>
-                The <filename>insane</filename> class adds a step to the
-                package generation process so that output quality assurance
-                checks are generated by the OpenEmbedded build system.
-                This step performs a range of checks to be sure the build's
-                output is free of common problems that show up during runtime.
-                For information on these checks, see the
-                <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-insane'><filename>insane</filename></ulink>
-                class and the
-                "<ulink url='&YOCTO_DOCS_REF_URL;#ref-qa-checks'>QA Error and Warning Messages</ulink>"
-                chapter in the Yocto Project Reference Manual.
-            </para>
-
-            <para>
-                After you build your software, you need to be sure your packages
-                are correct.
-                Examine the
-                <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/packages-split</filename>
-                directory and make sure files are where you expect them to be.
-            </para>
-
-            <para>
-                If you discover problems, you can set
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>,
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>,
-                <filename>do_install(_append)</filename>, and so forth as
-                needed.
-            </para>
-
-            <para>
-                See the
-                "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>"
-                section for an example that shows how you might split
-                your software into more than one package.
-            </para>
-
-            <para>
-                For an example showing how to install a post-installation
-                script, see the
-                "<link linkend='new-recipe-post-installation-scripts'>Post-Installation Scripts</link>"
-                section.
+                Successful packaging is a combination of automated processes
+                performed by the OpenEmbedded build system and some
+                specific steps you need to take.
+                The following list describes the process:
+                <itemizedlist>
+                    <listitem><para><emphasis>Splitting Files</emphasis>:
+                        The <filename>do_package</filename> task splits the
+                        files produced by the recipe into logical components.
+                        Even software that produces a single binary might
+                        still have debug symbols, documentation, and other
+                        logical components that should be split out.
+                        The <filename>do_package</filename> task ensures
+                        that files are split up and packaged correctly.
+                        </para></listitem>
+                    <listitem><para><emphasis>Running QA Checks</emphasis>:
+                        The <filename>insane</filename> class adds a step to
+                        the package generation process so that output quality
+                        assurance checks are generated by the OpenEmbedded
+                        build system.
+                        This step performs a range of checks to be sure the
+                        build's output is free of common problems that show
+                        up during runtime.
+                        For information on these checks, see the
+                        <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-insane'><filename>insane</filename></ulink>
+                        class and the
+                        "<ulink url='&YOCTO_DOCS_REF_URL;#ref-qa-checks'>QA Error and Warning Messages</ulink>"
+                        chapter in the Yocto Project Reference Manual.
+                        </para></listitem>
+                    <listitem><para><emphasis>Hand-Checking Your Packages</emphasis>:
+                        After you build your software, you need to be sure
+                        your packages are correct.
+                        Examine the
+                        <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/packages-split</filename>
+                        directory and make sure files are where you expect
+                        them to be.
+                        If you discover problems, you can set
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>,
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>,
+                        <filename>do_install(_append)</filename>, and so forth as
+                        needed.
+                        </para></listitem>
+                    <listitem><para><emphasis>Splitting an Application into Multiple Packages</emphasis>:
+                        If you need to split an application into several
+                        packages, see the
+                        "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>"
+                        section for an example.
+                        </para></listitem>
+                    <listitem><para><emphasis>Installing a Post-Installation Script</emphasis>:
+                        For an example showing how to install a
+                        post-installation script, see the
+                        "<link linkend='new-recipe-post-installation-scripts'>Post-Installation Scripts</link>"
+                        section.
+                        </para></listitem>
+                    <listitem><para><emphasis>Marking Package Architecture</emphasis>:
+                        Depending on what your recipe is building and how it
+                        is configured, it might be important to mark the
+                        packages produced as being specific to a particular
+                        machine, or to mark them as not being specific to
+                        a particular machine or architecture at all.
+                        By default, packages produced for the target are
+                        marked as being specific to the architecture of the
+                        target machine because that is usually the desired
+                        result.
+                        However, if the recipe configures the software to be
+                        built specific to the target machine (e.g. the
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+                        value is passed into the configure script or a patch
+                        is applied only for a particular machine), then you
+                        should mark the packages produced as being
+                        machine-specific by adding the following to the
+                        recipe:
+                        <literallayout class='monospaced'>
+     PACKAGE_ARCH = "${MACHINE_ARCH}"
+                        </literallayout>
+                        On the other hand, if the recipe produces packages
+                        that do not contain anything specific to the target
+                        machine or architecture at all (e.g. recipes
+                        that simply package script files or configuration
+                        files), you should use the
+                        <ulink url='&YOCTO_DOCS_REF_URL;#allarch'><filename>allarch</filename></ulink>
+                        class to do this for you by adding this to your
+                        recipe:
+                        <literallayout class='monospaced'>
+     inherit allarch
+                        </literallayout>
+                        Ensuring that the package architecture is correct is
+                        not critical while you are doing the first few builds
+                        of your recipe, but it is important in order to
+                        to ensure that your recipe rebuilds (or does not
+                        rebuild) appropriately in response to changes in
+                        configuration, and to ensure that you get the
+                        appropriate packages installed on the target machine.
+                        </para></listitem>
+                </itemizedlist>
             </para>
         </section>
 
@@ -2497,8 +2566,8 @@
                 package is included in an image.
                 To add a post-installation script to a package, add a
                 <filename>pkg_postinst_PACKAGENAME()</filename> function to
-                the recipe file (<filename>.bb</filename>) and use
-                <filename>PACKAGENAME</filename> as the name of the package
+                the recipe file (<filename>.bb</filename>) and replace
+                <filename>PACKAGENAME</filename> with the name of the package
                 you want to attach to the <filename>postinst</filename>
                 script.
                 To apply the post-installation script to the main package
@@ -2546,9 +2615,8 @@
 
             <para>
                 The previous example delays execution until the image boots
-                again because the
-                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'>D</ulink></filename>
-                variable points to the directory containing the image when
+                again because the environment variable <filename>D</filename>
+                points to the directory containing the image when
                 the root filesystem is created at build time but is unset
                 when executed on the first boot.
             </para>