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:

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:

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

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:

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:

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:

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:

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

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

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:

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:

Example:

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

Results in:

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