mirror of
https://git.yoctoproject.org/poky
synced 2026-02-27 03:49:41 +01:00
dev-manual, getting-started: Moved the BB syntax section
This section on BitBake syntax appeared in the Getting Started manual. I decided that it should live with the section on writing a new recipe. (From yocto-docs rev: 8d83ce3e11405b2f12f27cdd117a19c4af52146a) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
committed by
Richard Purdie
Richard Purdie
parent
72be05b9f5
commit
8d320536dc
@@ -17,7 +17,7 @@
|
||||
|
||||
<para>
|
||||
Specifically, this chapter addresses open source philosophy, workflows,
|
||||
Git, source repositories, licensing, recipe syntax, and development
|
||||
Git, source repositories, licensing, and development
|
||||
syntax.
|
||||
</para>
|
||||
|
||||
@@ -938,303 +938,6 @@
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='recipe-syntax'>
|
||||
<title>Recipe Syntax</title>
|
||||
|
||||
<para>
|
||||
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
|
||||
"<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>"
|
||||
chapter of the BitBake User Manual.
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Variable Assignments and Manipulations:</emphasis>
|
||||
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.</para>
|
||||
<para>The following example shows some of the ways
|
||||
you can use variables in recipes:
|
||||
<literallayout class='monospaced'>
|
||||
S = "${WORKDIR}/postfix-${PV}"
|
||||
CFLAGS += "-DNO_ASM"
|
||||
SRC_URI_append = " file://fixup.patch"
|
||||
</literallayout>
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Functions:</emphasis>
|
||||
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 <filename>sh</filename> shell
|
||||
syntax, although access to OpenEmbedded variables and
|
||||
internal methods are also available.</para>
|
||||
<para>The following is an example function from the
|
||||
<filename>sed</filename> recipe:
|
||||
<literallayout class='monospaced'>
|
||||
do_install () {
|
||||
autotools_do_install
|
||||
install -d ${D}${base_bindir}
|
||||
mv ${D}${bindir}/sed ${D}${base_bindir}/sed
|
||||
rmdir ${D}${bindir}/
|
||||
}
|
||||
</literallayout>
|
||||
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.</para></listitem>
|
||||
<listitem><para><emphasis>Keywords:</emphasis>
|
||||
BitBake recipes use only a few keywords.
|
||||
You use keywords to include common
|
||||
functions (<filename>inherit</filename>), load parts
|
||||
of a recipe from other files
|
||||
(<filename>include</filename> and
|
||||
<filename>require</filename>) and export variables
|
||||
to the environment (<filename>export</filename>).</para>
|
||||
<para>The following example shows the use of some of
|
||||
these keywords:
|
||||
<literallayout class='monospaced'>
|
||||
export POSTCONF = "${STAGING_BINDIR}/postconf"
|
||||
inherit autoconf
|
||||
require otherfile.inc
|
||||
</literallayout>
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Comments:</emphasis>
|
||||
Any lines that begin with the hash character
|
||||
(<filename>#</filename>) are treated as comment lines
|
||||
and are ignored:
|
||||
<literallayout class='monospaced'>
|
||||
# This is a comment
|
||||
</literallayout>
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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
|
||||
<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>
|
||||
chapter in the BitBake User Manual.
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Line Continuation: <filename>\</filename></emphasis> -
|
||||
Use the backward slash (<filename>\</filename>)
|
||||
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:
|
||||
<literallayout class='monospaced'>
|
||||
VAR = "A really long \
|
||||
line"
|
||||
</literallayout>
|
||||
<note>
|
||||
You cannot have any characters including spaces
|
||||
or tabs after the slash character.
|
||||
</note>
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<emphasis>Using Variables: <filename>${...}</filename></emphasis> -
|
||||
Use the <filename>${<replaceable>VARNAME</replaceable>}</filename> syntax to
|
||||
access the contents of a variable:
|
||||
<literallayout class='monospaced'>
|
||||
SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz"
|
||||
</literallayout>
|
||||
<note>
|
||||
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 <filename>:=</filename> operator instead of
|
||||
<filename>=</filename> when you make the
|
||||
assignment, but this is not generally needed.
|
||||
</note>
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Quote All Assignments: <filename>"<replaceable>value</replaceable>"</filename></emphasis> -
|
||||
Use double quotes around the value in all variable
|
||||
assignments.
|
||||
<literallayout class='monospaced'>
|
||||
VAR1 = "${OTHERVAR}"
|
||||
VAR2 = "The version is ${PV}"
|
||||
</literallayout>
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Conditional Assignment: <filename>?=</filename></emphasis> -
|
||||
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
|
||||
(<filename>?=</filename>) to make a "soft" assignment
|
||||
used for conditional assignment.
|
||||
Typically, "soft" assignments are used in the
|
||||
<filename>local.conf</filename> file for variables
|
||||
that are allowed to come through from the external
|
||||
environment.
|
||||
</para>
|
||||
<para>Here is an example where
|
||||
<filename>VAR1</filename> is set to "New value" if
|
||||
it is currently empty.
|
||||
However, if <filename>VAR1</filename> has already been
|
||||
set, it remains unchanged:
|
||||
<literallayout class='monospaced'>
|
||||
VAR1 ?= "New value"
|
||||
</literallayout>
|
||||
In this next example, <filename>VAR1</filename>
|
||||
is left with the value "Original value":
|
||||
<literallayout class='monospaced'>
|
||||
VAR1 = "Original value"
|
||||
VAR1 ?= "New value"
|
||||
</literallayout>
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Appending: <filename>+=</filename></emphasis> -
|
||||
Use the plus character followed by the equals sign
|
||||
(<filename>+=</filename>) to append values to existing
|
||||
variables.
|
||||
<note>
|
||||
This operator adds a space between the existing
|
||||
content of the variable and the new content.
|
||||
</note></para>
|
||||
<para>Here is an example:
|
||||
<literallayout class='monospaced'>
|
||||
SRC_URI += "file://fix-makefile.patch"
|
||||
</literallayout>
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Prepending: <filename>=+</filename></emphasis> -
|
||||
Use the equals sign followed by the plus character
|
||||
(<filename>=+</filename>) to prepend values to existing
|
||||
variables.
|
||||
<note>
|
||||
This operator adds a space between the new content
|
||||
and the existing content of the variable.
|
||||
</note></para>
|
||||
<para>Here is an example:
|
||||
<literallayout class='monospaced'>
|
||||
VAR =+ "Starts"
|
||||
</literallayout>
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Appending: <filename>_append</filename></emphasis> -
|
||||
Use the <filename>_append</filename> operator to
|
||||
append values to existing variables.
|
||||
This operator does not add any additional space.
|
||||
Also, the operator is applied after all the
|
||||
<filename>+=</filename>, and
|
||||
<filename>=+</filename> operators have been applied and
|
||||
after all <filename>=</filename> assignments have
|
||||
occurred.
|
||||
</para>
|
||||
<para>The following example shows the space being
|
||||
explicitly added to the start to ensure the appended
|
||||
value is not merged with the existing value:
|
||||
<literallayout class='monospaced'>
|
||||
SRC_URI_append = " file://fix-makefile.patch"
|
||||
</literallayout>
|
||||
You can also use the <filename>_append</filename>
|
||||
operator with overrides, which results in the actions
|
||||
only being performed for the specified target or
|
||||
machine:
|
||||
<literallayout class='monospaced'>
|
||||
SRC_URI_append_sh4 = " file://fix-makefile.patch"
|
||||
</literallayout>
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Prepending: <filename>_prepend</filename></emphasis> -
|
||||
Use the <filename>_prepend</filename> operator to
|
||||
prepend values to existing variables.
|
||||
This operator does not add any additional space.
|
||||
Also, the operator is applied after all the
|
||||
<filename>+=</filename>, and
|
||||
<filename>=+</filename> operators have been applied and
|
||||
after all <filename>=</filename> assignments have
|
||||
occurred.
|
||||
</para>
|
||||
<para>The following example shows the space being
|
||||
explicitly added to the end to ensure the prepended
|
||||
value is not merged with the existing value:
|
||||
<literallayout class='monospaced'>
|
||||
CFLAGS_prepend = "-I${S}/myincludes "
|
||||
</literallayout>
|
||||
You can also use the <filename>_prepend</filename>
|
||||
operator with overrides, which results in the actions
|
||||
only being performed for the specified target or
|
||||
machine:
|
||||
<literallayout class='monospaced'>
|
||||
CFLAGS_prepend_sh4 = "-I${S}/myincludes "
|
||||
</literallayout>
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Overrides:</emphasis> -
|
||||
You can use overrides to set a value conditionally,
|
||||
typically based on how the recipe is being built.
|
||||
For example, to set the
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>
|
||||
variable's value to "standard/base" for any target
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>,
|
||||
except for qemuarm where it should be set to
|
||||
"standard/arm-versatile-926ejs", you would do the
|
||||
following:
|
||||
<literallayout class='monospaced'>
|
||||
KBRANCH = "standard/base"
|
||||
KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
|
||||
</literallayout>
|
||||
Overrides are also used to separate alternate values
|
||||
of a variable in other situations.
|
||||
For example, when setting variables such as
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
|
||||
and
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
|
||||
that are specific to individual packages produced by
|
||||
a recipe, you should always use an override that
|
||||
specifies the name of the package.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Indentation:</emphasis>
|
||||
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.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Using Python for Complex Operations: <filename>${@<replaceable>python_code</replaceable>}</filename></emphasis> -
|
||||
For more advanced processing, it is possible to use
|
||||
Python code during variable assignments (e.g.
|
||||
search and replacement on a variable).</para>
|
||||
<para>You indicate Python code using the
|
||||
<filename>${@<replaceable>python_code</replaceable>}</filename>
|
||||
syntax for the variable assignment:
|
||||
<literallayout class='monospaced'>
|
||||
SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz
|
||||
</literallayout>
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Shell Function Syntax:</emphasis>
|
||||
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
|
||||
<filename>sh</filename> and that it does not require
|
||||
any <filename>bash</filename> or other shell-specific
|
||||
functionality.
|
||||
The same considerations apply to various system
|
||||
utilities (e.g. <filename>sed</filename>,
|
||||
<filename>grep</filename>, <filename>awk</filename>,
|
||||
and so forth) that you might wish to use.
|
||||
If in doubt, you should check with multiple
|
||||
implementations - including those from BusyBox.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="development-concepts">
|
||||
<title>Development Concepts</title>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user