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>
This commit is contained in:
parent
4abc384f25
commit
b55ffe7356
|
@ -1155,7 +1155,7 @@
|
||||||
The following figure shows the basic process for creating a
|
The following figure shows the basic process for creating a
|
||||||
new recipe.
|
new recipe.
|
||||||
Subsequent sections provide details for each step.
|
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>
|
</para>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
@ -1180,14 +1180,17 @@
|
||||||
have to add from scratch, and so forth.
|
have to add from scratch, and so forth.
|
||||||
All these risks stem from unfamiliarity with the
|
All these risks stem from unfamiliarity with the
|
||||||
existing recipe space.</para></listitem>
|
existing recipe space.</para></listitem>
|
||||||
<listitem><para><emphasis>Use and modify a skeleton
|
<listitem><para><emphasis>Use and modify the following
|
||||||
recipe:</emphasis>
|
skeleton recipe:</emphasis>
|
||||||
Using the skeleton recipe located at
|
<literallayout class='monospaced'>
|
||||||
<Need some path for a good recipe to use> is the
|
I need a simple
|
||||||
recommended method for creating a new recipe.
|
skeleton recipe
|
||||||
The skeleton recipe provides the fundamental areas
|
here
|
||||||
that you need to include, exclude, or alter to fit
|
</literallayout>
|
||||||
your needs.
|
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>
|
</para></listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
</para>
|
</para>
|
||||||
|
@ -1197,40 +1200,140 @@
|
||||||
<title>Fetching Code</title>
|
<title>Fetching Code</title>
|
||||||
|
|
||||||
<para>
|
<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
|
Fetching is controlled mainly through the
|
||||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
|
||||||
variable.
|
variable.
|
||||||
Your recipe must have a <filename>SRC_URI</filename> variable
|
Your recipe must have a <filename>SRC_URI</filename> variable
|
||||||
that points to where the source is located.
|
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
|
The <filename>do_fetch</filename> task uses the
|
||||||
variable and its prefix to determine what fetcher to use to
|
<filename>SRC_URI</filename> variable and its prefix to
|
||||||
get your source files.
|
determine what fetcher to use to get your source files.
|
||||||
It is the <filename>SRC_URI</filename> variable that triggers
|
It is the <filename>SRC_URI</filename> variable that triggers
|
||||||
the fetcher.
|
the fetcher.
|
||||||
The <filename>do_patch</filename> task uses the variable after
|
The <filename>do_patch</filename> task uses the variable after
|
||||||
source is fetched to apply patches.
|
source is fetched to apply patches.
|
||||||
The OpenEmbedded build system uses
|
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
|
when scanning directory names for files in
|
||||||
<filename>SRC_URI</filename>.
|
<filename>SRC_URI</filename>.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<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
|
variable in your recipe must define each unique location
|
||||||
for your source files.
|
for your source files.
|
||||||
For example, if you need a tarball, and two patches, then your
|
Here is a simple example from the
|
||||||
<filename>SRC_URI</filename> statement(s) must point to the
|
<filename>meta/recipes-devtools/cdrtools/cdrtools-native_3.01a17.bb</filename>
|
||||||
tarball and the patches.
|
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>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
I need some good examples here.
|
This next example is more complicated and is from the
|
||||||
I also need some sample error messages you get when you don't
|
<filename>meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.19.bb</filename>
|
||||||
have the correct <filename>SRC_URI</filename> locations.
|
recipe.
|
||||||
We can describe how you can copy and past the lines from the
|
The example uses a <filename>SRC_URI</filename> statement
|
||||||
error message and use the correct values.
|
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>
|
</para>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
@ -1263,18 +1366,6 @@ license shipped with the source.
|
||||||
</para>
|
</para>
|
||||||
</section>
|
</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'>
|
<section id='new-recipe-configuring-the-recipe'>
|
||||||
<title>Configuring the Recipe</title>
|
<title>Configuring the Recipe</title>
|
||||||
|
|
||||||
|
@ -1302,8 +1393,8 @@ the target, etc.
|
||||||
</para>
|
</para>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
<section id='new-recipe-optionally-installing'>
|
<section id='new-recipe-installing'>
|
||||||
<title>Optionally Installing</title>
|
<title>Installing</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
install: for autotools/cmake recipes, if the recipe passes through do_install
|
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>
|
</para>
|
||||||
</section>
|
</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'>
|
<section id='new-recipe-packaging'>
|
||||||
<title>Packaging</title>
|
<title>Packaging</title>
|
||||||
|
|
||||||
|
|
Binary file not shown.
Before Width: | Height: | Size: 32 KiB After Width: | Height: | Size: 38 KiB |
Loading…
Reference in New Issue