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