[oe-commits] org.oe.documentation usermanual: Add a list of all the installation variables and there typical
lenehan commit
openembedded-commits at lists.openembedded.org
Fri Jan 12 01:45:42 UTC 2007
usermanual: Add a list of all the installation variables and there typical
values to the reference section.
Author: lenehan at openembedded.org
Branch: org.openembedded.documentation
Revision: f74db950ed632b37828eec44bcbcf7e71f566a82
ViewMTN: http://monotone.openembedded.org/revision.psp?id=f74db950ed632b37828eec44bcbcf7e71f566a82
Files:
1
usermanual/chapters
usermanual/chapters/recipes.xml
usermanual/chapters/usage.xml
usermanual/reference/dirs_install.xml
usermanual/usermanual.xml
Diffs:
#
# mt diff -rec8a0fc9ce2a36c8cd78e18e6089f0ce75796044 -rf74db950ed632b37828eec44bcbcf7e71f566a82
#
#
#
# add_dir "usermanual/chapters"
#
# add_file "usermanual/chapters/recipes.xml"
# content [1a58c5a9c7cca480de2e10854c8cefc2810b2922]
#
# add_file "usermanual/chapters/usage.xml"
# content [1933682a44a115545405785b571ae17f3d4d7d57]
#
# add_file "usermanual/reference/dirs_install.xml"
# content [7997e68b9578aaec69b791f5bdaa65c985271155]
#
# patch "usermanual/usermanual.xml"
# from [c0f62678524eba4ec2b6a620ca00a2af7ae12811]
# to [67b3af1a46040d66788444501240f9cb9ef059e0]
#
============================================================
--- usermanual/chapters/recipes.xml 1a58c5a9c7cca480de2e10854c8cefc2810b2922
+++ usermanual/chapters/recipes.xml 1a58c5a9c7cca480de2e10854c8cefc2810b2922
@@ -0,0 +1,1459 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter>
+ <title>Recipes</title>
+
+ <section id="bb_introduction" xreflabel="introduction">
+ <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
+ 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
+ intermediate files, such as libraries and headers, which can be used when
+ building other application.</para>
+
+ <para>In many ways the process is similar to creating .deb or .rpm
+ packages for your standard desktop distributions with one major difference
+ - 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>
+
+ <para>This chapter assumes that you are familiar with working with
+ bitbake, including the work flow, required directory structures, bitbake
+ configuration and the use of monotone. If you are not familiar with these
+ then first take a look at the chapter on bitbake usage.</para>
+ </section>
+
+ <section id="bb_syntax" xreflabel="syntax">
+ <title>Syntax of recipes</title>
+
+ <para>The basic items that make up a bitbake recipe file are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>functions</term>
+
+ <listitem>
+ <para>Functions provide a series of actions to be performed.
+ Functions are usually used to override the default implementation of
+ a task function, or to compliment (append or prepend to an existing
+ function) a default function. Standard functions use sh shell
+ syntax, although access to OpenEmbedded variables and internal
+ methods is also available.</para>
+
+ <para>The following is an example function from the sed
+ recipe:</para>
+
+ <para><screen>do_install () {
+ autotools_do_install
+ install -d ${D}${base_bindir}
+ mv ${D}${bindir}/sed ${D}${base_bindir}/sed.${PN}
+}</screen>It is also possible to implement new functions, that are not
+ replacing or complimenting the default functions, which are called
+ between existing tasks. It is also possible to implement functions
+ in python instead of sh. Both of these options are not seen in the
+ majority of recipes.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>variable assignments and manipulations</term>
+
+ <listitem>
+ <para>Variable assignments allow a value to be assigned to a
+ variable. The assignment may be static text or might include the
+ contents of other variables. In addition to assignment, appending
+ and prepending operations are also supported.</para>
+
+ <para>The follow example shows the some of the ways variables can be
+ used in recipes:<screen>S = "${WORKDIR}/postfix-${PV}"
+PR = "r4"
+CFLAGS += "-DNO_ASM"
+SRC_URI_append = "file://fixup.patch;patch=1"</screen></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>keywords</term>
+
+ <listitem>
+ <para>Only a few keywords are used in btbake 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
+ <emphasis>require</emphasis>) and exporting variables to the
+ environment (export).</para>
+
+ <para>The following example shows the use of some of these
+ keywords:<screen>export POSTCONF = "${STAGING_BINDIR}/postconf"
+inherit autoconf
+require otherfile.inc</screen></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>comments</term>
+
+ <listitem>
+ <para>Any lines that begin with a # are treated as comment lines and
+ are ignored.<screen># This is a comment</screen></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The following is a summary of the most important (and most commonly
+ used) parst of the recipe syntax:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Line continuation: \</term>
+
+ <listitem>
+ <para>To split a line over multiple lines you should place a \ at
+ the end of the line that is to be continued on the next line.</para>
+
+ <screen>VAR = "A really long \
+ line"</screen>
+
+ <para>Note that there must not be anything (no spaces or tabs) after
+ the \.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Comments: #</term>
+
+ <listitem>
+ <para>Any lines beginning with a # are comments and will be
+ ignored.<screen># This is a comment</screen></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Using variables: ${...}</term>
+
+ <listitem>
+ <para>To access the contents of a variable you need to access it via
+ <emphasis>${<varname>}</emphasis>:<screen>SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz"</screen></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Quote all assignments</term>
+
+ <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
+ future).<screen>VAR1 = "${OTHERVAR}"
+VAR2 = "The version is ${PV}"</screen></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Appending: +=</term>
+
+ <listitem>
+ <para>You can append values to existing variables using the
+ <emphasis>+=</emphasis> operator. Note that this operator will add a
+ space between the existing content of the variable and the new
+ content.<screen>SRC_URI += "file://fix-makefile.patch;patch=1"</screen></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Prepending: =+</term>
+
+ <listitem>
+ <para>You can preprend values to existing variables using the
+ <emphasis>=+</emphasis> operator. Note that this operater will add a
+ space between the new content and the existing content of the
+ cariable.<screen>VAR =+ "Starts"</screen></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Appending: _append</term>
+
+ <listitem>
+ <para>You can append values to existing variables using the
+ <emphasis>_append</emphasis> method. Note that this operator does
+ not add any additional 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
+ 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,
+ which result in the actions only being performed for the specified
+ target or machine: [TODO: Link to section on overrides]<screen>SRC_URI_append_sh4 = " file://fix-makefile.patch;patch=1"</screen>Note
+ that the appended information is a variable itself, and therefore
+ it's possible to used <emphasis>+=</emphasis> or
+ <emphasis>=+</emphasis> to assign variables to the
+ <emphasis>_append</emphasis> information:<screen>SRC_URI_append = " file://fix-makefile.patch;patch=1"
+SRC_URI_append += "file://fix-install.patch;patch=1"</screen></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Prepending: _prepend</term>
+
+ <listitem>
+ <para>You can prepend values to existing variables using the
+ _prepend method. Note that this operator does not add any additional
+ 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
+ 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
+ overrides, which result in the actions only being performed for the
+ specified target or machine: [TODO: Link to section on
+ overrides]<screen>CFLAGS_prepend_sh4 = " file://fix-makefile.patch;patch=1"</screen>Note
+ that the appended information is a variable itself, and therefore
+ it's possible to used <emphasis>+=</emphasis> or
+ <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 +=
+ operator is adding space itself.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Spaces vs tabs</term>
+
+ <listitem>
+ <para>Spaces should be used for indentation, not hard tabs. Both
+ currently work, however it is a policy decision of OE that spaces
+ always be used.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Style: oe-stylize.py</term>
+
+ <listitem>
+ <para>To help with using the correct style in your recipes there is
+ a python script in the contrib directory called
+ <emphasis>oe-stylize.py</emphasis> which can be used to reformat
+ your recipes to the correct style. The output will contain a list of
+ warning (to let you know what you did wrong) which should be edited
+ out before using the new file.<screen>contrib/oe-stylize.py myrecipe.bb > fixed-recipe.bb
+vi fixed-recipe.bb
+mv fixed.recipe.bb myrecipe.bb</screen></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Using python for complex operations: ${@...}</term>
+
+ <listitem>
+ <para>For more advanced processing it is possible to use python code
+ during variable assignments, for doing search and replace on a
+ variable for example.</para>
+
+ <para>Python code is indicated by a proceeding @ sign in the
+ variable assignment.<screen>CXXFLAGS := "${@'${CXXFLAGS}'.replace('-frename-registers', '')}"</screen>More
+ information about using python is available in the <xref
+ linkend="bb_advanced_python" /> section.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Shell syntax</term>
+
+ <listitem>
+ <para>When describing a list of actions to take shell syntax is used
+ (as if you were writing a shell script). You should ensure that you
+ script would work with a generic sh and not require any bash (or
+ other shell) specific functionality. The same applies to various
+ system utilities (sed, grep, awk etc) that you may wish to use. If
+ in doubt you should check with multiple implementations - including
+ those from busybox.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>For a detailed description of the syntax for the bitbake recipe
+ files you should refer to the bitbake use manual.</para>
+ </section>
+
+ <section id="bb_versioning" xreflabel="versioning">
+ <title>Recipe naming: Names, versions and releases</title>
+
+ <para>Recipes in OpenEmbedded use a standard naming convention that
+ includes the package name and version number in the filename. In addition
+ to the name and version there is also a release number, which is indicates
+ 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>where <emphasis><package-name></emphasis> is the name of the
+ package (application, library, module, or whatever it is that is being
+ packaged) and <emphasis>version</emphasis> is the version number.</para>
+
+ <para>So a typical recipe name would be:<screen>strace_4.5.14.bb</screen>which
+ would be for version <emphasis>4.5.14</emphasis> of the
+ <emphasis>strace</emphasis> application.</para>
+
+ <para>The release version is defined via the package release variable, PR,
+ 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
+ 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
+ then the default value of "r0" is used.</para>
+
+ <para><note>
+ <para>It is good practice to always define PR in your recipes, even
+ for the <emphasis>"r0"</emphasis> release, so that when editing the
+ recipe it is clear that the PR number needs to be updated.</para>
+ </note></para>
+
+ <para>When a recipe is being processed some variables are automatically
+ set based on the recipe file name and can be used for other purposes from
+ within the recipe itself. These include:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>PN</term>
+
+ <listitem>
+ <para>The package name. Determined from the recipe filename -
+ everything up until the first underscore is considered to be the
+ package name. For the <command>strace_4.5.14.bb</command> recipe the
+ PN variable would be set to <emphasis>"strace"</emphasis>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>PV</term>
+
+ <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
+ <command>strace_4.5.14.bb</command> recipe the PV variable would be
+ set to <emphasis>"4.5.14"</emphasis>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>PR</term>
+
+ <listitem>
+ <para>The package release. This is explicitly set in the recipe, or
+ if not set it defaults to "<emphasis>r0"</emphasis> if not
+ set.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>P</term>
+
+ <li%s
>>> DIFF TRUNCATED @ 16K
More information about the Openembedded-commits
mailing list