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>
This commit is contained in:
Scott Rifenbark
Richard Purdie
parent
59b50ea598
commit
3cb04638b4
|
|
@ -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>
|
||||
|
|
|
|||
Loading…
Reference in New Issue