Chapter 32. Aap Command Line Arguments

Three Kinds Of Arguments

aap [option]... [assignment]... [target]...

The order of arguments is irrelevant. Options are explained in the next section.

Assignments take the form "VAR=value". This works just like putting this at the top of the main recipe used. But the shell used to start Aap may require escaping special characters, such as spaces. Putting the argument in double quotes often works (but not always).

Targets specify what needs to be done. If no target is given, one of the targets in the recipe is executed, see Recipe Execution Details.

Variables in the targets are expanded. This makes it possible to build a target in a directory whose name is set in the recipe. For example, to build a target in $BDIR:

       aap '$BDIR/foo.o'

Note: you must make sure that the variable is not expanded by the shell. In the example this is done by putting the argument in single quotes. This works for most Unix shells. To use a target with a $ character in the name use $($) in place of the $.


An option must appear only once, except for the ones that are noted to be allowed multiple times.


For a remote file, don't use a cached copy. Download it once for this invocation. Note that the file may be downloaded anyway, because it is not always possible to check if the cached copy is still valid. Use the {usecache} or {constant} attribute on a file to use the cached version whenever possible, see :fetch.

-c command
--command command

After reading the recipe, execute command. May appear several times, all the commands are executed.

Commands to be executed can be specified on the command line. This is useful, for example, to fetch individual files:

        aap -c ":fetch main.c"
        aap -c ":commit common.h"

Since the recipe is first read (and all child recipes), the attributes that are given to "main.c" will be used for fetching.

The commands are executed before updating targets. When no target is specified nothing is built, only the specified commands are executed. But the toplevel commands in the recipe are always executed, before executing the command arguments.

Keep in mind that the shell must not change the argument, use single quotes to avoid $VAR to be expanded by the shell:

        aap -c ':print $SOURCE'

--changed file

The file file is considered changed, no matter whether it was really changed. Targets build from file will also be considered changed, recursively.

Similar to the recipe command :changed file.


Only take action when file contents was changed, not when build commands or attributes changed.

For normal dependencies the buildcheck is ignored. This means that the build commands can be changed without causing them to be executed. The commands are executed anyway when one of the sources is out-of-date.

For publishing the "publish" attribute is ignored. The file is still published when its contents changed since the last time it was published to any destination, or if it was never published.

The signatures are updated as usual (unless --nobuild is used as well). Thus the new buildcheck and "publish" attribute are stored. This is useful if the buildcheck or "publish" argument changed in a way that you know does not require building or publishing.

-d flags
--debug flags

Switch on debugging for flags. Not implemented yet.

-f file
--recipe file

Specify the main recipe to read. When an URL is used the recipe is downloaded to the current directory before it is used. The name is the last part of the path. If it already exists the user is asked whether it should be overwritten. Example:

        cd /usr/local/share/vim/vim62/runtime
        aap -f 

When the file is "NONE" no recipe is read. This is useful when only a command is to be executed. Example:

        aap -f NONE -c ':print $AAP' 


Force rebuilding everything. That a target is already up-to-date is ignored.


Print a help message and exit. Does not read a recipe.

-I directory
--include directory

Add a directory to search for included recipes. This option may appear multiple times.

--install package

Install the package package. Only works for those packages that are supported, such as "cvs" and "rcp".

Does not read a recipe in the usual way, only the specified package is installed.

-j number
--jobs number

Maximum number of parallel jobs. Not implemented yet.


Continue after encountering an error.

When an error is detected in a block of build commands, the execution of that block is aborted. Building continues for other targets, but a target that depends on a target that failed to build will not be build.

To continue execution after an error in the same block of commands use the Python ":try" statement. Example:

            :print  this is an $error
        @except UserError, e:
            :print caught error: `str(e)`

Not fully implemented, still stops at some errors. Careful: When an error has side effects strange things may happen.


Do not recurse into subdirectories. Only applies to "add" and "remove" targets on the command line. Also for "revise" for its remove action.


Only print messages about what will be done, don't execute build rules. Commands at the toplevel and commands to discover dependencies are executed, but system commands, commands that download, upload, write or delete files and version control commands are skipped.

Note: since no files are downloaded, :child commands won't work for not existing recipes.


Do not fetch recipes when using the "fetch" and "update" targets. Useful if the current recipe is to be used while files must be fetched.

--profile file

Profile the execution of A-A-P and write the results in file. This file can then be examined with the standard Python module "pstats". The script can be used for this (it is located with the other Aap modules).


Fetch the recipe and child recipes. This is impled by using a "refresh", "fetch" or "update" target, unless "--nofetch-recipe" is used.


Stop building after encountering an error. This is the default, thus this option has no effect. Also see --continue.


Print less information, see $MESSAGE.


Update signatures on targets without executing build commands. After doing this the specified targets and intermediate results are considered up-to-date.

Commands at the toplevel will be executed, except system commands, commands that write a file and version control commands.


Search the directory tree upwards for the main.aap recipe. Useful when in a sub-directory of a large project, where the main.aap recipe is an unknown number of directory levels upwards.


Print version information and exit. Does not read a recipe.


Print more information, see $MESSAGE.


End of options, only targets and assignments follow. Use this when a target starts with a "-".