[oe-commits] org.oe.documentation usermanual: Update for recipes chapter.
lenehan commit
openembedded-commits at lists.openembedded.org
Fri Jan 12 05:42:46 UTC 2007
usermanual: Update for recipes chapter.
Lots of updates for the bitbake recipes chapter I accidentally checked
in as part of a different commit earlier today. This is not yet
linked into the main document - a few more sections need to be filled
and cleaned up before it's ready for that.
Author: lenehan at openembedded.org
Branch: org.openembedded.documentation
Revision: 8e0bf212a410ae541e288d0735c604f329309489
ViewMTN: http://monotone.openembedded.org/revision.psp?id=8e0bf212a410ae541e288d0735c604f329309489
Files:
1
usermanual/chapters/recipes.xml
Diffs:
#
# mt diff -rc805bc51d18d186a93efe9770274333a4de0f6ce -r8e0bf212a410ae541e288d0735c604f329309489
#
#
#
# patch "usermanual/chapters/recipes.xml"
# from [1a58c5a9c7cca480de2e10854c8cefc2810b2922]
# to [58c008a1389f15b81c102d2723df343ab952990f]
#
============================================================
--- usermanual/chapters/recipes.xml 1a58c5a9c7cca480de2e10854c8cefc2810b2922
+++ usermanual/chapters/recipes.xml 58c008a1389f15b81c102d2723df343ab952990f
@@ -6,7 +6,7 @@
<title>Introduction</title>
<para>A bitbake recipe is a set of instructions that describe what needs
- to be done to retrierve the source code for some application, apply any
+ to be done to retrieve the source code for some application, apply any
necessary patches, provide any additional files (such as init scripts),
compile it, install it and generated binary packages. The end result is a
binary package that you can install on your target device, and maybe some
@@ -18,7 +18,7 @@
- in OpenEmbedded everything is being cross-compiled. This often makes the
task far more difficult (depending on how well suited the application is
to cross compiling), then it is for other packaging systems and sometime
- impossible. </para>
+ impossible.</para>
<para>This chapter assumes that you are familiar with working with
bitbake, including the work flow, required directory structures, bitbake
@@ -79,7 +79,7 @@ SRC_URI_append = "file://fixup.patch;pat
<term>keywords</term>
<listitem>
- <para>Only a few keywords are used in btbake recipes. They are used
+ <para>Only a few keywords are used in bitbake recipes. They are used
for things such as including common functions
(<emphasis>inherit</emphasis>), loading parts of a recipe from other
files (<emphasis>include</emphasis> and
@@ -104,7 +104,7 @@ require otherfile.inc</screen></para>
</variablelist>
<para>The following is a summary of the most important (and most commonly
- used) parst of the recipe syntax:</para>
+ used) parts of the recipe syntax:</para>
<variablelist>
<varlistentry>
@@ -145,7 +145,7 @@ require otherfile.inc</screen></para>
<listitem>
<para>All variable assignments should be quoted with double quotes.
- (It may work without them at pesent, but it will not work in the
+ (It may work without them at present, but it will not work in the
future).<screen>VAR1 = "${OTHERVAR}"
VAR2 = "The version is ${PV}"</screen></para>
</listitem>
@@ -166,10 +166,10 @@ VAR2 = "The version is ${PV}"</screen></
<term>Prepending: =+</term>
<listitem>
- <para>You can preprend values to existing variables using the
- <emphasis>=+</emphasis> operator. Note that this operater will add a
+ <para>You can prepend values to existing variables using the
+ <emphasis>=+</emphasis> operator. Note that this operator will add a
space between the new content and the existing content of the
- cariable.<screen>VAR =+ "Starts"</screen></para>
+ variable.<screen>VAR =+ "Starts"</screen></para>
</listitem>
</varlistentry>
@@ -183,7 +183,7 @@ VAR2 = "The version is ${PV}"</screen></
<emphasis>+=</emphasis>, and <emphasis>=+</emphasis> operators have
been applied.</para>
- <para>The following example show the space being explicity added to
+ <para>The following example show the space being explicitly added to
the start to ensure the appended value is not merged with the
existing value:<screen>SRC_URI_append = " file://fix-makefile.patch;patch=1"</screen>The
<emphasis>_append</emphasis> method can also be used with overrides,
@@ -206,7 +206,7 @@ SRC_URI_append += "file://fix-install.pa
space, and it is applied after all the <emphasis>+=</emphasis>, and
<emphasis>=+</emphasis> operators have been applied.</para>
- <para>The following example show the space being explicity added to
+ <para>The following example show the space being explicitly added to
the end to ensure the prepended value is not merged with the
existing value:<screen>CFLAGS_prepend = "-I${S}/myincludes "</screen>The
<emphasis>_prepend</emphasis> method can also be used with
@@ -218,7 +218,7 @@ CFLAGS_prepend += "-I${S}/myincludes2 "<
<emphasis>=+</emphasis> to assign variables to the
<emphasis>_prepend</emphasis> information:<screen>CFLAGS_prepend = "-I${S}/myincludes "
CFLAGS_prepend += "-I${S}/myincludes2 "</screen>Note also the lack of a space
- when using += to append to a preprend value - remember that the +=
+ when using += to append to a prepend value - remember that the +=
operator is adding space itself.</para>
</listitem>
</varlistentry>
@@ -291,7 +291,7 @@ mv fixed.recipe.bb myrecipe.bb</screen><
changes to the way the package is built and/or packaged. The release
number is contained within the recipe itself.</para>
- <para>The expected fomat of recipe name is:<screen><package-name>_<version>.bb</screen></para>
+ <para>The expected format of recipe name is:<screen><package-name>_<version>.bb</screen></para>
<para>where <emphasis><package-name></emphasis> is the name of the
package (application, library, module, or whatever it is that is being
@@ -305,7 +305,7 @@ mv fixed.recipe.bb myrecipe.bb</screen><
contained in the recipe. The expected format is:<screen>r<n></screen>where
<emphasis><n></emphasis> is an integer number starting from 0
initially and then incremented each time the recipe, or something that
- effects the recipe, is modified. So a typical defintion of the release
+ effects the recipe, is modified. So a typical definition of the release
would be:<screen>PR = "r1"</screen>to specify release number
<emphasis>1</emphasis> (the second release, the first would have been
<emphasis>0</emphasis>). If there is no definition of PR in the recipe
@@ -339,7 +339,7 @@ mv fixed.recipe.bb myrecipe.bb</screen><
<listitem>
<para>The package version. Determined from the recipe filename -
everything between the first underscore and the final .bb is
- considered to be the pacakge version. For the
+ considered to be the package version. For the
<command>strace_4.5.14.bb</command> recipe the PV variable would be
set to <emphasis>"4.5.14"</emphasis>.</para>
</listitem>
@@ -359,7 +359,7 @@ mv fixed.recipe.bb myrecipe.bb</screen><
<term>P</term>
<listitem>
- <para>The package name and versions seperated by a hyphen.<screen>P = "${PN}-${PV}"</screen></para>
+ <para>The package name and versions separated by a hyphen.<screen>P = "${PN}-${PV}"</screen></para>
<para>For the <command>strace_4.5.14.bb</command> recipe the P
variable would be set to
@@ -371,8 +371,8 @@ mv fixed.recipe.bb myrecipe.bb</screen><
<term>PF</term>
<listitem>
- <para>The package name, version and release seperated by
- hypens.<screen>PF = "${PN}-${PV}-${PR}"</screen></para>
+ <para>The package name, version and release separated by
+ hyphens.<screen>PF = "${PN}-${PV}-${PR}"</screen></para>
<para>For the s<command>trace_4.5.14.bb recipe</command>, with PR
set to <emphasis>"r1"</emphasis> in the recipe, the PF variable
@@ -400,7 +400,7 @@ mv fixed.recipe.bb myrecipe.bb</screen><
<title>Variables</title>
<para>One of the most confusing part of bitbake recipes for new users is
- the large amount of variables that appear to be avaialble to change and/or
+ the large amount of variables that appear to be available to change and/or
control the behaviour of some aspect of the recipe. Some variables, such
as those derived from the file name are reasonably obvious, others are not
at all obvious.</para>
@@ -410,7 +410,7 @@ mv fixed.recipe.bb myrecipe.bb</screen><
<orderedlist>
<listitem>
- <para>A large number of variables are definied in the bitbake
+ <para>A large number of variables are defined in the bitbake
configuration file conf/bitbake.conf - it's often a good idea to look
through that file when trying to determine what a particular variable
means.</para>
@@ -420,7 +420,7 @@ mv fixed.recipe.bb myrecipe.bb</screen><
<para>Machine and distribution configuration files in conf/machine and
conf/distro will sometimes define some variables specific to the
machine and/or distribution. You should look at the appropriate files
- for your targets to see if anything is being definied that effects the
+ for your targets to see if anything is being defined that effects the
recipes you are building.</para>
</listitem>
@@ -435,49 +435,60 @@ mv fixed.recipe.bb myrecipe.bb</screen><
<para>The classes, that are used via the inherit keyword, define
and/or use the majority of the remaining variables. A class is a like
a library that contain parts of a bitbake recipe that are used by
- multiple recipes. To make them useable in more situations they often
+ multiple recipes. To make them usable in more situations they often
include a large number of variables to control how the class
operates.</para>
</listitem>
</orderedlist>
- <para>[</para>
+ <para>Another important aspect is that there are three different types of
+ things that binaries and libraries are used for and they often have
+ different variables for each. These include:</para>
- <para>talk about predefinied variables</para>
+ <variablelist>
+ <varlistentry>
+ <term>target</term>
- <para>look in conf/bitbake.conf</para>
+ <listitem>
+ <para>Refers to things built for the target are expected to be run
+ on the target device itself.</para>
+ </listitem>
+ </varlistentry>
- <para>target filesystem paths</para>
+ <varlistentry>
+ <term>native</term>
- <para>build variables</para>
+ <listitem>
+ <para>Refers to things built to run natively on the build host
+ itself.</para>
+ </listitem>
+ </varlistentry>
- <para>data/time variables</para>
+ <varlistentry>
+ <term>cross</term>
- <para>]</para>
+ <listitem>
+ <para>Refers to things built to run natively on the build host
+ itself, but produce output which is suitable for the target device.
+ Cross versions of packages usually only exist for things like
+ compilers and assemblers - i.e. things which are used to produce
+ binary applications themselves.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
<para></para>
-
- <para>[TODO: Table probably goes to ref section, just mention some of the
- more common of these here]</para>
-
- <para></para>
-
- <para>build vs host vs target</para>
-
- <para>build - run on the build system, produce things that run on the
- build system</para>
-
- <para>host - run on the build system, produce things for the</para>
-
- <para></para>
</section>
<section id="bb_header" xreflabel="header">
<title>Header</title>
- <para>talk about some of the header entries</para>
+ <para>Practically all recipes start was the header section which describes
+ various aspects of the package that is being built. This information is
+ typically used directly by the package format (such as ipkg or deb) as
+ it's meta data used to describe the package.</para>
- <para></para>
+ <para>Variables used in the header include:</para>
<variablelist>
<varlistentry>
@@ -533,10 +544,13 @@ mv fixed.recipe.bb myrecipe.bb</screen><
<listitem>
<para>The license for the application. If it is not one of the
- standard linceses then the license itself must be included
- (where?)</para>
+ standard licenses then the license itself must be included
+ (where?).</para>
- <para>The default licenses is <emphasis>"unknown"</emphasis>.</para>
+ <para>As well as being used in the package meta-data the license is
+ also used by the src_distribute class.</para>
+
+ <para>The default license is <emphasis>"unknown"</emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>
@@ -610,26 +624,24 @@ mv fixed.recipe.bb myrecipe.bb</screen><
<section>
<title>WORKDIR: The working directory</title>
- <para>[UNEDITED]</para>
+ <para>The working directory is where the source code is extracted, to
+ which plain files (not patches) are copied and where the logs and
+ installation files are created. A typical reason for needing to
+ reference the work directory is for the handling of non patch
+ files.</para>
- <para>The workdir is the directory into which the source code is
- extracted, to which files (non patch files) are copied and where the
- logs and installation files are created. A typical reason for needing to
- reference the work directory is for non patch files. If we take a look
- at the recipe for quagga we can see an example of this:</para>
-
- <para><screen>SRC_URI = "http://www.quagga.net/download/quagga-${PV}.tar.gz \
+ <para>If we take a look at the recipe for quagga we can see an example
+ non patch files for configuration and init scripts:<screen>SRC_URI = "http://www.quagga.net/download/quagga-${PV}.tar.gz \
file://fix-for-lib-inpath.patch;patch=1 \
file://quagga.init \
file://quagga.default \
file://watchquagga.init \
- file://watchquagga.default"</screen>This has two init files and two
- configuration files which are not patches, but actually files that it
- wants to include in the generated packages. Bitbake will copy these
- files into the work directory. So to access them we refer to
- WORKDIR:</para>
-
- <para><screen>do_install () {
+ file://watchquagga.default"</screen>The recipe has two init files
+ and two configuration files, which are not patches, but are actually
+ files that it wants to include in the generated packages. Bitbake will
+ copy these files into the work directory. So to access them during the
+ install task we refer to them via the <emphasis
+ role="bold">WORKDIR</emphasis> variable:<screen>do_install () {
# Install init script and default settings
install -m 0755 -d ${D}${sysconfdir}/default ${D}${sysconfdir}/init.d ${D}${sysconfdir}/quagga
install -m 0644 ${WORKDIR}/quagga.default ${D}${sysconfdir}/default/quagga
@@ -644,22 +656,29 @@ mv fixed.recipe.bb myrecipe.bb</screen><
<section>
<title>S: The unpacked source code directory</title>
- <para>[UNEDITED]</para>
+ <para>Bitbake expects to find the extracted source for a package in a
+ directory called <emphasis
+ role="bold"><packagename>-<version></emphasis> in the
+ <emphasis role="bold">WORKDIR</emphasis> directory. This is the
+ directory in which it will change into before patching, compiling and
+ installation the package.</para>
- <para>Bitbake expects to find the source for a package in the
- <packagename>-<version> directory, so for a package called
- widgets_1.2.bb we are extracting widgets-1.2.tar.gz and bitbake expects
- to source to end up in a directory called widgets-1.2 within the work
- directory. If the source does not end up in this directory then bitbake
- needs to be told this by explicitly setting S.</para>
+ <para>For example, we have a package called <emphasis
+ role="bold">widgets_1.2.bb</emphasis> which we are extracting from the
+ <emphasis role="bold">widgets-1.2.tar.gz</emphasis> file. Bitbake
+ expects the source to end up in a directory called <%s
>>> DIFF TRUNCATED @ 16K
More information about the Openembedded-commits
mailing list