Syntax¶
This appendix contains a rough sketch of the formal syntax used to define OE-lite recipes.
Formal grammar¶
The BNF grammar below is extracted from the actual source code used to parse recipes. On the one hand, that makes it quite authoritative. On the other hand, it might have been more readable if it was a little less formal. Also, not all terminals (productions in uppercase) are defined below [1] – but at least some of the missing ones should be obvious, and we explain a few more (e.g. what constitutes a valid variable name) in the semantics section below.
syntax ::=statement
statement
syntax
statement ::= NEWLINEassignment
NEWLINEexport_variable
NEWLINEinclude
NEWLINErequire
NEWLINEinherit
NEWLINEfunc
NEWLINEfakeroot_func
NEWLINEpython_func
NEWLINEdef_func
addtask
NEWLINEaddhook
NEWLINEprefer
NEWLINE COMMENT variable ::= VARNAMEexport_variable
export_variable ::=EXPORT
VARNAME varflag ::= VARNAME FLAG varoverride ::= VARNAME OVERRIDE string ::=empty_string
quoted_string
STRING empty_string ::=QUOTE
QUOTE
quoted_string ::=QUOTE
string_value
QUOTE
string_value ::= STRING STRINGstring_value
assignment ::=variable
ASSIGN
string
varflag
ASSIGN
string
varoverride
ASSIGN
string
variable
EXPASSIGN
string
varflag
EXPASSIGN
string
varoverride
EXPASSIGN
string
variable
LAZYASSIGNstring
variable
WEAKASSIGN
string
varflag
WEAKASSIGN
string
varoverride
WEAKASSIGN
string
variable
APPEND
string
varflag
APPEND
string
varoverride
APPEND
string
variable
PREPEND
string
varflag
PREPEND
string
varoverride
PREPEND
string
variable
PREDOT
string
varflag
PREDOT
string
varoverride
PREDOT
string
variable
POSTDOT
string
varflag
POSTDOT
string
varoverride
POSTDOT
string
include ::=INCLUDE
INCLUDEFILE require ::=REQUIRE
INCLUDEFILE inherit ::=INHERIT
inherit_classes
inherit_classes ::= INHERITCLASS INHERITCLASSinherit_classes
addtask ::=addtask_task
addtask_task
addtask_dependencies
addtask_task ::=ADDTASK
TASK addtask_dependencies ::=addtask_dependency
addtask_dependency
addtask_dependencies
addtask_dependency ::=addtask_after
addtask_before
addtask_after ::=AFTER
tasks
addtask_before ::=BEFORE
tasks
tasks ::= TASK TASKtasks
addhook ::=ADDHOOK
HOOKTO
HOOKNAMEADDHOOK
HOOKTO
HOOKNAME HOOKSEQUENCEADDHOOK
HOOKTO
HOOKNAMEaddhook_dependencies
ADDHOOK
HOOKTO
HOOKNAME HOOKSEQUENCEaddhook_dependencies
addhook_dependencies ::=addhook_dependency
addhook_dependency
addhook_dependencies
addhook_dependency ::=addhook_after
addhook_before
addhook_after ::=AFTER
hooks
addhook_before ::=BEFORE
hooks
hooks ::= HOOK HOOKhooks
prefer ::=PREFER
recipe
maybe_layer
maybe_version
PREFER
packages
maybe_recipe
maybe_layer
maybe_version
recipe ::= RECIPE RECIPENAME maybe_recipe ::=recipe
layer ::= LAYER LAYERNAME maybe_layer ::=layer
version ::= VERSION VERSIONNAME maybe_version ::=version
packages ::= PACKAGEpackage
package ::= PACKAGENAME PACKAGENAMEpackage
func ::= VARNAME FUNCSTARTfunc_body
FUNCSTOP func_body ::= FUNCLINE FUNCLINEfunc_body
fakeroot_func ::=FAKEROOT
func
python_func ::=python_func_start
func_body
FUNCSTOP python_func_start ::=PYTHON
VARNAME FUNCSTART def_func ::=DEF
VARNAMEdef_funcargs
NEWLINEfunc_body
DEF
VARNAMEdef_funcargs
NEWLINEfunc_body
FUNCSTOP def_funcargs ::= ARGSTART STRING ARGSTOP ARGSTART ARGSTOP ADDHOOK ::= addhook ADDTASK ::= addtask AFTER ::= after APPEND ::= += ASSIGN ::= = BEFORE ::= before DEF ::= def EXPASSIGN ::= := EXPORT ::= export FAKEROOT ::= fakeroot INCLUDE ::= include INHERIT ::= inherit POSTDOT ::= =. PREDOT ::= .= PREFER ::= prefer PREPEND ::= =+ PYTHON ::= python QUOTE ::= " REQUIRE ::= require TO ::= to WEAKASSIGN ::= ?=
Semantics¶
This section describes the semantics of the most important top-level productions in the above grammar.
Assignment¶
The most common statement in a recipe is some form of assignment. The
LHS must be a valid variable name, which means that it must match the
regular expression [a-zA-Z_][a-zA-Z0-9_\-\${}\+\.]*
. In other
words, it must start with a letter or underscore, and otherwise
consist of alphanumeric characters, along with -${}+.
.
The characters ${}
are not part of the actual variable name, but
can be used to substitute the value of another variable. For example,
if PN
contains openssh
, RDEPENDS_${PN} = "something"
would
assign the value something
to RDEPENDS_openssh
. In practice,
${PN}
is the only variable one will ever use in this context.
The RHS should normally consist of a quoted string. References to
other variables can be done by wrapping them in ${}
(this differs
from Makefile syntax where $()
is used).
The semantics of the various operators is as follows:
LHS = "RHS"
: Assign RHS
to the variable LHS
.
LHS .= "RHS"
: Append RHS
to the current value of LHS
– if
LHS
was not defined, it is treated as if it was defined to the
empty string.
LHS =. "RHS"
: This works just like .=
except that it prepends
rather than appends.
LHS += "RHS"
: If LHS is not currently defined or is the empty
string, this works just as LHS = "RHS"
. Otherwise, this appends a
space and then RHS
to the value of LHS
.
LHS =+ "RHS"
: This works just like +=
except that it prepends
rather than appends.
LHS := "RHS"
: Expand all variables appearing in RHS
(recursively) and assign the result to LHS
. It is an error if the
RHS, or any of the text it expands to, refers to undefined variables.
LHS ?= "RHS"
: If LHS
is already defined (even as the empty
string), this does nothing. Otherwise, it works just as LHS =
"RHS"
.
Flags¶
Apart from its value, a variable can also have a number of attributes, or flags. It is rarely necessary to set flags in recipes, but you may encounter the syntax in classes and configuration files.
In general, the syntax for flag settings is just as for variable settings:
varname[flag] = "value"
Some flags just serve as boolean flags (hence the name) and are hence
normally only set using the =
, ?=
and :=
operators, while
others are treated as a whitespace separated list of words.
nohash¶
This flag indicates that the variable it is attached to should not be part of the metadata hashing.
export¶
When a shell function is executed as part of a task, most of the
task’s metadata variables [2] are written to the shell script. Only those
variables with the export
flag set are further exported to the
commands executed by the script.
Instead of setting this flag using the varname[export] = "1"
syntax, an alternative is to use the export varname
statement.
unexport¶
A variable with this flag does not get exported to the shell environment when a shell function is run. It is thus not quite the opposite of the export flag.
emit¶
This flag is used to limit the tasks which a given variable gets copied to. If set, the variable is only emitted to the metadata instances for the tasks listed, e.g.
PACKAGES[emit] = "do_split do_package"
Footnotes
[1] | Automatically extracting the regexps definining the various tokens and presenting them in a reasonable way is not easy. |
[2] | Variables names which are not valid as shell variables,
e.g. those containing - , are not exported. |