This is the alphabetical list of all A-A-P commands. Common arguments are explained at the end.
Some commands can be used in a pipe. A pipe is a sequence of commands separated by '|', where the output of one command is the input for the next command. Example:
:cat foo | :eval re.sub('this', 'that', stdin) | :assign bar |
In the commands below [redir] indicates the possibility to redirect stdout.
:action action filetype-out [filetype-in]
Define the commands for an action. See Chapter 23.
:do build {target = prog} foo.c |
See :do for executing actions.
:add Version control command, see Chapter 16. :addall Version control command, see Chapter 16. :assign varname Assign stdin to a variable. Can only be used after a "|". :attr {attrname} ... itemname ... :attribute {attrname} ... itemname ... Add the list of attributes "{attrname} ..." to each item in the list of items "itemname ...". Creates a node for each "itemname". :attr itemname {attrname} ... :attribute itemname {attrname} ... Add attributes "{attrname} ..." to item "itemname". The above two forms can be mixed. Example: :attr {fetch = cvs://} foo.c patch12 {constant} This adds the "fetch" attribute to both foo.c and patch12, and the "constant" attribute only to patch12. This does the same in two commands: :attr {fetch = cvs://} foo.c patch12 :attr {constant} patch12 Note: the attributes are added internally. When using ":print $var" this only shows the attributes given by an assignment, not the ones added with ":attr". |
:cat [redir] fname...
Concatenate the arguments and write the result to stdout. Files are read like text files. The "-" argument can be used to get the output of a previous pipe command. When redirecting to a file this output file is created before the arguments are read, thus you cannot use the same file for input.
See here for [redir].
:checkin Version control command, see Chapter 16. :checkinall Version control command, see Chapter 16. :checkout Version control command, see Chapter 16. :checkoutall Version control command, see Chapter 16. :child [{nopass}] name Read recipe "name" as a child. Mostly works like the commands were in the parent recipe, with a few exceptions: - When "name" is in another directory, change to that directory and accept all items in it relative to that directory. - Build commands defined in the child are executed in the directory of the child. Thus it works as if executing the child recipe in the directory where it is located. - Variables from the parent recipe can be used but changes to them will be used in the child only. When the {nopass} option is used, variables from the parent recipe are not passed to the child. New variables are local to the child recipe. Except for the variables exported with ":export". - Build commands are executed with the variables of the child recipe available, plus the variables of the toplevel parent. For exported variables the value of the toplevel parent is used, for others the local values are used. The "fetch" attribute is supported like with ":include". :chmod [options] mode name ... Change the protection flags of a file or directory. Currently "mode" must be an octal number, like used by the Unix "chmod" command. Useful values: 755 executable for everyone, writable by user 444 read-only 600 read-write for the user only 660 read-write for user and group OPTIONS {f} {force} don't give an error when the file doesn't exist :commit Version control command, see Chapter 16. :commitall Version control command, see Chapter 16. :copy [options] from ... to Copy files or directory trees. "from" and "to" may be URLs. This means :copy can be used to upload and download a file, or even copy a file from one remote location to another. Examples: :copy file_org.c file_dup.c :copy {r} onedir twodir :copy *.c backups :copy http://vim.sf.net/download.php download.php :copy $ZIP ftp://upload.sf.net/incoming/$ZIP :copy ftp://foo.org/README ftp://bar.org/mirrors/foo/README When "from" and "to" are directories, "from" is created in "to". Unlike the Unix "cp" command, where this depends on whether "to" exists or not. Thus: :copy {recursive} foo bar will create the directory "bar/foo" if it doesn't exist yet. If the contents of "foo" is to be copied without creating "bar/foo", use this: :copy {recursive} foo/* bar OPTIONS {f} {force} forcefully overwrite an existing file or dir (default) {e} {exist} {exists} don't overwrite an existing file or directory {i} {interactive} before overwriting a local file, prompt for confirmation (currently doesn't work for remote files) {u} {unlink} when used with {recursive}, don't copy a symlink, make a copy of the file or dir it links to {p} {preserve} preserve file permissions and timestamps as much as possible {r} {recursive} recursive, copy a directory tree. "to" is created and should not exist yet. {q} {quiet} don't report copied files Wildcards in local files are expanded. This uses Unix style wildcards. When there is no matching file the command fails (also when there are enough other arguments). When (after expanding wildcards) there is more than one "from" item, the "to" item must be a directory. For "to" only local files, ftp:// and scp:// can be used. See "URLs" for info on forming URLs. Attributes for "from" and "to" are currently ignored. :del [options] file ... :delete [options] file ... Delete files and/or directories. OPTIONS {f} {force} don't fail when a file doesn't exist {r} {recursive} delete directories and their contents recursively {q} {quiet} don't report deleted files Wildcards in local files are expanded. This uses Unix style wildcards. When there is no matching file the command fails (also when there are enough other arguments). CAREFUL: if you make a mistake in the argument, anything might be deleted. For example, accidentally inserting a space before a wildcard: :del {r} dir/temp * To give you some protection, the command aborts on the first error. Thus if "dir/temp" didn't exist in the example, "*" would not be deleted. :deldir [options] dir ... Delete a directory. Fails when the directory is not empty. OPTIONS {f} {force} don't fail when a directory doesn't exist; still fails when it exists but is not a directory or could not be deleted {q} {quiet} don't report deleted directories |
:do action [fname...]
Execute an action. The commands executed may depend on the types of the input and/or output files. See Chapter 23.
:do build {target = prog} foo.c |
See :action for defining actions.
:eval [redir] python-expression Filter stdin using a Python expression. When not used after "|" evaluate the Python expression. The Python expression is evaluated as specified in the argument. The "stdin" variable holds the value of the input as a string, it must be present when ":eval" is used after "|". $var items are not expanded before evaluating the python expression. To get the value of $var use "var" as a Python variable. The expression must result in the filtered string or something that can be converted to a string with str(). This becomes stdout. The result may be empty. Examples: :print $foo | :eval re.sub('<.*?>', '', stdin) > tt :eval os.name | :assign OSNAME Note that the expression must not contain a "|" preceded by white space, it will be recognized as a pipe. Also there must be no ">" preceded by white space, it will be recognized as redirection. $VAR items will be expanded in the filter command. :execute [{pass}] name [ argument ] ... Execute recipe "name" right away. This works like executing aap on "name". Variables from the current recipe are passed to the executed recipe when the "{pass}" option is used. ":export" can be used to get variables from the executed recipe into the current recipe. The "fetch" attribute is supported like with ":include". Optional arguments may be given, like on the command line. This is useful for specifying targets and variable values. "-f recipe" is ignored. Example: TESTPROG = ./myprog :execute test.aap test1 test2 This command is useful when a recipe does not contain dependencies that interfere with sources and targets in the current recipe. For example, to build a command the current recipe depends on. For example, when the program "mytool" is required and it doesn't exist yet, execute a recipe to build and install it: @if not program_path("mytool"): :execute mytool.aap install :sys mytool Another example: build two variants: :execute build.aap GUI=motif :execute build.aap GUI=gtk :exit Quit executing recipes. When used in build commands, the "finally" targets will still be executed. But a ":quit" or ":exit" in the commands of a "finally" target will quit further execution. :export varname ... When used at the toplevel, export variable "varname" with its current value to the recipe that uses the current recipe as a child or executes it. When used in build commands, export variable "varname" to the recipe or build commands that invoked and export to the toplevel of the current recipe. Useful to pass a value to the "finally" target or remember a value for the next invocation. When the variable was assigned a value with "$=" the argument will be evaluated now. Note: When exporting a variable that contains the name of a file, a relative file name will not be valid in another directory. When using these commands: :child dir/main.aap :cat $RESULT using the following in dir/main.aap causes trouble: RESULT = foo.txt bar.txt export RESULT Instead use: RESULT = foo.txt bar.txt RESULT = `aap_abspath(RESULT)` export RESULT :global name ... Define variable "name" to be global to other recipes. Even when "name" has been assigned a value, build commands (actions, dependencies or rules) will still use the value passed on by who invoked the build commands. Example: CFLAGS = -O4 :global CFLAGS This means that when the value of CFLAGS is changed this value will be used for build commands defined in this recipe. :include [options] name Read recipe "name" as if it was included in the current recipe. Does not change directory and file names are considered to be relative to the current recipe, not the included recipe. The "fetch" attribute can be used to specify a list of locations where the recipe can be fetched from. OPTIONS {q} {quiet} don't give a warning for a file that can't be read. :local name ... Define variable "name" to be local to this recipe. It will not be passed on to child recipes. Build commands defined in this recipe (actions, dependencies or rules) will use the value from the recipe instead of a value passed from who invoked the commands. :mkdir [options] dir ... Create directory. This fails when "dir" already exists and is not a directory. A "mode" attribute on a directory can be used to specify the protection flags for the new directory. Example: :mkdir {r} ~/secret/dir {mode = 0700} The default mode is 0644. The effective umask may reset some of the bits though. OPTIONS {f} {force} don't fail when a directory already exist; still fails when it is not a directory or could not be created {q} {quiet} don't report created directories {r} {recursive} also create intermediate directories, not just the deepest one Note: automatic creation of directories can be done by adding the {directory} attribute to a source item. :mkdownload name file ... Generate a recipe "name" that downloads the specified files. Each file must have a "fetch" attribute, which is used in the generated recipe. When the file "name" already exists it is overwritten (without warning). MD5 checksums are generated and used in the recipe to fetch a file only when the checksum differs. Example of one item: file = foobar.txt @if get_md5(file) != "a5dba5bce69918c040703e9b8eb35f1d": :fetch {fetch = ftp://foo.org/files/%file%} $file When there is a "fetch" attribute on "name", this will be used to add a ":recipe" command at the start of the generated recipe. :move [options] from ... to Move files or directories. Mostly like ":copy", except that the "from" files/directories are renamed or, when renaming isn't possible, copied and deleted. OPTIONS {f} {force} forcefully overwrite an existing file or directory (default) {e} {exist} {exists} don't overwrite an existing file or directory {i} {interactive} before overwriting a local file, prompt for confirmation (currently doesn't work for remote files) {q} {quiet} don't report moved files |
:print [redir] [text...]
Print the arguments on stdout. Without arguments a line feed is produced. $var items are expanded, otherwise the arguments are produced literally, including quotes:
:print "hello" |
"hello"
Leading white space is skipped, but white space in between arguments is kept. To produce leading white space start with the "empty" variable::print $empty indented text |
indented text
When used in a pipe the stdin variable holds the input.See here for [redir].
:proxy [protocol] {address} Specify a proxy server. Examples: :proxy ftp ftp://ftp.proxy.net:1234 :proxy http://www.someproxy.com:1080 The [protocol] can be "ftp", "http" or "gopher". When omitted "http" is used. Case doesn't matter. The {address} is a URL with the port number included. The result of this command is that an environment variable is set, as the Python library "urllib" requires. Therefore it must be done early in the startup phase, before accessing the internet. :publish file ... :publish {attribute} ... file ... Publish the files mentioned according to their "publish" or "commit" attribute. Creates directories when needed (for CVS only one level). :publishall file ... Like ":publish" but also remove files that are not an argument. Careful! :python python-commands A block of Python code. The block ends when the indent drops to the level of ":python" or below. :python {term} python-commands {term} A block of Python code. The block ends when {term} is found on a line by itself. The Python commands may have any indent. White space before and after {term} is allowod and a comment after {term} is also allowed. {term} can contain any characters but no white space. :quit See ":exit". :recipe {fetch = URL ... } Location of this recipe. The "fetch" attribute is used like with ":child": a list of locations. The first one that works is used. When aap was started with the "fetch" argument, fetch the recipe and restart reading it. Using the "fetch" or "update" target causes this as well. The commands before ":recipe" have already been executed, thus this may cause a difference from executing the new recipe directly. The values of variables are restored to the values before executing the recipe. Fetching the recipe is done only once per session. :fetch file ... Fetch the files mentioned according to their "fetch" or "commit" attribute. When a file does not have these attributes or fetching fails you will get an error message. Files that exist and have a "fetch" attribute with value "no" are skipped. The name "." can be used to update the current directory: :fetch . {fetch = cvs://$CVSROOT} :fetch {attribute} ... file ... Like above, apply {attribute} to all following items. :remove Version control command, see Chapter 16. :removeall Version control command, see Chapter 16. :reviseall Version control command, see Chapter 16. :rule tpat ... : spat ... commands Define a rule to build files matching the pattern "tpat" from a file matching "spat". There can be several "tpat" patterns, the rule is used if one of them matches. There can be several "spat" patterns, the rule is used if they all exist (or no better rule is found). When "commands" is missing this only defines that "tpat" depends on "spat". Can only be used at the toplevel. The "skip" attribute on 'tpat' can be used to skip certain matches. $target and $source can be used in "commands" for the actual file names. $match is what the "%" in the pattern matched. Alternative: instead of matching the file name with a pattern, ":action" uses filetypes to specify commands. :start cmds Like ":sys" and ":system", but don't wait for the commands to finish. Errors are ignored. Runs in the same terminal, which will cause problems when the command waits for input. Open a new terminal to run that command in. Example: :start xterm -e more README WARNING: Using ":start" probably makes your recipe non-portable. :sys [options] cmds :system [options] cmds Execute "cmds" as system (shell) commands. Example: :system filter <foo >bar :sys echo one two The following lines with more indent are appended, replacing the indent with a single space. Example: :sys echo one two This echos "one two". Options: {i} or {interactive}: don't log output (see below) {q} or {quiet}: Don't echo the command {l} or {log}: Redirect all output to the log file, do not echo it {interactive} and {log} cannot be used at the same time. Output is logged by default. If this is undesirable (e.g., when starting an interactive command) prepend "{i}" or "{interactive}" to the command. It will be removed before executing it. Example: :system {i} vi bugreport When the "async" variable is set and it is not empty, ":sys" works like "start", except that consecutive commands are executed all at once in one shell. WARNING: Using ":sys" or ":system" probably makes your recipe non-portable. :syseval [redir] command Execute shell command "command" and write its output to stdout. Only stdout of the command is captured. When {stderr} is just after the command name, stderr is also captured. Example: :syseval hostname | :assign HOSTNAME When used in a pipe, the stdin is passed to the command. Example: :print $var | :syseval sort | :assign var Note the difference with the ":sys" command: redirection in ":sys" is handled by the shell, for ":syseval" it is handled by aap. When executing the command fails, the result is empty. The exit value of the command is available in $exit. WARNING: Using ":syseval" probably makes your recipe non-portable. :syspath path arg ... Use "path" as a colon separated list of commands, use the first one that works. When %s appears in "path", it is replaced with the arguments. If it does not appear, the arguments are appended. Other appearences of % in "path" are removed, thereby reducing %% to % and %: to : while avoiding their special meaning. Don't forget that "path" must be one argument, use quotes around it to include white space. Example: :syspath 'vim:vi:emacs' foobar.txt Output is not logged. Note: on MS-Windows it's not possible to detect if a command worked, the first item in the path will always be used. WARNING: Using ":syspath" probably makes your recipe non-portable. :tag Version control command, see Chapter 16. :tagall Version control command, see Chapter 16. :tee [redir] fname ... Write stdin to each file in the argument list and also write it to stdout. This works like a T shaped connection in a water pipe. Example: :cat file1 file2 | :tee totfile | :assign foo :touch [options] name ... Update timestamp of file or directory "name". OPTIONS {f} {force} create the file when it doesn't exist {e} {exist} create the file when it doesn't exist, don't update timestamp when the file already exists If "name" doesn't exist and {force} and {exist} are not present the command fails. If "name" doesn't exist and {force} or {exist} is present an empty file will be created. If "name" does exist and {exist} is present nothing happens. A "directory" attribute can be used to specify a non-existing "name" is to be created as a directory. There is no check if an existing "name" actually is a directory. A "mode" attribute can be used to specify the mode with which a new file or directory is to be created. The value is in the usual octal form, e.g., "0644". :unlock Version control command, see Chapter 16. :unlockall Version control command, see Chapter 16. :update [{force}] target ... Update "target" now, if it is outdated or when "{force}" is used. One or more targets can be specified, each will be updated. When this appears at the top level, a dependency or rule for the target must already have been specified, there is no look-ahead. :verscont Version control command, see Chapter 16. |
[redir]
Redirect the output of a command. Can be one of these items:
> fname | write output to file "fname"; fails when "fname" already exists |
>! fname | write output to file "fname"; overwrite an existing file |
>> fname | append output to file "fname"; create the file if it does not exist yet |
| command | pipe output to the following "command" |
The file name can be a URL. The text will first be written to a local file and then the file is moved to the final destination.
The white space before the file name may be omitted. White space before the ">" and "|" is required. To avoid recognizing the ">" and "|" for redirection and pipes, use $gt and $pipe.
When a command produces text on stdout and no redirection or pipe is used, the stdout is printed to the terminal.
URLs In various places URLs can be used to specify remote locations and the method how to access it. http://machine/path HTTP protocol, commonly used for web sites. read-only "machine" can also be "machine:port". ftp://machine/path FTP protocol. "machine" can also be "machine:port". For authentication the ~/.netrc file is used if possible (unfortunately, the Python netrc module has a bug that prevents it from understanding many netrc files). Alternatively, login name and password can be specified just before the machine name: ftp://user@machine/path ftp://user:password@machine/path When ":password" is omitted, you will be prompted for entering the password. Either way: ftp sends passwords literally over the net, thus this is not secure! Should use "scp://" instead. scp://machine/path SCP protocol (using SSH, secure shell). Requires the "scp" program installed. Additionally a user name can be specified: scp://user@machine/path "path" is a relative path to the directory where "ssh" logs in to. To use an absolute path prepend a slash: scp://machine//path The resulting path for the "scp" command uses a ":" instead of the first slash. |