diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2014-06-03 09:33:04 +0300 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2014-06-18 10:30:44 +0100 |
commit | 3cb04638b46f26da61fc894221462b738ffeca0c (patch) | |
tree | 4185f30ba9dd03886ae1fbf54a36236d1c2ccb5e /documentation/dev-manual | |
parent | 59b50ea598538cb9ad9933ba28f9514052258d00 (diff) | |
download | openembedded-core-contrib-3cb04638b46f26da61fc894221462b738ffeca0c.tar.gz |
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>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 186 |
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> |