A-A-P home page | A-A-P Recipe Executive |
Prev | Reference Manual | Next

## Chapter 34. Variables and Scopes

## Using Variables

A variable value is normally a string. The meaning of the value depends on where it is used. For example, "*" is interpreted as a wildcard when a variable is used where a file name is expected. Thus the wildcard is not expanded in the assignment. If you need it, use a Python expression to expand wildcards.

When using Python you can assign any type of value to a variable. Only a few types are supported for variables used in Aap commands:

String |
Integer or Long | converted to a string
ExpandVar object | used for delayed expansion of variables

In Python code the ExpandVar object needs to be expanded before you can use the value it contains. Use the var2string() function for that.

Normally using $VAR gets what you want. Aap will use the kind of quoting expected and add attributes when needed. This depends on the place where the variable is used. However, when you want something else, this can be specified:

$var | depends on where it's used
$?var | when the variable is not set or defined use an empty string instead of generating an error
$-var | without attributes (may collapse white space)
$+var | with attributes
$*var | use rc-style expansion (may collapse white space)
$/var | slashes changed to backslashes (for MS-Windows commands)
$=var | no quotes or backslashes
$'var | aap quoted (using ' and/or " where required, no backslashes)
$"var | quoted with " (doubled for a literal ")
$\var | special characters escaped with a backslash
$!var | depends on the shell, either like $'var or $"var

In most places $var is expanded as $+'var (with attributes, using ' and " for quoting). The exceptions are:

:sys | $-!var | no attributes, shell quoting
$n in $(v[$n]) | $-=var | no attributes, no quoting
:del | $-'var | no attributes, normal quoting

The quoted variables don't handle the backslash as a special character. This is useful for MS-Windows file names. Example:

            prog : "dir\file 1.c"
                    :print $'source

Results in: "dir\file 1.c"

Be careful with using "$\var" and quotes, you may not always get what you wanted.

## RC-style expansion

RC-style expansion means that each item in a variable is concatenated to the item immediately before and after the variable. Example:

            var = one two three
            :print dir/$*var

Results in:

dir/one dir/two dir/three

For the expansion the variable is used as a list of white-separated items. Quotes can be used to include white space in an item. Use double quotes around a single quote and single quotes around a double quote. Escaping the meaning of quotes with a backslash is not supported.

When using rc-style expansion of a variable that is empty, the result is empty. Example:

            aa =
            :print bla$*aa

This prints an empty line. The "bla" is omitted, because the rc-style expansion has zero items.

When concatenating variables and using rc-style expansion, the attributes of the last variable overrule the identical attributes of a previous one.

            v1 = foo {check = 1}
            v2 = bar {check = 2}
            vv = $*v1$v2

Is equivalent to:

            vv = foobar{check = 1}{check = 2}

When using rc-style expansion, quotes will not be kept as they are, but removed and re-inserted where used or necessary. Example:

            foo: "file 1.c" foo.c
                    :print "dir/$*source"

Results in:

"dir/file 1.c" "dir/foo.c"

## Variable Indexing

To get one item out of a variable that is a list of items, use an index number in square brackets. Parenthesis or curly braces must be used around the variable name and the index. The first item is indexed with zero. Example:

            BAR = beer coffee cola
            :print $(BAR[0])

            BAR_ONE = $(BAR[2])
            :print $BAR_ONE

Results in:

beer
cola

Using an index for which no item exists gives an empty result. When $MESSAGE includes "warning" a message is printed about this.

## Using Scopes

A dot is considered part of the variable name. It separates the scope name from the variable name within that scope. However, a trailing dot is not part of the variable name, so that this works:

              :print $result.     # print the result

In Python code you need to explicitly specify the scope name. When no scope name is given only the local scope is used. To get the equivalent of an Aap command that does not specify a scope, you need to use the "_no" scope in Python. The same example as above but now with a Python expression looks like this:

              :print `_no.result`.      # print the result

## Predefined Scopes

Aap defines a scope for each recipe and each block of commands.

A user may also define a specific scope, see below. These scope names must start with an alphabetical name. Scope names starting with an underscore are used for predefined scopes.

Each time a block of commands is executed a new scope is created. Thus when executing the commands for a dependency a second time, its scope will not contain items from the first time.

A variable may exist in several scopes with a different value. To specify which scope is to be used, a scope name is prepended before the variable name, using a dot to separate the two.

These scope specifiers can be used to access a specific scope:

_recipe | The current recipe. Useful in build commands that are defined in the recipe.
_top | The toplevel recipe. This can be regarded as the global scope.
_default | The scope of default values, after the defaults settings have been done, but before reading user or system startup recipes. Cannot be used in the recipe that sets the default settings.
_start | The scope of startup values, as it was before reading the toplevel recipe. Cannot be used in the recipe that sets the default settings and in the startup recipes.
_arg | The scope of variables set on the command line. Can be used to obtain the values set when Aap was executed or arguments of the :execute command. Although the scope is writable, thus you can mess it up...
_parent | The parent recipe. Only valid in a child recipe.
_caller | The scope of the command block that invoked the current command block. Can only be used in command blocks of dependencies, rules, actions and :tree.

These scope specifiers can be used to search scopes to find a variable. The first scope in which the variable exists is used.

_no | No scope, equal to leaving out the scope specifier in recipe commands, but required in Python commands. First looks in the current scope, then "_stack" and then "_tree".
_stack | Uses the scope of the command block that invoked the current scope, the command blocks that invoked that scope, and further up the call stack. Excludes the toplevel. Can only be used in command blocks of dependencies, rules and actions.
_tree | Uses the scope of the current recipe, its parent, the parent of its parent, etc., up to the toplevel. In the toplevel recipe it is equal to "_top".
_up | First uses "_stack" and then "_tree", but excludes the current scope.

These are the scopes searched for a variable with the "_up" scope when it is used in a build command block:

1. Invoking command blocks. That is, the scope of the command block that invoked the current command block with an :update command or because of a dependency. Then the scope of the command block that invoked that command block, and so on. This excludes the toplevel.

2. The recipe in which the command block was defined, its parent and so on. This goes on until and including the toplevel.

This is used both for reading a variable and assigning a new value. It is an error when assigning a new value to a variable that does not exist.

For the commands of an action the sequence is slightly different:

1. Invoking command blocks. That is, the scope of the command block that invoked the action with a :do command. Then the scope of the command block that invoked that command block, and so on. This excludes the toplevel.

2. The recipe in which the ":do" command was invoked, its parent and so on. This goes on until and including the toplevel.

3. The recipe in which the action was defined, its parent and so on. This goes on until the toplevel.

The "_no" scope is used for a variable in recipe commands without a specified scope. Thus these two are equivalent:

              :print $foobar
              :print $_no.foobar

But in Python commands a variable without a specified scope is always in the local scope. You must use "_no" to get the same effect:

              foo = $bar         # finds "bar" in local or "_up" scope
              @foo = bar         # finds "bar" in local scope only
              @foo = _no.bar     # finds "bar" in local or "_up" scope

When reading a variable with the "_no" scope it is first looked up in the local scope. If it does not exist, the "_stack" and "_tree" scopes are used, as explained above.

When writing a variable without a specified scope it is always put in the local scope. A specific situation where this may lead to an unexpected result is appending:

              foo += something

This is equivalent to:

              foo = $foo something

This obtains the value of "foo" from the first scope where it is defined, but it is set in the current scope. To change the variable where it is defined use the "_no" scope explicitly:

              _no.foo += something

## User Scopes

The user can define a new scope by assigning a value to a variable, using the scope name:

            s_debug.foo = xxx

This creates the scope "s_debug" if it didn't exist yet. The variable "foo" within that scope is assigned the value "xxx".

The scope name must start with an alphabetic character. Following characters may be letters, digits and the underscore.

A user defined scope is only used when explicitly specified. The "_no" and "_up" scopes do not use it.

The scope can be accessed from everywhere, except recipes that create a new toplevel scope have their own set of user defined scopes. That is when using :execute or ":child {nopass}". ":execute {pass}" and :child do share the user scopes.

There cannot be a scope name and a variable with the same name. This applies to variables in ALL scopes! Thus when you have a scope "foo" in one place, you cannot use the variable "foo" anywhere else. The only exception is that you can use the variable "foo" in scopes that have been abandoned when the user scope "foo" is created, but that is tricky.

Recommendation: Let user scope names start with "s_".

A user scope can be specified for a dependency:

            s_foo.OPTIMIZE = 4
            ...
            foo : {scope = s_foo} foo.c
                :do build $source

A user scope can be specified for a rule:

            :rule %.a : {scope = s_aaa} %.b

A user scope can be specified for an action:

            :do foobar {scope = s_some} foo.bar

## Variables In Build Commands

A dependency and a rule can have a list of commands. For these commands the following variables are available:

$source | The list of input files as a string.
$source_list | The list of input files as a Python list.
$source_dl | Only for use in Python commands: A list of dictionaries, each input item is one entry.
$depend | The list of dependencies (source files plus virtual dependencies) as a string.
$depend_list | The list of dependencies (source files plus virtual dependencies) as a Python list.
$depend_dl | Only for use in Python commands: A list of dictionaries, each dependency item is one entry.
$target | The list of output files as a string.
$target_list | The list of output files as a Python list.
$target_dl | Only for use in Python commands: A list of dictionaries, each output item is one entry.
$buildtarget | The name of the target for which the commands are executed. It is one of the items in $target.
$match | For a rule: the string that matched with %

Example:

            doit {virtual}:
                :print building $target
            prog : "main file.c" doit
                :print building $target from $source

Results in:

building doit{virtual=1}
building prog from "main file.c"

Note that quoting of expanded $var depends on the command used.

The Python lists $source_list and $target_list can be used to loop over each item. Example:

            $OUT : foo.txt
                @for item in target_list:
                    :print $source > $item

Note the difference between $source and $depend: $source only contains real files, $depend also contains virtual dependencies.

The list of dictionaries can be used to access the attributes of each item. Each dictionary has an entry "name", which is the (file) name of the item. Other entries are attributes. Example:

            prog : file.c {check = md5}
                @print source_dl[0]["name"], source_dl[0]["check"]

Results in: file.c md5

Prev | Up | Next
Chapter 33. Recipe Syntax | Contents | Chapter 35. Common Variables