sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

dev-manual: Integrated Hello World section into new writing recipe section 

This change merged in the Hello World section as a summarizing
example section to the new "Writing a New Recipe" section.

(From yocto-docs rev: 79c858e1590e5ab4c56b19dc51b03e0e570b6209)

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 2013-12-21 08:49:03 -06:00 committed by Richard Purdie
parent 3ad993da10
commit 71460e5fc2
1 changed files with 241 additions and 226 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

467
documentation/dev-manual/dev-manual-common-tasks.xml
View File

@ -1146,6 +1146,12 @@
requires a recipe to define the component. requires a recipe to define the component.
This section describes how to create, write, and test a new This section describes how to create, write, and test a new
recipe. recipe.
<note>
For information on variables that are useful for recipes and
for information about recipe naming issues, see the
"<ulink url='&YOCTO_DOCS_REF_URL;#ref-varlocality-recipe-required'>Required</ulink>"
section of the Yocto Project Reference Manual.
</note>
</para> </para>
<section id='new-recipe-overview'> <section id='new-recipe-overview'>
@ -1162,6 +1168,16 @@
<section id='new-recipe-locate-a-base-recipe'> <section id='new-recipe-locate-a-base-recipe'>
<title>Locate a Base Recipe</title> <title>Locate a Base Recipe</title>
<para>
Before writing a recipe from scratch, it is often useful to
check whether someone else has written one already.
OpenEmbedded is a good place to look as it has a wider scope
and range of packages.
Because the Yocto Project aims to be compatible with
OpenEmbedded, most recipes you find there should work for
you.
</para>
<para> <para>
Working from an existing recipe or a skeleton recipe is the Working from an existing recipe or a skeleton recipe is the
best way to get started. best way to get started.
@ -1204,6 +1220,42 @@
</para></listitem> </para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
<note>
<para>When writing shell functions, you need to be aware of BitBake's
curly brace parsing.
If a recipe uses a closing curly brace within the function and
the character has no leading spaces, BitBake produces a parsing
error.
If you use a pair of curly brace in a shell function, the
closing curly brace must not be located at the start of the line
without leading spaces.</para>
<para>Here is an example that causes BitBake to produce a parsing
error:
<literallayout class='monospaced'>
fakeroot create_shar() {
cat &lt;&lt; "EOF" &gt; ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
usage()
{
echo "test"
###### The following "}" at the start of the line causes a parsing error ######
}
EOF
}
</literallayout>
Writing the recipe this way avoids the error:
<literallayout class='monospaced'>
fakeroot create_shar() {
cat &lt;&lt; "EOF" &gt; ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
usage()
{
echo "test"
######The following "}" with a leading space at the start of the line avoids the error ######
}
EOF
}
</literallayout></para>
</note>
</section> </section>
<section id='new-recipe-naming-the-recipe'> <section id='new-recipe-naming-the-recipe'>
@ -2036,89 +2088,32 @@ do_unpack unpacks the source, and S must be set
section. section.
</para> </para>
</section> </section>
</section>
<section id='usingpoky-extend-addpkg'> <section id='new-recipe-testing-hello-world-example'>
<title>Writing a Recipe to Add a Package to Your Image</title> <title>Hello World Example</title>
<para>
Recipes let you define packages you can add to your image.
Writing a recipe means creating a <filename>.bb</filename> file that sets some
variables.
For information on variables that are useful for recipes and for information about recipe naming
issues, see the
"<ulink url='&YOCTO_DOCS_REF_URL;#ref-varlocality-recipe-required'>Required</ulink>"
section of the Yocto Project Reference Manual.
</para>
<para>
Before writing a recipe from scratch, it is often useful to check
whether someone else has written one already.
OpenEmbedded is a good place to look as it has a wider scope and range of packages.
Because the Yocto Project aims to be compatible with OpenEmbedded, most recipes
you find there should work for you.
</para>
<para>
For new packages, the simplest way to add a recipe is to base it on a similar
pre-existing recipe.
The sections that follow provide some examples that show how to add standard
types of packages.
</para>
<note>
<para>When writing shell functions, you need to be aware of BitBake's
curly brace parsing.
If a recipe uses a closing curly brace within the function and
the character has no leading spaces, BitBake produces a parsing
error.
If you use a pair of curly brace in a shell function, the
closing curly brace must not be located at the start of the line
without leading spaces.</para>
<para>Here is an example that causes BitBake to produce a parsing
error:
<literallayout class='monospaced'>
fakeroot create_shar() {
cat &lt;&lt; "EOF" &gt; ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
usage()
{
echo "test"
###### The following "}" at the start of the line causes a parsing error ######
}
EOF
}
</literallayout>
Writing the recipe this way avoids the error:
<literallayout class='monospaced'>
fakeroot create_shar() {
cat &lt;&lt; "EOF" &gt; ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
usage()
{
echo "test"
######The following "}" with a leading space at the start of the line avoids the error ######
}
EOF
}
</literallayout></para>
</note>
<section id='usingpoky-extend-addpkg-singlec'>
<title>Single .c File Package (Hello World!)</title>
<para> <para>
Building an application from a single file that is stored locally (e.g. under To help summarize how to write a recipe, this section provides
<filename>files/</filename>) requires a recipe that has the file listed in an example recipe that builds a single "Hello World!" package.
the </para>
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
variable. <section id='usingpoky-extend-addpkg-singlec'>
Additionally, you need to manually write the <filename>do_compile</filename> and <title>Single .c File Package (Hello World!)</title>
<filename>do_install</filename> tasks.
The <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> <para>
variable defines the Building an application from a single file that is stored locally (e.g. under
directory containing the source code, which is set to <filename>files/</filename>) requires a recipe that has the file listed in
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'> the
WORKDIR</ulink></filename> in this case - the directory BitBake uses for the build. <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
<literallayout class='monospaced'> variable.
Additionally, you need to manually write the <filename>do_compile</filename> and
<filename>do_install</filename> tasks.
The <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename>
variable defines the
directory containing the source code, which is set to
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'>
WORKDIR</ulink></filename> in this case - the directory BitBake uses for the build.
<literallayout class='monospaced'>
DESCRIPTION = "Simple helloworld application" DESCRIPTION = "Simple helloworld application"
SECTION = "examples" SECTION = "examples"
LICENSE = "MIT" LICENSE = "MIT"
@ -2137,32 +2132,32 @@ do_unpack unpacks the source, and S must be set
install -d ${D}${bindir} install -d ${D}${bindir}
install -m 0755 helloworld ${D}${bindir} install -m 0755 helloworld ${D}${bindir}
} }
</literallayout> </literallayout>
</para> </para>
<para> <para>
By default, the <filename>helloworld</filename>, <filename>helloworld-dbg</filename>, By default, the <filename>helloworld</filename>, <filename>helloworld-dbg</filename>,
and <filename>helloworld-dev</filename> packages are built. and <filename>helloworld-dev</filename> packages are built.
For information on how to customize the packaging process, see the For information on how to customize the packaging process, see the
"<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application
into Multiple Packages</link>" section. into Multiple Packages</link>" section.
</para> </para>
</section> </section>
<section id='usingpoky-extend-addpkg-autotools'> <section id='usingpoky-extend-addpkg-autotools'>
<title>Autotooled Package</title> <title>Autotooled Package</title>
<para> <para>
Applications that use Autotools such as <filename>autoconf</filename> and Applications that use Autotools such as <filename>autoconf</filename> and
<filename>automake</filename> require a recipe that has a source archive listed in <filename>automake</filename> require a recipe that has a source archive listed in
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> and <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> and
also inherits Autotools, which instructs BitBake to use the also inherits Autotools, which instructs BitBake to use the
<filename>autotools.bbclass</filename> file, which contains the definitions of all the steps <filename>autotools.bbclass</filename> file, which contains the definitions of all the steps
needed to build an Autotool-based application. needed to build an Autotool-based application.
The result of the build is automatically packaged. The result of the build is automatically packaged.
And, if the application uses NLS for localization, packages with local information are And, if the application uses NLS for localization, packages with local information are
generated (one package per language). generated (one package per language).
Following is one example: (<filename>hello_2.3.bb</filename>) Following is one example: (<filename>hello_2.3.bb</filename>)
<literallayout class='monospaced'> <literallayout class='monospaced'>
DESCRIPTION = "GNU Helloworld application" DESCRIPTION = "GNU Helloworld application"
SECTION = "examples" SECTION = "examples"
LICENSE = "GPLv2+" LICENSE = "GPLv2+"
@ -2172,49 +2167,49 @@ do_unpack unpacks the source, and S must be set
SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz" SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
inherit autotools gettext inherit autotools gettext
</literallayout> </literallayout>
</para> </para>
<para> <para>
The variable The variable
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename> <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename>
is used to track source license changes as described in the is used to track source license changes as described in the
"<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" section. "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" section.
You can quickly create Autotool-based recipes in a manner similar to the previous example. You can quickly create Autotool-based recipes in a manner similar to the previous example.
</para> </para>
</section> </section>
<section id='usingpoky-extend-addpkg-makefile'> <section id='usingpoky-extend-addpkg-makefile'>
<title>Makefile-Based Package</title> <title>Makefile-Based Package</title>
<para> <para>
Applications that use GNU <filename>make</filename> also require a recipe that has Applications that use GNU <filename>make</filename> also require a recipe that has
the source archive listed in the source archive listed in
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>. <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
You do not need to add a <filename>do_compile</filename> step since by default BitBake You do not need to add a <filename>do_compile</filename> step since by default BitBake
starts the <filename>make</filename> command to compile the application. starts the <filename>make</filename> command to compile the application.
If you need additional <filename>make</filename> options, you should store them in the If you need additional <filename>make</filename> options, you should store them in the
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'>EXTRA_OEMAKE</ulink></filename> <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'>EXTRA_OEMAKE</ulink></filename>
variable. variable.
BitBake passes these options into the <filename>make</filename> GNU invocation. BitBake passes these options into the <filename>make</filename> GNU invocation.
Note that a <filename>do_install</filename> task is still required. Note that a <filename>do_install</filename> task is still required.
Otherwise, BitBake runs an empty <filename>do_install</filename> task by default. Otherwise, BitBake runs an empty <filename>do_install</filename> task by default.
</para> </para>
<para> <para>
Some applications might require extra parameters to be passed to the compiler. Some applications might require extra parameters to be passed to the compiler.
For example, the application might need an additional header path. For example, the application might need an additional header path.
You can accomplish this by adding to the You can accomplish this by adding to the
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink></filename> variable. <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink></filename> variable.
The following example shows this: The following example shows this:
<literallayout class='monospaced'> <literallayout class='monospaced'>
CFLAGS_prepend = "-I ${S}/include " CFLAGS_prepend = "-I ${S}/include "
</literallayout> </literallayout>
</para> </para>
<para> <para>
In the following example, <filename>mtd-utils</filename> is a makefile-based package: In the following example, <filename>mtd-utils</filename> is a makefile-based package:
<literallayout class='monospaced'> <literallayout class='monospaced'>
DESCRIPTION = "Tools for managing memory technology devices." DESCRIPTION = "Tools for managing memory technology devices."
SECTION = "base" SECTION = "base"
DEPENDS = "zlib lzo e2fsprogs util-linux" DEPENDS = "zlib lzo e2fsprogs util-linux"
@ -2245,46 +2240,46 @@ do_unpack unpacks the source, and S must be set
PARALLEL_MAKE = "" PARALLEL_MAKE = ""
BBCLASSEXTEND = "native" BBCLASSEXTEND = "native"
</literallayout> </literallayout>
</para> </para>
<para> <para>
If your sources are available as a tarball instead of a Git repository, you If your sources are available as a tarball instead of a Git repository, you
will need to provide the URL to the tarball as well as an will need to provide the URL to the tarball as well as an
<filename>md5</filename> or <filename>sha256</filename> sum of <filename>md5</filename> or <filename>sha256</filename> sum of
the download. the download.
Here is an example: Here is an example:
<literallayout class='monospaced'> <literallayout class='monospaced'>
SRC_URI="ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-1.4.9.tar.bz2" SRC_URI="ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-1.4.9.tar.bz2"
SRC_URI[md5sum]="82b8e714b90674896570968f70ca778b" SRC_URI[md5sum]="82b8e714b90674896570968f70ca778b"
</literallayout> </literallayout>
You can generate the <filename>md5</filename> or <filename>sha256</filename> sums You can generate the <filename>md5</filename> or <filename>sha256</filename> sums
by using the <filename>md5sum</filename> or <filename>sha256sum</filename> commands by using the <filename>md5sum</filename> or <filename>sha256sum</filename> commands
with the target file as the only argument. with the target file as the only argument.
Here is an example: Here is an example:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ md5sum mtd-utils-1.4.9.tar.bz2 $ md5sum mtd-utils-1.4.9.tar.bz2
82b8e714b90674896570968f70ca778b mtd-utils-1.4.9.tar.bz2 82b8e714b90674896570968f70ca778b mtd-utils-1.4.9.tar.bz2
</literallayout> </literallayout>
</para> </para>
</section> </section>
<section id='splitting-an-application-into-multiple-packages'> <section id='splitting-an-application-into-multiple-packages'>
<title>Splitting an Application into Multiple Packages</title> <title>Splitting an Application into Multiple Packages</title>
<para> <para>
You can use the variables You can use the variables
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename> and <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename> and
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'>FILES</ulink></filename> <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'>FILES</ulink></filename>
to split an application into multiple packages. to split an application into multiple packages.
</para> </para>
<para> <para>
Following is an example that uses the <filename>libXpm</filename> recipe. Following is an example that uses the <filename>libXpm</filename> recipe.
By default, this recipe generates a single package that contains the library along By default, this recipe generates a single package that contains the library along
with a few binaries. with a few binaries.
You can modify the recipe to split the binaries into separate packages: You can modify the recipe to split the binaries into separate packages:
<literallayout class='monospaced'> <literallayout class='monospaced'>
require xorg-lib-common.inc require xorg-lib-common.inc
DESCRIPTION = "X11 Pixmap library" DESCRIPTION = "X11 Pixmap library"
@ -2299,61 +2294,61 @@ do_unpack unpacks the source, and S must be set
PACKAGES =+ "sxpm cxpm" PACKAGES =+ "sxpm cxpm"
FILES_cxpm = "${bindir}/cxpm" FILES_cxpm = "${bindir}/cxpm"
FILES_sxpm = "${bindir}/sxpm" FILES_sxpm = "${bindir}/sxpm"
</literallayout> </literallayout>
</para> </para>
<para> <para>
In the previous example, we want to ship the <filename>sxpm</filename> In the previous example, we want to ship the <filename>sxpm</filename>
and <filename>cxpm</filename> binaries in separate packages. and <filename>cxpm</filename> binaries in separate packages.
Since <filename>bindir</filename> would be packaged into the main Since <filename>bindir</filename> would be packaged into the main
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename> <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename>
package by default, we prepend the <filename>PACKAGES</filename> package by default, we prepend the <filename>PACKAGES</filename>
variable so additional package names are added to the start of list. variable so additional package names are added to the start of list.
This results in the extra <filename>FILES_*</filename> This results in the extra <filename>FILES_*</filename>
variables then containing information that define which files and variables then containing information that define which files and
directories go into which packages. directories go into which packages.
Files included by earlier packages are skipped by latter packages. Files included by earlier packages are skipped by latter packages.
Thus, the main <filename>PN</filename> package Thus, the main <filename>PN</filename> package
does not include the above listed files. does not include the above listed files.
</para> </para>
</section> </section>
<section id='usingpoky-extend-addpkg-postinstalls'> <section id='usingpoky-extend-addpkg-postinstalls'>
<title>Post-Installation Scripts</title> <title>Post-Installation Scripts</title>
<para> <para>
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 the <filename>pkg_postinst_PACKAGENAME()</filename> function to the
<filename>.bb</filename> file and use <filename>.bb</filename> file and use
<filename>PACKAGENAME</filename> as the name of the package you want to attach to the <filename>PACKAGENAME</filename> as the name of the package you want to attach to the
<filename>postinst</filename> script. <filename>postinst</filename> script.
Normally, Normally,
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename> <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename>
can be used, which automatically expands to <filename>PACKAGENAME</filename>. can be used, which automatically expands to <filename>PACKAGENAME</filename>.
A post-installation function has the following structure: A post-installation function has the following structure:
<literallayout class='monospaced'> <literallayout class='monospaced'>
pkg_postinst_PACKAGENAME () { pkg_postinst_PACKAGENAME () {
#!/bin/sh -e #!/bin/sh -e
# Commands to carry out # Commands to carry out
} }
</literallayout> </literallayout>
</para> </para>
<para> <para>
The script defined in the post-installation function is called when the The script defined in the post-installation function is called when the
root filesystem is created. root filesystem is created.
If the script succeeds, the package is marked as installed. If the script succeeds, the package is marked as installed.
If the script fails, the package is marked as unpacked and the script is If the script fails, the package is marked as unpacked and the script is
executed when the image boots again. executed when the image boots again.
</para> </para>
<para> <para>
Sometimes it is necessary for the execution of a post-installation Sometimes it is necessary for the execution of a post-installation
script to be delayed until the first boot. script to be delayed until the first boot.
For example, the script might need to be executed on the device itself. For example, the script might need to be executed on the device itself.
To delay script execution until boot time, use the following structure in the To delay script execution until boot time, use the following structure in the
post-installation script: post-installation script:
<literallayout class='monospaced'> <literallayout class='monospaced'>
pkg_postinst_PACKAGENAME () { pkg_postinst_PACKAGENAME () {
#!/bin/sh -e #!/bin/sh -e
if [ x"$D" = "x" ]; then if [ x"$D" = "x" ]; then
@ -2362,15 +2357,35 @@ do_unpack unpacks the source, and S must be set
exit 1 exit 1
fi fi
} }
</literallayout> </literallayout>
</para> </para>
<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 the root filesystem is created at build time but
is unset when executed on the first boot.
</para>
</section>
</section>
<section id='writer-notes'>
<title>Writer Notes</title>
<para> <para>
The previous example delays execution until the image boots again because the <itemizedlist>
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'>D</ulink></filename> <listitem><para>
variable points Need to edit the faq.xml chapter and find the single reference to
to the directory containing the image when the root filesystem is created at build time but <filename>usingpoky-extend-addpkg</filename> and replace it
is unset when executed on the first boot. with <filename>new-recipe-testing-hello-world-example</filename>.
</para></listitem>
</itemizedlist>
</para> </para>
</section> </section>
</section> </section>