mirror of
git://git.yoctoproject.org/poky
synced 2026-05-18 23:44:18 +00:00
ae06e04cd2
Creation involved removing the overview-manual and replacing it with the getting-started manual. All links to the string "&YOCTO_DOCS_OVERVIEW_URL" had to be replaced with "&YOCTO_DOCS_GS_URL" across the entire YP manual set. I renamed files used to create the manual with prefixes suited for the new manual name, which is "Getting Started With Yocto Project". The style sheet for the new manual needed updating to display the new .PNG image for the title page. The mega-manual file had to be updated to include the files. The mega-manual.sed file had to be updated to include the new manual and not use the overview manual. (From yocto-docs rev: 6c7abf9192390121000f577d6c98f259d290d15d) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
384 lines
17 KiB
HTML
384 lines
17 KiB
HTML
<html>
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||
<title>2.7. Recipe Syntax</title>
|
||
<link rel="stylesheet" type="text/css" href="../book.css">
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
|
||
<link rel="home" href="index.html" title="Getting Started With Yocto Project">
|
||
<link rel="up" href="overview-development-environment.html" title="Chapter 2. The Yocto Project Development Environment">
|
||
<link rel="prev" href="licensing.html" title="2.6. Licensing">
|
||
<link rel="next" href="development-concepts.html" title="2.8. Development Concepts">
|
||
</head>
|
||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.7. Recipe Syntax">
|
||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||
<a name="recipe-syntax"></a>2.7. Recipe Syntax</h2></div></div></div>
|
||
<p>
|
||
Understanding recipe file syntax is important for
|
||
writing recipes.
|
||
The following list overviews the basic items that make up a
|
||
BitBake recipe file.
|
||
For more complete BitBake syntax descriptions, see the
|
||
"<a class="link" href="../bitbake-user-manual/bitbake-user-manual-metadata.html" target="_self">Syntax and Operators</a>"
|
||
chapter of the BitBake User Manual.
|
||
</p>
|
||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||
<li class="listitem">
|
||
<p><span class="emphasis"><em>Variable Assignments and Manipulations:</em></span>
|
||
Variable assignments allow a value to be assigned to a
|
||
variable.
|
||
The assignment can be static text or might include
|
||
the contents of other variables.
|
||
In addition to the assignment, appending and prepending
|
||
operations are also supported.</p>
|
||
<p>The following example shows some of the ways
|
||
you can use variables in recipes:
|
||
</p>
|
||
<pre class="literallayout">
|
||
S = "${WORKDIR}/postfix-${PV}"
|
||
CFLAGS += "-DNO_ASM"
|
||
SRC_URI_append = " file://fixup.patch"
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
</li>
|
||
<li class="listitem">
|
||
<p><span class="emphasis"><em>Functions:</em></span>
|
||
Functions provide a series of actions to be performed.
|
||
You usually use functions to override the default
|
||
implementation of a task function or to complement
|
||
a default function (i.e. append or prepend to an
|
||
existing function).
|
||
Standard functions use <code class="filename">sh</code> shell
|
||
syntax, although access to OpenEmbedded variables and
|
||
internal methods are also available.</p>
|
||
<p>The following is an example function from the
|
||
<code class="filename">sed</code> recipe:
|
||
</p>
|
||
<pre class="literallayout">
|
||
do_install () {
|
||
autotools_do_install
|
||
install -d ${D}${base_bindir}
|
||
mv ${D}${bindir}/sed ${D}${base_bindir}/sed
|
||
rmdir ${D}${bindir}/
|
||
}
|
||
</pre>
|
||
<p>
|
||
It is also possible to implement new functions that
|
||
are called between existing tasks as long as the
|
||
new functions are not replacing or complementing the
|
||
default functions.
|
||
You can implement functions in Python
|
||
instead of shell.
|
||
Both of these options are not seen in the majority of
|
||
recipes.</p>
|
||
</li>
|
||
<li class="listitem">
|
||
<p><span class="emphasis"><em>Keywords:</em></span>
|
||
BitBake recipes use only a few keywords.
|
||
You use keywords to include common
|
||
functions (<code class="filename">inherit</code>), load parts
|
||
of a recipe from other files
|
||
(<code class="filename">include</code> and
|
||
<code class="filename">require</code>) and export variables
|
||
to the environment (<code class="filename">export</code>).</p>
|
||
<p>The following example shows the use of some of
|
||
these keywords:
|
||
</p>
|
||
<pre class="literallayout">
|
||
export POSTCONF = "${STAGING_BINDIR}/postconf"
|
||
inherit autoconf
|
||
require otherfile.inc
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
</li>
|
||
<li class="listitem">
|
||
<p><span class="emphasis"><em>Comments:</em></span>
|
||
Any lines that begin with the hash character
|
||
(<code class="filename">#</code>) are treated as comment lines
|
||
and are ignored:
|
||
</p>
|
||
<pre class="literallayout">
|
||
# This is a comment
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
</li>
|
||
</ul></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
This next list summarizes the most important and most commonly
|
||
used parts of the recipe syntax.
|
||
For more information on these parts of the syntax, you can
|
||
reference the
|
||
<a class="link" href="../bitbake-user-manual/bitbake-user-manual-metadata.html" target="_self">Syntax and Operators</a>
|
||
chapter in the BitBake User Manual.
|
||
</p>
|
||
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
|
||
<li class="listitem">
|
||
<p><span class="emphasis"><em>Line Continuation: <code class="filename">\</code></em></span> -
|
||
Use the backward slash (<code class="filename">\</code>)
|
||
character to split a statement over multiple lines.
|
||
Place the slash character at the end of the line that
|
||
is to be continued on the next line:
|
||
</p>
|
||
<pre class="literallayout">
|
||
VAR = "A really long \
|
||
line"
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
|
||
<h3 class="title">Note</h3>
|
||
You cannot have any characters including spaces
|
||
or tabs after the slash character.
|
||
</div>
|
||
<p>
|
||
</p>
|
||
</li>
|
||
<li class="listitem">
|
||
<p>
|
||
<span class="emphasis"><em>Using Variables: <code class="filename">${...}</code></em></span> -
|
||
Use the <code class="filename">${<em class="replaceable"><code>VARNAME</code></em>}</code> syntax to
|
||
access the contents of a variable:
|
||
</p>
|
||
<pre class="literallayout">
|
||
SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz"
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
|
||
<h3 class="title">Note</h3>
|
||
It is important to understand that the value of a
|
||
variable expressed in this form does not get
|
||
substituted automatically.
|
||
The expansion of these expressions happens
|
||
on-demand later (e.g. usually when a function that
|
||
makes reference to the variable executes).
|
||
This behavior ensures that the values are most
|
||
appropriate for the context in which they are
|
||
finally used.
|
||
On the rare occasion that you do need the variable
|
||
expression to be expanded immediately, you can use
|
||
the <code class="filename">:=</code> operator instead of
|
||
<code class="filename">=</code> when you make the
|
||
assignment, but this is not generally needed.
|
||
</div>
|
||
<p>
|
||
</p>
|
||
</li>
|
||
<li class="listitem">
|
||
<p><span class="emphasis"><em>Quote All Assignments: <code class="filename">"<em class="replaceable"><code>value</code></em>"</code></em></span> -
|
||
Use double quotes around the value in all variable
|
||
assignments.
|
||
</p>
|
||
<pre class="literallayout">
|
||
VAR1 = "${OTHERVAR}"
|
||
VAR2 = "The version is ${PV}"
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
</li>
|
||
<li class="listitem">
|
||
<p><span class="emphasis"><em>Conditional Assignment: <code class="filename">?=</code></em></span> -
|
||
Conditional assignment is used to assign a value to
|
||
a variable, but only when the variable is currently
|
||
unset.
|
||
Use the question mark followed by the equal sign
|
||
(<code class="filename">?=</code>) to make a "soft" assignment
|
||
used for conditional assignment.
|
||
Typically, "soft" assignments are used in the
|
||
<code class="filename">local.conf</code> file for variables
|
||
that are allowed to come through from the external
|
||
environment.
|
||
</p>
|
||
<p>Here is an example where
|
||
<code class="filename">VAR1</code> is set to "New value" if
|
||
it is currently empty.
|
||
However, if <code class="filename">VAR1</code> has already been
|
||
set, it remains unchanged:
|
||
</p>
|
||
<pre class="literallayout">
|
||
VAR1 ?= "New value"
|
||
</pre>
|
||
<p>
|
||
In this next example, <code class="filename">VAR1</code>
|
||
is left with the value "Original value":
|
||
</p>
|
||
<pre class="literallayout">
|
||
VAR1 = "Original value"
|
||
VAR1 ?= "New value"
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
</li>
|
||
<li class="listitem">
|
||
<p><span class="emphasis"><em>Appending: <code class="filename">+=</code></em></span> -
|
||
Use the plus character followed by the equals sign
|
||
(<code class="filename">+=</code>) to append values to existing
|
||
variables.
|
||
</p>
|
||
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
|
||
<h3 class="title">Note</h3>
|
||
This operator adds a space between the existing
|
||
content of the variable and the new content.
|
||
</div>
|
||
<p>Here is an example:
|
||
</p>
|
||
<pre class="literallayout">
|
||
SRC_URI += "file://fix-makefile.patch"
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
</li>
|
||
<li class="listitem">
|
||
<p><span class="emphasis"><em>Prepending: <code class="filename">=+</code></em></span> -
|
||
Use the equals sign followed by the plus character
|
||
(<code class="filename">=+</code>) to prepend values to existing
|
||
variables.
|
||
</p>
|
||
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
|
||
<h3 class="title">Note</h3>
|
||
This operator adds a space between the new content
|
||
and the existing content of the variable.
|
||
</div>
|
||
<p>Here is an example:
|
||
</p>
|
||
<pre class="literallayout">
|
||
VAR =+ "Starts"
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
</li>
|
||
<li class="listitem">
|
||
<p><span class="emphasis"><em>Appending: <code class="filename">_append</code></em></span> -
|
||
Use the <code class="filename">_append</code> operator to
|
||
append values to existing variables.
|
||
This operator does not add any additional space.
|
||
Also, the operator is applied after all the
|
||
<code class="filename">+=</code>, and
|
||
<code class="filename">=+</code> operators have been applied and
|
||
after all <code class="filename">=</code> assignments have
|
||
occurred.
|
||
</p>
|
||
<p>The following example shows the space being
|
||
explicitly added to the start to ensure the appended
|
||
value is not merged with the existing value:
|
||
</p>
|
||
<pre class="literallayout">
|
||
SRC_URI_append = " file://fix-makefile.patch"
|
||
</pre>
|
||
<p>
|
||
You can also use the <code class="filename">_append</code>
|
||
operator with overrides, which results in the actions
|
||
only being performed for the specified target or
|
||
machine:
|
||
</p>
|
||
<pre class="literallayout">
|
||
SRC_URI_append_sh4 = " file://fix-makefile.patch"
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
</li>
|
||
<li class="listitem">
|
||
<p><span class="emphasis"><em>Prepending: <code class="filename">_prepend</code></em></span> -
|
||
Use the <code class="filename">_prepend</code> operator to
|
||
prepend values to existing variables.
|
||
This operator does not add any additional space.
|
||
Also, the operator is applied after all the
|
||
<code class="filename">+=</code>, and
|
||
<code class="filename">=+</code> operators have been applied and
|
||
after all <code class="filename">=</code> assignments have
|
||
occurred.
|
||
</p>
|
||
<p>The following example shows the space being
|
||
explicitly added to the end to ensure the prepended
|
||
value is not merged with the existing value:
|
||
</p>
|
||
<pre class="literallayout">
|
||
CFLAGS_prepend = "-I${S}/myincludes "
|
||
</pre>
|
||
<p>
|
||
You can also use the <code class="filename">_prepend</code>
|
||
operator with overrides, which results in the actions
|
||
only being performed for the specified target or
|
||
machine:
|
||
</p>
|
||
<pre class="literallayout">
|
||
CFLAGS_prepend_sh4 = "-I${S}/myincludes "
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
</li>
|
||
<li class="listitem">
|
||
<p><span class="emphasis"><em>Overrides:</em></span> -
|
||
You can use overrides to set a value conditionally,
|
||
typically based on how the recipe is being built.
|
||
For example, to set the
|
||
<a class="link" href="../ref-manual/var-KBRANCH.html" target="_self"><code class="filename">KBRANCH</code></a>
|
||
variable's value to "standard/base" for any target
|
||
<a class="link" href="../ref-manual/var-MACHINE.html" target="_self"><code class="filename">MACHINE</code></a>,
|
||
except for qemuarm where it should be set to
|
||
"standard/arm-versatile-926ejs", you would do the
|
||
following:
|
||
</p>
|
||
<pre class="literallayout">
|
||
KBRANCH = "standard/base"
|
||
KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
|
||
</pre>
|
||
<p>
|
||
Overrides are also used to separate alternate values
|
||
of a variable in other situations.
|
||
For example, when setting variables such as
|
||
<a class="link" href="../ref-manual/var-FILES.html" target="_self"><code class="filename">FILES</code></a>
|
||
and
|
||
<a class="link" href="../ref-manual/var-RDEPENDS.html" target="_self"><code class="filename">RDEPENDS</code></a>
|
||
that are specific to individual packages produced by
|
||
a recipe, you should always use an override that
|
||
specifies the name of the package.
|
||
</p>
|
||
</li>
|
||
<li class="listitem"><p><span class="emphasis"><em>Indentation:</em></span>
|
||
Use spaces for indentation rather than than tabs.
|
||
For shell functions, both currently work.
|
||
However, it is a policy decision of the Yocto Project
|
||
to use tabs in shell functions.
|
||
Realize that some layers have a policy to use spaces
|
||
for all indentation.
|
||
</p></li>
|
||
<li class="listitem">
|
||
<p><span class="emphasis"><em>Using Python for Complex Operations: <code class="filename">${@<em class="replaceable"><code>python_code</code></em>}</code></em></span> -
|
||
For more advanced processing, it is possible to use
|
||
Python code during variable assignments (e.g.
|
||
search and replacement on a variable).</p>
|
||
<p>You indicate Python code using the
|
||
<code class="filename">${@<em class="replaceable"><code>python_code</code></em>}</code>
|
||
syntax for the variable assignment:
|
||
</p>
|
||
<pre class="literallayout">
|
||
SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
</li>
|
||
<li class="listitem"><p><span class="emphasis"><em>Shell Function Syntax:</em></span>
|
||
Write shell functions as if you were writing a shell
|
||
script when you describe a list of actions to take.
|
||
You should ensure that your script works with a generic
|
||
<code class="filename">sh</code> and that it does not require
|
||
any <code class="filename">bash</code> or other shell-specific
|
||
functionality.
|
||
The same considerations apply to various system
|
||
utilities (e.g. <code class="filename">sed</code>,
|
||
<code class="filename">grep</code>, <code class="filename">awk</code>,
|
||
and so forth) that you might wish to use.
|
||
If in doubt, you should check with multiple
|
||
implementations - including those from BusyBox.
|
||
</p></li>
|
||
</ul></div>
|
||
<p>
|
||
</p>
|
||
</div></body>
|
||
</html>
|