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:
parent
59b50ea598
commit
3cb04638b4
|
@ -1896,6 +1896,16 @@
|
||||||
subdirectory that is not specified in the patch file, use the
|
subdirectory that is not specified in the patch file, use the
|
||||||
"patchdir" option in the entry.
|
"patchdir" option in the entry.
|
||||||
</para>
|
</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>
|
||||||
|
|
||||||
<section id='new-recipe-licensing'>
|
<section id='new-recipe-licensing'>
|
||||||
|
@ -2190,9 +2200,23 @@
|
||||||
In these cases, you need to go back and add additional
|
In these cases, you need to go back and add additional
|
||||||
options to the configure script as well as possibly
|
options to the configure script as well as possibly
|
||||||
add additional build-time dependencies to
|
add additional build-time dependencies to
|
||||||
<filename>DEPENDS</filename>.
|
<filename>DEPENDS</filename>.</para>
|
||||||
Occasionally, it is necessary to apply a patch to the
|
<para>Occasionally, it is necessary to apply a patch
|
||||||
source to ensure the correct paths are used.
|
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>
|
</para></listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
</para>
|
</para>
|
||||||
|
@ -2263,7 +2287,8 @@
|
||||||
recipe.
|
recipe.
|
||||||
The function must first use
|
The function must first use
|
||||||
<filename>install -d</filename> to create the
|
<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
|
Once the directories exist, your function can use
|
||||||
<filename>install</filename> to manually install the
|
<filename>install</filename> to manually install the
|
||||||
built software into the directories.</para>
|
built software into the directories.</para>
|
||||||
|
@ -2398,56 +2423,100 @@
|
||||||
<title>Packaging</title>
|
<title>Packaging</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The <filename>do_package</filename> task splits the files
|
Successful packaging is a combination of automated processes
|
||||||
produced by the recipe into logical components.
|
performed by the OpenEmbedded build system and some
|
||||||
Even software that produces a single binary might still have
|
specific steps you need to take.
|
||||||
debug symbols, documentation, and other logical components
|
The following list describes the process:
|
||||||
that should be split out.
|
<itemizedlist>
|
||||||
The <filename>do_package</filename> task ensures that files
|
<listitem><para><emphasis>Splitting Files</emphasis>:
|
||||||
are split up and packaged correctly.
|
The <filename>do_package</filename> task splits the
|
||||||
</para>
|
files produced by the recipe into logical components.
|
||||||
|
Even software that produces a single binary might
|
||||||
<para>
|
still have debug symbols, documentation, and other
|
||||||
The <filename>insane</filename> class adds a step to the
|
logical components that should be split out.
|
||||||
package generation process so that output quality assurance
|
The <filename>do_package</filename> task ensures
|
||||||
checks are generated by the OpenEmbedded build system.
|
that files are split up and packaged correctly.
|
||||||
This step performs a range of checks to be sure the build's
|
</para></listitem>
|
||||||
output is free of common problems that show up during runtime.
|
<listitem><para><emphasis>Running QA Checks</emphasis>:
|
||||||
For information on these checks, see the
|
The <filename>insane</filename> class adds a step to
|
||||||
<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-insane'><filename>insane</filename></ulink>
|
the package generation process so that output quality
|
||||||
class and the
|
assurance checks are generated by the OpenEmbedded
|
||||||
"<ulink url='&YOCTO_DOCS_REF_URL;#ref-qa-checks'>QA Error and Warning Messages</ulink>"
|
build system.
|
||||||
chapter in the Yocto Project Reference Manual.
|
This step performs a range of checks to be sure the
|
||||||
</para>
|
build's output is free of common problems that show
|
||||||
|
up during runtime.
|
||||||
<para>
|
For information on these checks, see the
|
||||||
After you build your software, you need to be sure your packages
|
<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-insane'><filename>insane</filename></ulink>
|
||||||
are correct.
|
class and the
|
||||||
Examine the
|
"<ulink url='&YOCTO_DOCS_REF_URL;#ref-qa-checks'>QA Error and Warning Messages</ulink>"
|
||||||
<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/packages-split</filename>
|
chapter in the Yocto Project Reference Manual.
|
||||||
directory and make sure files are where you expect them to be.
|
</para></listitem>
|
||||||
</para>
|
<listitem><para><emphasis>Hand-Checking Your Packages</emphasis>:
|
||||||
|
After you build your software, you need to be sure
|
||||||
<para>
|
your packages are correct.
|
||||||
If you discover problems, you can set
|
Examine the
|
||||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>,
|
<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/packages-split</filename>
|
||||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>,
|
directory and make sure files are where you expect
|
||||||
<filename>do_install(_append)</filename>, and so forth as
|
them to be.
|
||||||
needed.
|
If you discover problems, you can set
|
||||||
</para>
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>,
|
||||||
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>,
|
||||||
<para>
|
<filename>do_install(_append)</filename>, and so forth as
|
||||||
See the
|
needed.
|
||||||
"<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>"
|
</para></listitem>
|
||||||
section for an example that shows how you might split
|
<listitem><para><emphasis>Splitting an Application into Multiple Packages</emphasis>:
|
||||||
your software into more than one package.
|
If you need to split an application into several
|
||||||
</para>
|
packages, see the
|
||||||
|
"<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application into Multiple Packages</link>"
|
||||||
<para>
|
section for an example.
|
||||||
For an example showing how to install a post-installation
|
</para></listitem>
|
||||||
script, see the
|
<listitem><para><emphasis>Installing a Post-Installation Script</emphasis>:
|
||||||
"<link linkend='new-recipe-post-installation-scripts'>Post-Installation Scripts</link>"
|
For an example showing how to install a
|
||||||
section.
|
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>
|
</para>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
@ -2497,8 +2566,8 @@
|
||||||
package is included in an image.
|
package is included in an image.
|
||||||
To add a post-installation script to a package, add a
|
To add a post-installation script to a package, add a
|
||||||
<filename>pkg_postinst_PACKAGENAME()</filename> function to
|
<filename>pkg_postinst_PACKAGENAME()</filename> function to
|
||||||
the recipe file (<filename>.bb</filename>) and use
|
the recipe file (<filename>.bb</filename>) and replace
|
||||||
<filename>PACKAGENAME</filename> as the name of the package
|
<filename>PACKAGENAME</filename> with the name of the package
|
||||||
you want to attach to the <filename>postinst</filename>
|
you want to attach to the <filename>postinst</filename>
|
||||||
script.
|
script.
|
||||||
To apply the post-installation script to the main package
|
To apply the post-installation script to the main package
|
||||||
|
@ -2546,9 +2615,8 @@
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The previous example delays execution until the image boots
|
The previous example delays execution until the image boots
|
||||||
again because the
|
again because the environment variable <filename>D</filename>
|
||||||
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'>D</ulink></filename>
|
points to the directory containing the image when
|
||||||
variable points to the directory containing the image when
|
|
||||||
the root filesystem is created at build time but is unset
|
the root filesystem is created at build time but is unset
|
||||||
when executed on the first boot.
|
when executed on the first boot.
|
||||||
</para>
|
</para>
|
||||||
|
|
Loading…
Reference in New Issue