<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 42. A-A-P Commands</title><meta name="generator" content="DocBook XSL Stylesheets V1.71.1"><link rel="start" href="index.html" title="A-A-P Recipe Executive"><link rel="up" href="reference.html" title="Part III. Reference Manual"><link rel="prev" href="ref-python.html" title="Chapter 41. A-A-P Python functions"><link rel="next" href="appendix.html" title="Part IV. Appendixes"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table width="100%" id="navtable"><tbody><tr><td align="left" class="left" width="33%"><b><a href="http://www.a-a-p.org">A-A-P home page</a></b></td><td align="center" class="center" width="34%"><b><a href="index.html">A-A-P Recipe Executive</a></b></td><td align="right" class="right" width="33%"></td></tr><tr><td align="left" class="left"><a accesskey="p" href="ref-python.html">Prev</a></td><td align="center" class="center">Reference Manual</td><td align="right" class="right"><a accesskey="n" href="appendix.html">Next</a></td></tr></tbody></table><hr><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-commands"></a>Chapter 42. A-A-P Commands</h2></div></div></div><h2><a name="id2693868"></a>Commands grouped by functionality</h2><p>
</p><div class="informaltable"><table border="0"><colgroup><col width="200"><col></colgroup><tbody><tr><td colspan="2">Dependencies</td><td> </td></tr><tr><td> <a href="ref-commands.html#cmd-program">:program</a></td><td> Define the sources for an executable program.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-lib">:lib</a></td><td> Define the sources for a static library.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-ltlib">:ltlib</a></td><td> Define the sources for a library to be made with
libtool.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-dll">:dll</a></td><td> Define the sources for a shared (dynamically loaded)
library.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-produce">:produce</a></td><td> Generic way to build something from sources.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-totype">:totype</a></td><td> Use routes to turn one filetype into another.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-rule">:rule</a></td><td> Define build commands for files matching a pattern.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-delrule">:delrule</a></td><td> Delete a specific rule.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-clearrules">:clearrules</a></td><td> Delete all rules.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-update">:update</a></td><td> Update a target, build it when it is outdated.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-changed">:changed</a></td><td> Mark a file as changed.</td><td class="auto-generated"> </td></tr><tr><td> </td><td> </td><td class="auto-generated"> </td></tr><tr><td colspan="2">Recipes</td><td> </td></tr><tr><td> <a href="ref-commands.html#cmd-child">:child</a></td><td> Read a child recipe.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-include">:include</a></td><td> Include another recipe.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-import">:import</a></td><td> Include a module from the <span class="application">Aap</span> distribution.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-execute">:execute</a></td><td> Execute a recipe.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-recipe">:recipe</a></td><td> Define the URL where the recipe can be obtaind from.</td><td class="auto-generated"> </td></tr><tr><td> </td><td> </td><td class="auto-generated"> </td></tr><tr><td colspan="2">Actions</td><td> </td></tr><tr><td> <a href="ref-commands.html#cmd-action">:action</a></td><td> Define commands for an action.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-do">:do</a></td><td> Invoke an action.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-route">:route</a></td><td> Define a route of actions to turn one filetype into another.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-filetype">:filetype</a></td><td> Define filetype detection.</td><td class="auto-generated"> </td></tr><tr><td> </td><td> </td><td class="auto-generated"> </td></tr><tr><td colspan="2">Up- and Downloading</td><td> </td></tr><tr><td> <a href="ref-commands.html#cmd-fetch">:fetch</a></td><td> Download files.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-fetchall">:fetchall</a></td><td> Download all files with a "fetch" attribute.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-publish">:publish</a></td><td> Upload the specified files.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-publishall">:publishall</a></td><td> Upload all files with a "publish" attribute.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-mkdownload">:mkdownload</a></td><td> Create a recipe to download files.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-proxy">:proxy</a></td><td> Define a proxy server.</td><td class="auto-generated"> </td></tr><tr><td> </td><td> </td><td class="auto-generated"> </td></tr><tr><td colspan="2">Version control</td><td> </td></tr><tr><td> <a href="ref-commands.html#cmd-add">:add</a></td><td> Add a file to the version control repository.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-addall">:addall</a></td><td> Add all files with a "commit" attribute to the version control repository.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-checkin">:checkin</a></td><td> Checkin a file into the version control repository.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-checkinall">:checkinall</a></td><td> Checkin all files with a "commit" attribute into the version
control repository.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-checkout">:checkout</a></td><td> Checkout a file from the version control repository.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-checkoutall">:checkoutall</a></td><td> Checkout all files with a "commit" attribute from the version
control repository.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-commit">:commit</a></td><td> Commit files to the version control repository.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-commitall">:commitall</a></td><td> Commit all files with a "commit" attribute to the version
control repository.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-remove">:remove</a></td><td> Remove a file from the version control repository.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-removeall">:removeall</a></td><td> Remove all file without the "commit" attribute from the version
control repository.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-reviseall">:reviseall</a></td><td> combination of :checkinall and :removeall.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-tag">:tag</a></td><td> Add a tag in the version control repository for a file.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-tagall">:tagall</a></td><td> Add a tag in the version control repository for all files with
the "commit" attribute .</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-unlock">:unlock</a></td><td> Unlock a checked out file.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-unlockall">:unlockall</a></td><td> Unlock all checked out files with the "commit" attribute.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-verscont">:verscont</a></td><td> Generic version control command.</td><td class="auto-generated"> </td></tr><tr><td> </td><td> </td><td class="auto-generated"> </td></tr><tr><td colspan="2">System commands</td><td> </td></tr><tr><td> <a href="ref-commands.html#cmd-asroot">:asroot</a></td><td> Execute a command as the system administrator.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-sys">:sys</a></td><td> Execute a system command.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-sys">:system</a></td><td> Execute a system command.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-start">:start</a></td><td> Run a system command asynchronously.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-syseval">:syseval</a></td><td> Execute a system command and catch the output.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-sysdepend">:sysdepend</a></td><td> Execute a system command to figure out dependencies.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-syspath">:syspath</a></td><td> Execute one of a number of commands.</td><td class="auto-generated"> </td></tr><tr><td> </td><td> </td><td class="auto-generated"> </td></tr><tr><td colspan="2">Pipe commands</td><td> </td></tr><tr><td> <a href="ref-commands.html#cmd-assign">:assign</a></td><td> Assign stdin to a variable.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-cat">:cat</a></td><td> List or concatenate files.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-print">:print</a></td><td> Print a message</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-log">:log</a></td><td> Write a message to the log file</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-tee">:tee</a></td><td> Echo stdin to stdout and also write it in a file. </td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-eval">:eval</a></td><td> Evaluate a Python expression</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-syseval">:syseval</a></td><td> Execute a system command and catch the output.</td><td class="auto-generated"> </td></tr><tr><td> </td><td> </td><td class="auto-generated"> </td></tr><tr><td colspan="2">File system commands</td><td> </td></tr><tr><td> <a href="ref-commands.html#cmd-copy">:copy</a></td><td> Copy files.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-move">:move</a></td><td> Rename or move a file.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-symlink">:symlink</a></td><td> Create a symbolic link.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-chmod">:chmod</a></td><td> Change the protection bits of a file.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-del">:del</a></td><td> Delete files.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-del">:delete</a></td><td> Delete files.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-deldir">:deldir</a></td><td> Delete directories.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-mkdir">:mkdir</a></td><td> Create a directory.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-touch">:touch</a></td><td> Create a file and/or update its timestamp.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-tree">:tree</a></td><td> Execute commands for a directory tree.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-cd">:cd</a></td><td> Change directory.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-chdir">:chdir</a></td><td> Change directory.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-pushdir">:pushdir</a></td><td> Change directory and remember the previous one.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-popdir">:popdir</a></td><td> Change to an older directory.</td><td class="auto-generated"> </td></tr><tr><td> </td><td> </td><td class="auto-generated"> </td></tr><tr><td colspan="2">Various</td><td> </td></tr><tr><td> <a href="ref-commands.html#cmd-attr">:attr</a></td><td> Attach attributes to items.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-attr">:attribute</a></td><td> Attach attributes to items.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-buildcheck">:buildcheck</a></td><td> Add a string to the build command signature.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-exit">:exit</a></td><td> Stop execution.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-quit">:quit</a></td><td> Stop execution.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-pass">:pass</a></td><td> Do nothing.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-variant">:variant</a></td><td> Define build variants.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-python">:python</a></td><td> Execute Python commands.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-conf">:conf</a></td><td> Do a configuration check.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-progsearch">:progsearch</a></td><td> Search for an executable program.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-assertpkg">:assertpkg</a></td><td> Check if a package is present, install it when not.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-installpkg">:installpkg</a></td><td> Install a package unconditionally.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-usetool">:usetool</a></td><td> Specify what tool to use.</td><td class="auto-generated"> </td></tr><tr><td> <a href="ref-commands.html#cmd-toolsearch">:toolsearch</a></td><td> Search for tools that can be used.</td><td class="auto-generated"> </td></tr></tbody></table></div><p>
</p><h2><a name="id2696318"></a>Alphabetical list of Commands</h2><p>
This is the alphabetical list of all A-A-P commands.
Common arguments are explained
<a href="ref-commands.html#common-arguments">at the end</a>.
</p><p>
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:
</p><pre class="programlisting">
:cat foo | :eval re.sub('this', 'that', stdin) | :assign bar
</pre><p>
Unix tradition calls the output that can be redirected or piped "stdout".
Reading input from a pipe is called "stdin".
</p><p>
In the commands below [redir] indicates the possibility to redirect stdout.
</p><p>
</p><div class="variablelist"><dl><dt><a name="cmd-action"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:action</code> <em class="replaceable"><code>action</code></em> <em class="replaceable"><code>filetype-out</code></em> [<em class="replaceable"><code>filetype-in</code></em>]</p></div></span></dt><dd><p>
Define the commands for an action.
See <a href="user-filetype.html" title="Chapter 28. Customizing Filetype Detection and Actions">Chapter 28, <i>Customizing Filetype Detection and Actions</i></a>.
</p><pre class="programlisting">
:action makeme {primary} me moo
:sys me < $source > $target
</pre><p>
The optional {primary} attribute, just after the action name,
indicates that this is the preferred action to be used for turning the
specified input filetypes into the specified output filetypes.
</p><p>
See <a href="ref-commands.html#cmd-do">:do</a> for executing actions.
</p></dd><dt><a name="cmd-add"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:add</code> [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...] <em class="replaceable"><code>fname</code></em>... </p></div></span></dt><dd><p>
Version control command, also see <a href="user-version.html" title="Chapter 18. Version Control">Chapter 18, <i>Version Control</i></a>.
</p><p>
Add the files to the repository. The files must exist locally.
Implies a "commit" of the files.
</p></dd><dt><a name="cmd-addall"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:addall</code> [<em class="replaceable"><code>option</code></em>...] [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...] [<em class="replaceable"><code>directory</code></em>...]</p></div></span></dt><dd><p>
Version control command, also see <a href="user-version.html" title="Chapter 18. Version Control">Chapter 18, <i>Version Control</i></a>.
</p><p>
Apply the <code class="literal">:add</code> command to all files in the directory that
have been given the "commit" attribute in the recipe (and child recipes)
but do not exist in the repository.
</p><p>
</p><div class="informaltable"><table border="0"><colgroup><col width="150"><col></colgroup><thead><tr><th>options</th><td class="auto-generated"> </td></tr></thead><tbody><tr><td>{l} {local}</td><td>don't do current directory recursively</td></tr><tr><td>{r} {recursive}</td><td>do handle arguments recursively</td></tr></tbody></table></div><p>
</p><p>
When no directory argument is given, the current directory is
used. It is inspected recursively, unless the "{local}"
option was given.
</p><p>
When directory arguments are given, each directory is
inspected. Recursively when the "{recursive}" option was
given.
</p><p>
When no "commit" attribute is specified here, it will be
obtained from any node.
</p></dd><dt><a name="cmd-asroot"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:asroot</code> <em class="replaceable"><code>command</code></em> </p></div></span></dt><dd><p>
Execute shell command "command" in a separate shell with super-user
privileges. Only the first time the root password will have to be
entered. Each executed command must be confirmed by the user (for
safety).
</p><p>
The command will be executed in the current directory of the recipe.
Variables in "command" will be expanded (no attributes, shell quoting).
stdin and stdout are redirected, this cannot be used for interactive
commands.
</p><p>
On non-Unix systems and when running <span class="application">Aap</span> as root this command is
equivalent to
<a href="ref-commands.html#cmd-system">:system</a>
.
</p><p>
When the user types "n" to refuse executing the command,
$sysresult will be set to a non-zero value. If the command is executed
successfully $sysresult is set to zero. When the command fails an error
message is generated.
</p><p>
To execute recipe commands you need to start <span class="application">Aap</span>, for example:
</p><pre class="programlisting">
:asroot $AAP -c 'copy {r} foodir /usr/local/share'
</pre><p>
$AAP includes the Python interpreter, so that it works the same way as how
the current <span class="application">Aap</span> was started.
</p></dd><dt><a name="cmd-assertpkg"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:assertpkg</code> <em class="replaceable"><code>package</code></em>... </p></div></span></dt><dd><p>
For each argument check if the command by that name can be found.
If not, ask the user and attempt installing the package for it.
</p><p>
Option: {optional} after the package name indicates the user may chose
not to install the package. Without this option the user cannot chose
to continue without the package being installed.
</p><p>
See <a href="user-package.html" title="Chapter 25. Automatic Package Install">Chapter 25, <i>Automatic Package Install</i></a> about using packages.
See <a href="ref-commands.html#cmd-installpkg">:installpkg</a> for installing a
package unconditionally.
</p></dd><dt><a name="cmd-assign"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:assign</code> <em class="replaceable"><code>varname</code></em> </p></div></span></dt><dd><p>
Assign stdin to a variable. Can only be used after a "|".
</p><p>
See <a href="ref-commands.html#arg-redir">here</a> about using stdin.
</p></dd><dt><a name="cmd-attr"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:attr</code> [<em class="replaceable"><code>{attrname}</code></em>...] <em class="replaceable"><code>itemname</code></em> [<em class="replaceable"><code>{attrname}</code></em>...]<br><code class="command">:attribute</code> [<em class="replaceable"><code>{attrname}</code></em>...] <em class="replaceable"><code>itemname</code></em> [<em class="replaceable"><code>{attrname}</code></em>...]</p></div></span></dt><dd><p>
Any "{attrname"} given before the items is added to each item in the
list of items "itemname ...".
The "{attrname"} give later are only added to the item just before it.
</p><p>
A node is created for each "itemname". This also means wildcards in
item names will be expanded.
</p><p>
Example:
</p><pre class="programlisting">
:attr {fetch = cvs://} foo.c patch12 {constant}
</pre><p>
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:
</p><pre class="programlisting">
:attr {fetch = cvs://} foo.c patch12
:attr {constant} patch12
</pre><p>
Note: the attributes are added internally. When using ":print
$var" this only shows the attributes given by an assignment, not
the ones added with
<a href="ref-commands.html#cmd-attr">:attr</a>.
</p></dd><dt><a name="cmd-buildcheck"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:buildcheck</code> <em class="replaceable"><code>argument</code></em>... </p></div></span></dt><dd><p>
Doesn't do anything. Placeholder for variables that are used
but don't show up in build commands, so that they will be
included in the buildcheck.
</p></dd><dt><a name="cmd-cat"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:cat</code> [<em class="replaceable"><code>redir</code></em>] <em class="replaceable"><code>fname</code></em>... </p></div></span></dt><dd><p>
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.
</p><p>
See <a href="ref-commands.html#arg-redir">here</a> for [redir].
</p></dd><dt><a name="cmd-cd"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:cd</code> <em class="replaceable"><code>dir</code></em>... </p></div></span></dt><dd><p>
Change directory to "dir". When "dir" is "-" it goes back to the
previous directory (it is an error if there was no previous
<a href="ref-commands.html#cmd-cd">:cd</a>
command in the current command block).
</p><p>
When multiple arguments are given, they are concatenated with path
separators inserted where needed. This is similar to doing a
<a href="ref-commands.html#cmd-cd">:cd</a> for
each argument, except that each argument but the first one is as handled
as a relative path:
</p><pre class="programlisting">
:cd /tmp /usr/local bin
</pre><p>
Is equivalent to:
</p><pre class="programlisting">
:cd /tmp
:cd ./usr/local
:cd bin
</pre><p>
</p><p>
If the target directory does not exist this command fails. Use
<a href="ref-commands.html#cmd-mkdir">:mkdir</a>
first if needed (note:
<a href="ref-commands.html#cmd-mkdir">:mkdir</a>
does not contatenate its
arguments!).
</p><p>
Note that at the start of each command block <span class="application">Aap</span> changes directory to
the directory of the recipe.
</p><p>
WARNING: variables with a relative path
become invalid! This includes $source and $target. Use
<a href="ref-python.html#python-var-abspath">var_abspath()</a>.
when needed.
</p></dd><dt><a name="cmd-changed"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:changed</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>name</code></em>... </p></div></span></dt><dd><p>
Consider file "name" changed, no matter whether it was
really changed.
</p><p>
Similar to the command line argument "--changed FILE".
</p><p>
</p><div class="informaltable"><table border="0"><colgroup><col width="150"><col></colgroup><thead><tr><th>options</th><td class="auto-generated"> </td></tr></thead><tbody><tr><td>{r} {recursive}</td><td>Targets build from file "name" will also be considered
changed, recursively.</td></tr></tbody></table></div><p>
</p></dd><dt><a name="cmd-chdir"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:chdir</code> <em class="replaceable"><code>dir</code></em> </p></div></span></dt><dd><p>
Same as
<a href="ref-commands.html#cmd-cd">:cd</a> .
</p></dd><dt><a name="cmd-checkin"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:checkin</code> [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...] <em class="replaceable"><code>fname</code></em>... </p></div></span></dt><dd><p>
Version control command, also see <a href="user-version.html" title="Chapter 18. Version Control">Chapter 18, <i>Version Control</i></a>.
</p><p>
Commit the files to the repository and unlock them.
Just like <code class="literal">:commit</code> and <code class="literal">:unlock</code>.
</p></dd><dt><a name="cmd-checkinall"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:checkinall</code> [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...]</p></div></span></dt><dd><p>
Version control command, also see <a href="user-version.html" title="Chapter 18. Version Control">Chapter 18, <i>Version Control</i></a>.
</p><p>
Apply the <code class="literal">:checkin</code> command to all files in the recipe (and
child recipes) that have the "commit" attribute.
</p></dd><dt><a name="cmd-checkout"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:checkout</code> [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...] <em class="replaceable"><code>fname</code></em>... </p></div></span></dt><dd><p>
Version control command, also see <a href="user-version.html" title="Chapter 18. Version Control">Chapter 18, <i>Version Control</i></a>.
</p><p>
Obtain the latest version of the files from the repository.
Lock the files for editing if possible.
</p></dd><dt><a name="cmd-checkoutall"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:checkoutall</code> [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...]</p></div></span></dt><dd><p>
Version control command, also see <a href="user-version.html" title="Chapter 18. Version Control">Chapter 18, <i>Version Control</i></a>.
</p><p>
Apply the <code class="literal">:checkout</code> command to all files in the recipe (and
child recipes) that have the "commit" attribute.
</p></dd><dt><a name="cmd-checksum"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:checksum</code> <em class="replaceable"><code>file</code></em>... </p></div></span></dt><dd><p>
For each file argument compute the MD5 checksum and compare it to the
"md5" attribute of the file.
An error is generated when a file doesn't exist or when the
checksums differ.
</p><p>
This command is useful to check if a downloaded file was not damaged
when downloading it.
</p></dd><dt><a name="cmd-child"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:child</code> [<em class="replaceable"><code>{nopass}</code></em>] <em class="replaceable"><code>name</code></em> </p></div></span></dt><dd><p>
Read recipe "name" as a child. Works like the commands were in the
parent recipe, with a number of exceptions:
</p><div class="orderedlist"><ol type="1"><li><p>
When "name" is in another directory, change to that directory and accept
all items in it relative to that directory.
</p></li><li><p>
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.
</p></li><li><p>
The child recipe defines a new scope. Variables set there without a
scope specification will be local to the child recipe.
</p></li><li><p>
When the {nopass} option is used, the child recipe is used as if it is a
toplevel recipe. Variables from the parent recipe are not available to
the child.
</p></li><li><p>
Build commands defined in the child recipe will be executed in the scope
of that recipe.
</p></li></ol></div><p>
</p><p>
The "fetch" attribute is supported like with
<a href="ref-commands.html#cmd-include">:include</a>.
</p><p>
The
<a href="ref-commands.html#cmd-child">:child</a> command can only appear at the
recipe level.
</p></dd><dt><a name="cmd-chmod"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:chmod</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>mode</code></em> <em class="replaceable"><code>name</code></em>... </p></div></span></dt><dd><p>
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:
</p><div class="informaltable"><table border="0"><colgroup><col width="150"><col></colgroup><thead><tr><th>mode</th><th>meaning</th></tr></thead><tbody><tr><td>755</td><td>executable for everyone, writable by
user</td></tr><tr><td>444</td><td>read-only</td></tr><tr><td>600</td><td>read-write for the user only</td></tr><tr><td>660</td><td>read-write for user and group</td></tr></tbody></table></div><p>
</p><p>
</p><div class="informaltable"><table border="0"><colgroup><col width="150"><col></colgroup><thead><tr><th>options</th><td class="auto-generated"> </td></tr></thead><tbody><tr><td>{c} {continue}</td><td>when an item with a wildcard does not have matches
continue with the next item</td></tr><tr><td>{f} {force}</td><td> don't give an error when the file doesn't exist </td></tr></tbody></table></div><p>
</p></dd><dt><a name="cmd-clearrules"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:clearrules</code> </p></div></span></dt><dd><p>
Delete all rules. Also see
<a href="ref-commands.html#cmd-delrule">:delrule</a>.
</p></dd><dt><a name="cmd-commit"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:commit</code> [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...] <em class="replaceable"><code>fname</code></em>... </p></div></span></dt><dd><p>
Version control command, also see <a href="user-version.html" title="Chapter 18. Version Control">Chapter 18, <i>Version Control</i></a>.
</p><p>
Update the repository for each file that was changed.
This is also done for a file that didn't change, it's
up to the version control software to check for an
unchanged file (it might have been changed in the
repository).
</p><p>
Do checkout/checkin when checkout is required.
</p><p>
Don't change locking of the file.
</p><p>
Uses a "logentry" attribute when a log entry is to be
done. When there is no "logentry" attribute the
$LOGENTRY variable is used. If neither is given you
are prompted to enter a message.
</p><p>
Adds new files when needed.
</p><p>
Creates directories when needed (CVS: only one level).
</p></dd><dt><a name="cmd-commitall"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:commitall</code> [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...]</p></div></span></dt><dd><p>
Version control command, also see <a href="user-version.html" title="Chapter 18. Version Control">Chapter 18, <i>Version Control</i></a>.
</p><p>
Apply the <code class="literal">:commit</code> command to all files in the recipe (and
child recipes) that have the "commit" attribute.
</p></dd><dt><a name="cmd-conf"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:conf</code> <em class="replaceable"><code>checkname</code></em> [<em class="replaceable"><code>arg</code></em>...]</p></div></span></dt><dd><p>
Configuration command. See <a href="user-configure.html" title="Chapter 23. Automatic Configuration">Chapter 23, <i>Automatic Configuration</i></a>.
</p></dd><dt><a name="cmd-copy"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:copy</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>from</code></em>... <em class="replaceable"><code>to</code></em> </p></div></span></dt><dd><p>
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:
</p><pre class="programlisting">
: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
</pre><p>
Note that "ftp://machine/path" uses "path" relative to
the login directory, while "ftp://machine//path" uses
"/path" absolutely.
</p><p>
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:
</p><pre class="programlisting">
:copy {recursive} foo bar
</pre><p>
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:
</p><pre class="programlisting">
:copy {recursive} foo/* bar
</pre><p>
</p><div class="informaltable"><table border="0"><colgroup><col width="150"><col></colgroup><thead><tr><th>options</th><td class="auto-generated"> </td></tr></thead><tbody><tr><td>{c} {continue}</td><td>when an item with a wildcard does not have matches continue
with the next item</td></tr><tr><td>{e} {exist} {exists}</td><td>don't overwrite an existing file or directory</td></tr><tr><td>{f} {force}</td><td>forcefully overwrite an existing file or dir (default)</td></tr><tr><td>{i} {interactive}</td><td>before overwriting a local file, prompt for confirmation
(currently doesn't work for remote files)</td></tr><tr><td>{k} {keepdir}</td><td>keep the directory of the source file if the target is a
directory; the targetfile name is the target directory with the
source file name appended</td></tr><tr><td>{m} {mkdir}</td><td>create destination directory when needed</td></tr><tr><td>{p} {preserve}</td><td>preserve file permissions and timestamps as much as
possible</td></tr><tr><td>{q} {quiet}</td><td>don't report copied files</td></tr><tr><td>{r} {recursive}</td><td>recursive, copy a directory tree. "to" is created and should
not exist yet.</td></tr><tr><td>{u} {unlink}</td><td>when used with {recursive}, don't copy a symlink, make a copy
of the file or dir it links to</td></tr></tbody></table></div><p>
</p><p>
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).
</p><p>
When (after expanding wildcards) there is more than
one "from" item, the "to" item must be a directory.
</p><p>
For "to" only local files, ftp://, rcp://, rsync://
and scp:// can be used. See "URLs" for info on
forming URLs.
</p><p>
Attributes for "from" and "to" are currently ignored.
</p></dd><dt><a name="cmd-del"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:del</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>file</code></em>... <br><code class="command">:delete</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>file</code></em>... </p></div></span></dt><dd><p>
Delete files and/or directories.
</p><p>
</p><div class="informaltable"><table border="0"><colgroup><col width="150"><col></colgroup><thead><tr><th>options</th><td class="auto-generated"> </td></tr></thead><tbody><tr><td>{f} {force}</td><td>don't fail when a file doesn't exist</td></tr><tr><td>{r} {recursive}</td><td>delete directories and their contents recursively.</td></tr><tr><td>{q} {quiet}</td><td>don't report deleted files</td></tr></tbody></table></div><p>
</p><p>
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).
</p><p>
When deleting a symbolic link, the link itself is deleted, not the
file or directory it refers to.
</p><p>
CAREFUL: if you make a mistake in the argument,
anything might be deleted. For example, accidentally
inserting a space before a wildcard:
</p><pre class="programlisting">
:del {r} dir/temp *
</pre><p>
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.
</p></dd><dt><a name="cmd-deldir"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:deldir</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>dir</code></em>... </p></div></span></dt><dd><p>
Delete a directory. Fails when the directory is not empty.
</p><p>
</p><div class="informaltable"><table border="0"><colgroup><col width="150"><col></colgroup><thead><tr><th>options</th><td class="auto-generated"> </td></tr></thead><tbody><tr><td>{c} {continue}</td><td>when an item with a wildcard does not have matches
continue with the next item</td></tr><tr><td>{f} {force}</td><td>don't fail when a directory doesn't exist; still fails when it exists but is not a directory or could not be deleted</td></tr><tr><td>{q} {quiet}</td><td>don't report deleted directories</td></tr></tbody></table></div><p>
</p></dd><dt><a name="cmd-delrule"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:delrule</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>tpat</code></em>... <em class="replaceable"><code>spat</code></em>... </p></div></span></dt><dd><p>
Delete an existing rule. Can be used when one of the
default rules would be used when this is not wanted.
</p><p>
</p><div class="informaltable"><table border="0"><colgroup><col width="150"><col></colgroup><thead><tr><th>options</th><td class="auto-generated"> </td></tr></thead><tbody><tr><td>{q} {quiet}</td><td>don't complain when there is no matching rule</td></tr></tbody></table></div><p>
</p><p>
Also see <a href="ref-commands.html#cmd-clearrules">:clearrules</a>.
</p></dd><dt><a name="cmd-dll"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:dll</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>target</code></em> : [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...] <em class="replaceable"><code>source</code></em>... </p></div></span></dt><dd><p>
Specify that "target" is a shared (dynamic) library,
build from "source". Dependencies will be added to
compile "source" into an object file and combine the
object files together into "target".
</p><p>
When the basename of "target" does not contain a dot,
$DLLPRE will be prepended and $DLLSUF will be
appended. The original name becomes an alias name for
the target, so that this works:
</p><pre class="programlisting">
all: foo bar
:dll foo : foo.c
:dll bar : bar.c
</pre><p>
On Unix this builds libfoo.so and libbar.so.
</p><p>
See <a href="ref-commands.html#cmd-produce">:produce</a> for the most important
options.
The default values used for ":dll" are:
$DLLSUF for "targetsuffix", $DLLPRE for "targetprefix"
$DLLOBJSUF for "objectsuffix", "dllobject" for "objecttype",
"INSTALL_DLL" for "installvar" and "builddll" for "buildaction".
</p><p>
In addition, the "{onestep}" option explained for
<a href="ref-commands.html#cmd-program">:command</a> can be used.
</p><p>
"{attr = val}" is an optional attribute that apply to the generated
dependencies. Use the "scope" attribute to
specify a user scope to be used before other scopes
(except the local scope) in the generated
dependencies.
</p><p>
The target will be added to $INSTALL_DLL. Use the "installvar"
option to select another variable name. Use {installvar=} when
installing the target is not wanted.
The target and intermediate files will be added to
$CLEANFILES. The source files will be added to
$DISTFILES, except the ones with a {nodist} attribute.
</p><p>
Can only be used at the recipe level.
</p></dd><dt><a name="cmd-do"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:do</code> <em class="replaceable"><code>action</code></em> [<em class="replaceable"><code>fname</code></em>...]</p></div></span></dt><dd><p>
Execute an action.
The commands executed may depend on the types of the first input file
and/or the output file.
See <a href="user-filetype.html" title="Chapter 28. Customizing Filetype Detection and Actions">Chapter 28, <i>Customizing Filetype Detection and Actions</i></a>.
</p><p>
Attributes just after the "action", except the options mentioned
below, are passed as variables to the build commands. The name of the
attribute is used as the name of the variable. Prepending "var_" is
optional.
</p><pre class="programlisting">
:do build {target = prog} foo.c
</pre><p>
</p><div class="informaltable"><table border="0"><colgroup><col width="150"><col></colgroup><thead><tr><th>options</th><td class="auto-generated"> </td></tr></thead><tbody><tr><td>{filetype}</td><td><p>
The "filetype" attribute can be used to override the output filetype
used to select the action to be executed. Example:
</p><pre class="programlisting">
:do build {filetype = libtoolexe} $Objects
</pre><p>
When this option is not used the filetype of the target is used. The
filetype of source files must be given with the source file.
</p></td></tr><tr><td>{scope}</td><td><p>
The "scope" attribute has a special meaning: define the user scope
from which variables are obtained first. Variables in this scope
overrule variables in the recipe or other scopes. Only variables in
the local scope come first.
</p><pre class="programlisting">
s_opti.DEFINE = -DFOOBAR
...
:do build {scope = s_opti} foo.c
</pre><p>
</p></td></tr><tr><td>{remove}</td><td><p>The "remove" attribute can be used to delete all the arguments
after the action was executed. This also happens when the action
failed. This can be used when the argument is a temporary file.
Example:
</p><pre class="programlisting">
tmp = `tempfname()`
:print >tmp Buy more Spam!
:do email {remove} {to = everybody@world.org} {subject = Spam} tmp
</pre><p>
</p></td></tr></tbody></table></div><p>
See <a href="ref-commands.html#cmd-action">:action</a> for defining actions.
</p></dd><dt><a name="cmd-eval"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:eval</code> [<em class="replaceable"><code>redir</code></em>] <em class="replaceable"><code>python-expression</code></em> </p></div></span></dt><dd><p>
Filter stdin using a Python expression.
See <a href="ref-commands.html#arg-redir">here</a> for [redir].
When not used after "|" evaluate the Python
expression.
</p><p>
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
<a href="ref-commands.html#cmd-eval">:eval</a>
is used after "|".
</p><p>
See <a href="ref-python.html#python-var2string">var2string()</a> for information
about using <span class="application">Aap</span> variables in the Python expression.
</p><p>
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:
</p><pre class="programlisting">
:print $foo | :eval re.sub('<.*?>', '', stdin) > tt
:eval os.name | :assign OSNAME
</pre><p>
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.
</p></dd><dt><a name="cmd-execute"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:execute</code> [<em class="replaceable"><code>{pass}</code></em>] <em class="replaceable"><code>name</code></em> [<em class="replaceable"><code>argument</code></em>...]</p></div></span></dt><dd><p>
Execute recipe "name" right away. This works like
executing aap on "name".
</p><p>
The recipe is executed in a new scope. This is used
as the toplevel scope, unless the "{pass}" option is
used.
</p><p>
The "fetch" attribute is supported like with
<a href="ref-commands.html#cmd-include">:include</a>.
</p><p>
Optional arguments may be given, like on the command
line. This is useful for specifying targets and
variable values. "-f recipe" is ignored.
Example:
</p><pre class="programlisting">
TESTPROG = ./myprog
:execute test.aap test1 test2
</pre><p>
The following command line options are also used for the executed
recipe. Thus when <span class="application">Aap</span> was started with the --nobuild argument, this
will also be applied to recipes executed with :execute. All other
command line arguments are not passed on.
</p><div class="informaltable"><table border="0"><colgroup><col></colgroup><tbody><tr><td>-C --contents</td></tr><tr><td>-k --continue</td></tr><tr><td>-F --force</td></tr><tr><td>-n --nobuild</td></tr><tr><td>-a --nocache</td></tr><tr><td>-N --nofetch-recipe</td></tr><tr><td>-s --silent</td></tr><tr><td>-S --stop</td></tr><tr><td>-t --touch</td></tr><tr><td>-v --verbose</td></tr></tbody></table></div><p>
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:
</p><pre class="programlisting">
@if not program_path("mytool"):
:execute mytool.aap install
:sys mytool
</pre><p>
See the <a href="ref-python.html#python-program-path">program_path()</a>
function.
</p><p>
Another example: build two variants:
</p><p>
</p><pre class="programlisting">
:execute build.aap GUI=motif
:execute build.aap GUI=gtk
</pre><p>
</p></dd><dt><a name="cmd-exit"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:exit</code> [<em class="replaceable"><code>exitval</code></em>]</p></div></span></dt><dd><p>
Quit executing recipes. When used in build commands, the "finally"
targets will still be executed. But a
<a href="ref-commands.html#cmd-quit">:quit</a>
or
<a href="ref-commands.html#cmd-exit">:exit</a> in the
commands of a "finally" target will quit further execution.
</p><p>
When "exitval" is given Aap will use it as the exit value of the
program.
</p></dd><dt><a name="cmd-fetch"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:fetch</code> [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...] <em class="replaceable"><code>file</code></em>... </p></div></span></dt><dd><p>
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.
</p><p>
An attribute that appears before the files it is applied to all files.
</p><p>
Files that exist and have a "fetch" attribute with
value "no" are skipped.
</p><p>
The name "." can be used to update the current
directory:
</p><pre class="programlisting">
:fetch . {fetch = cvs://$CVSROOT}
</pre><p>
The "{usecache}" attribute can be used to use a cached
version of the file. This skips downloading when the
file was downloaded before, but may use an older
version of the file.
</p><p>
"{nocache}" does the opposite: never use a cached
file.
</p><p>
The "{constant}" attribute can be used to skip
fetching a file that already exists. This is useful
for a file that will never change (when it includes a
version number). Implies "{usecache}".
</p></dd><dt><a name="cmd-fetchall"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:fetchall</code> [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...]</p></div></span></dt><dd><p>
Fetch all the files in the recipe (and child recipes) that
have the "fetch" attribute.
</p><p>
Extra attributes for fetching can be specified here, they
overrule the attributes of the file itself.
</p></dd><dt><a name="cmd-filetype"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:filetype</code> [<em class="replaceable"><code>argument</code></em>...]</p></div></span></dt><dd><p>
Specify filetype detection. See <a href="user-filetype.html" title="Chapter 28. Customizing Filetype Detection and Actions">Chapter 28, <i>Customizing Filetype Detection and Actions</i></a>.
</p></dd><dt><a name="cmd-import"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:import</code> <em class="replaceable"><code>name</code></em> </p></div></span></dt><dd><p>
Read a module stored in the main <span class="application">Aap</span> directory or elsewhere.
This happens in a special scope, does not change
directory, and has no effect on the recipe
containing the <code class="computeroutput">:import</code>
command <span class="emphasis"><em>except</em></span>
that the actions, filetypes and routes
defined in the module become available globally.
This is the easiest way to add additional language
support to <span class="application">Aap</span>. See <a href="user-language.html" title="Chapter 31. Adding A Language Module">Chapter 31, <i>Adding A Language Module</i></a>.
</p><p>
The recipe(s) read have the name of the module with ".aap" appended.
Thus for ":import java" the "java.aap" recipe is used.
</p><p>
The directories searched for module recipes depend on the platform.
The first module that is found is used, further directories are not
searched.
For Unix systems three directories are used:
</p><table class="simplelist" border="0" summary="Simple list"><tr><td> - <code class="filename">~/.aap/modules/</code></td></tr><tr><td> - <code class="filename">/usr/local/share/aap/modules/</code> </td></tr><tr><td> - The <code class="filename">modules</code> directory of the <span class="application">Aap</span> installation</td></tr></table><p>
For other systems these directories are used:
</p><table class="simplelist" border="0" summary="Simple list"><tr><td> - <code class="filename">$HOME/aap/modules/</code> </td></tr><tr><td> - <code class="filename">$HOMEDRIVE/$HOMEPATH/aap/modules/</code></td></tr><tr><td> - <code class="filename">c:/aap/modules/</code></td></tr><tr><td> - The <code class="filename">modules</code> directory of the <span class="application">Aap</span> installation</td></tr></table><p>
$HOME, $HOMEDRIVE and $HOMEPATH are environment variables, not <span class="application">Aap</span>
variables.
</p><p>
Additionally, recipes in the "modules2" subdirectory are loaded.
This can be used to do additional settings without modifying a
distributed module.
All found recipes are loaded, ignoring wether a recipe was already
found. The same list of directories is used as mentioned above, with
"modules" replaced with "modules2". Although there is no "modules2"
directory in the distribution, thus the last item in the directory
lists above is not used.
</p><p>
The scope that is used for the module recipe can be accessed from
elsewhere under the name of the module with "m_" prepended. Thus when
doing ":import java" the "m_java" scope is available. The recipes
from the "modules2" directory use this same scope.
</p></dd><dt><a name="cmd-include"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:include</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>name</code></em> </p></div></span></dt><dd><p>
Read recipe "name" as if it was included in the current recipe. Does
not change directory and file names in the included recipe are
considered to be relative to the current recipe, not the included
recipe.
</p><p>
The <a href="ref-arguments.html#option-include">-I</a> or
<a href="ref-arguments.html#option-include">--include</a> command line argument
can be used to specify directories to look for the recipe.
The current directory is always searched first.
When the recipe name is an absolute path or starts with a dot (e.g.,
"./foo.aap") only the current directory is used.
</p><p>
The "fetch" attribute can be used to specify a list of locations where
the recipe can be fetched from. If the recipe is fetched, it is
stored under the specified "name" in the current directory.
</p><div class="informaltable"><table border="0"><colgroup><col width="150"><col></colgroup><thead><tr><th>options</th><td class="auto-generated"> </td></tr></thead><tbody><tr><td>{q} {quiet}</td><td>Don't give a warning for a file that can't be read.
Used to optionally include a recipe.</td></tr><tr><td>{o} {once}</td><td>Don't include the recipe if it was already read.
Useful for project settings that are only to be included once,
while you have sub-projects that can be build
independendly.</td></tr></tbody></table></div></dd><dt><a name="cmd-installpkg"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:installpkg</code> <em class="replaceable"><code>package</code></em>... </p></div></span></dt><dd><p>
Install packages. Each argument is the name of a package.
This works like <a href="ref-commands.html#cmd-assertpkg">:assertpkg</a> but
without checking if the package is already present or asking the user
whether it should be installed.
</p><p>
See <a href="user-package.html" title="Chapter 25. Automatic Package Install">Chapter 25, <i>Automatic Package Install</i></a> about using packages.
</p></dd><dt><a name="cmd-lib"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:lib</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>target</code></em> : [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...] <em class="replaceable"><code>source</code></em>... </p></div></span></dt><dd><p>
Specify that "target" is a static library, build from
"source". Dependencies will be added to compile
"source" into an object file and combine the object
files together into "target".
</p><p>
When the basename of "target" does not contain a dot,
$LIBPRE will be prepended and $LIBSUF will be
appended. The original name becomes an alias name for
the target, so that this works:
</p><pre class="programlisting">
all: foo bar
:lib foo : foo.c
:lib bar : bar.c
</pre><p>
On Unix this builds libfoo.a and libbar.a.
</p><p>
See <a href="ref-commands.html#cmd-produce">:produce</a> for the most important
options.
The default values used for ":lib" are:
$LIBSUF for "targetsuffix", $LIBPRE for "targetprefix"
$LIBOBJSUF for "objectsuffix", "libobject" for "objecttype",
"INSTALL_LIB" for "installvar" and "buildlib" for "buildaction".
</p><p>
In addition, the "{onestep}" option explained for
<a href="ref-commands.html#cmd-program">:command</a> can be used.
</p><p>
"{attr = val}" is an optional attribute that apply to the generated
dependencies. Use the "scope" attribute to
specify a user scope to be used before other scopes
(except the local scope) in the generated
dependencies.
</p><p>
The target will be added to $INSTALL_LIB. Use the "installvar"
option to select another variable name. Use {installvar=} when
installing the target is not wanted.
The target and intermediate files will be added to
$CLEANFILES. The source files will be added to
$DISTFILES.
</p><p>
Can only be used at the recipe level.
</p></dd><dt><a name="cmd-log"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:log</code> [<em class="replaceable"><code>text</code></em>...]</p></div></span></dt><dd><p>
Write the arguments to the log file AAPDIR/log.
This is like <a href="ref-commands.html#cmd-print">:print</a>, but the text is
not echoed.
The output cannot be redirected or piped, since there isn't any.
</p></dd><dt><a name="cmd-ltlib"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:ltlib</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>target</code></em> : [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...] <em class="replaceable"><code>source</code></em>... </p></div></span></dt><dd><p>
Specify that "target" is a library, build from
"source" with the libtool program. Dependencies will be added to
compile each "source" into an object file and combine the object
files together into "target".
</p><p>
Very similar to <a href="ref-commands.html#cmd-lib">:lib</a>.
</p><p>
Using libtool requires importing the libtool module. Since
<a href="ref-commands.html#cmd-ltlib">:ltlib</a> will not work without it, the
libtool module is automatically imported.
</p><p>
See <a href="ref-commands.html#cmd-produce">:produce</a> for the options.
The default values used for ":ltlib" are:
$LTLIBSUF for "targetsuffix", $LTLIBPRE for "targetprefix"
$LTOBJSUF for "objectsuffix", "ltobject" for "objecttype",
"INSTALL_LTLIB" for "installvar" and "buildltlib" for "buildaction".
</p><p>
The target will be added to $INSTALL_LTLIB. Use the "installvar"
option to select another variable name. Use {installvar=} when
installing the target is not wanted.
The target and intermediate files will be added to
$CLEANFILES. The source files will be added to $DISTFILES.
</p><p>
Can only be used at the recipe level.
</p></dd><dt><a name="cmd-mkdir"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:mkdir</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>dir</code></em>... </p></div></span></dt><dd><p>
Create directory. This fails when "dir" already
exists and is not a directory.
</p><p>
Each argument is handled separately (they are not
concatenated like with <a href="ref-commands.html#cmd-cd">:cd</a>!).
A "mode" attribute on a directory can be used to
specify the protection flags for the new directory.
</p><p>
Example:
</p><pre class="programlisting">
:mkdir {r} ~/secret/dir {mode = 0700}
</pre><p>
The default mode is 0644. The effective umask may
reset some of the bits though.
</p><p>
</p><div class="informaltable"><table border="0"><colgroup><col width="150"><col></colgroup><thead><tr><th>options</th><td class="auto-generated"> </td></tr></thead><tbody><tr><td>{f} {force}</td><td>Don't fail when a directory already exist; still fails when it
is not a directory or could not be created.</td></tr><tr><td>{q} {quiet}</td><td>don't report created directories.</td></tr><tr><td>{r} {recursive}</td><td>Also create intermediate directories, not just the deepest
one.</td></tr></tbody></table></div><p>
</p><p>
Note: automatic creation of directories can be done by
adding the {directory} attribute to a source item.
</p></dd><dt><a name="cmd-mkdownload"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:mkdownload</code> <em class="replaceable"><code>name</code></em> <em class="replaceable"><code>file</code></em>... </p></div></span></dt><dd><p>
Generate a recipe "name" that downloads the specified
files. Each file must have a "fetch" attribute, which
is used in the generated recipe.
</p><p>
When the file "name" already exists it is overwritten
without warning.
</p><p>
Wildcards in "file ..." are expanded. Not in "name".
</p><p>
MD5 checksums are generated and used in the recipe to
fetch a file only when the checksum differs. Example
of one item:
</p><pre class="programlisting">
file = foobar.txt
@if get_md5(file) != "a5dba5bce69918c040703e9b8eb35f1d":
:fetch {fetch = ftp://foo.org/files/%file%} $file
</pre><p>
When there is a "fetch" attribute on "name", this will
be used to add a
<a href="ref-commands.html#cmd-recipe">:recipe</a> command at the start of the
generated recipe.
</p></dd><dt><a name="cmd-move"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:move</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>from</code></em>... <em class="replaceable"><code>to</code></em> </p></div></span></dt><dd><p>
Move files or directories. Mostly like
<a href="ref-commands.html#cmd-copy">:copy</a>,
except that the "from" files/directories are renamed
or, when renaming isn't possible, copied and deleted.
</p><p>
</p><div class="informaltable"><table border="0"><colgroup><col width="150"><col></colgroup><thead><tr><th>options</th><td class="auto-generated"> </td></tr></thead><tbody><tr><td>{c} {continue}</td><td>when an item with a wildcard does not have matches
continue with the next item</td></tr><tr><td>{e} {exist} {exists}</td><td>don't overwrite an existing file or directory</td></tr><tr><td>{i} {interactive}</td><td>before overwriting a local file, prompt for confirmation
(currently doesn't work for remote files)</td></tr><tr><td>{m} {mkdir}</td><td>create destination directory when needed</td></tr><tr><td>{q} {quiet}</td><td>don't report moved files</td></tr></tbody></table></div><p>
</p></dd><dt><a name="cmd-pass"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:pass</code> </p></div></span></dt><dd><p>
Do nothing. Useful to define a target with build commands to avoid a
dependency is added automatically.
</p><pre class="programlisting">
clean:
:pass
</pre></dd><dt><a name="cmd-popdir"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:popdir</code> </p></div></span></dt><dd><p>
Change back to directory on top of the directory stack, undoing a
previous
<a href="ref-commands.html#cmd-pushdir">:pushdir</a>. It is an error if the
directory stack is empty (more :popdir than :pushdir used).
</p></dd><dt><a name="cmd-print"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:print</code> [<em class="replaceable"><code>redir</code></em>] [<em class="replaceable"><code>text</code></em>...]</p></div></span></dt><dd><p>
Print the arguments on stdout.
Without arguments a line feed is produced.
$var items are expanded, otherwise the arguments are produced
literally, including quotes:
</p><pre class="programlisting">
:print "hello"
</pre><p>
results in:
</p><div class="literallayout"><p> "hello" </p></div><p>
Leading white space is skipped, but white space in
between arguments is kept. To produce leading white
space write the first space as an escaped character:
</p><pre class="programlisting">
:print $( ) indented text
</pre><p>
results in:
</p><div class="literallayout"><p> indented text </p></div><p>
When used in a pipe the <code class="literal">stdin</code> variable holds
the input.
</p><p>
See <a href="ref-commands.html#arg-redir">here</a> for [redir].
See <a href="ref-commands.html#cmd-log">:log</a> for writing a message to the
log file without echoing.
</p></dd><dt><a name="cmd-produce"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:produce</code> <em class="replaceable"><code>what</code></em> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>target</code></em> : [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...] <em class="replaceable"><code>source</code></em>... </p></div></span></dt><dd><p>
Specify that "target" has filetype "what" and is build from "source
...".
Aap will add dependencies to invoke the actions that will accomplish
the task of building "target".
</p><p>
For specific types of targets separate commands are available. You
don't need to specify the mandatory options then.
For building a normal program use
<a href="ref-commands.html#cmd-program">:program</a>, for building a shared
library use
<a href="ref-commands.html#cmd-dll">:dll</a>, for building a static library use
<a href="ref-commands.html#cmd-lib">:lib</a>, for building a libtool library use
<a href="ref-commands.html#cmd-ltlib">:ltlib</a>.
</p><p>
The building is split up in two parts:
</p><div class="orderedlist"><ol type="1"><li><p>
Dependencies are
added to compile the source files into files specified with the
"objecttype" option. The routes specified with
<a href="ref-commands.html#cmd-route">:route</a> are used to decide which
actions to invoke.
These <a href="ref-commands.html#cmd-route">:route</a> commands must
precede the <a href="ref-commands.html#cmd-produce">:produce</a> command!
Each step in the route becomes a separate
dependency, so that intermediate results are produced.
This is similar to what the
<a href="ref-commands.html#cmd-totype">:totype</a> command does.
</p></li><li><p>
The second step is to build the "target" from the "objecttype"
files. This invokes the action defined with "buildaction",
using "what" as the target filetype. The "what" filetype is
declared when necessary, to avoid a warning for defining an
action for an unknown filetype.
</p></li></ol></div><p>
</p><p>
When the basename of "target" does not contain a dot,
the "targetsuffix" option will be appended and "targetprefix"
prepended. The original name becomes an alias name for the target, so
that this works:
</p><pre class="programlisting">
all: foo bar
:produce drink $drinkoptions foo : foo.c
:produce snack $snackoptions bar : bar.c
</pre><p>
</p><div class="informaltable"><table border="0"><colgroup><col width="150"><col></colgroup><thead><tr><th>options</th><td class="auto-generated"> </td></tr></thead><tbody><tr><td>targetsuffix</td><td>(optional) appended to the target if it doesn't contain
a dot</td></tr><tr><td>targetprefix</td><td>(optional) prepended to the target if it doesn't
contain a dot</td></tr><tr><td>comment</td><td>(optional) description of type of building displayed for
"aap --comment target". A "comment" attribute on the
target overrules this.</td></tr><tr><td>objectprefix</td><td>(optional) prefix for the intermediate results.</td></tr><tr><td>objectsuffix</td><td>(optional) suffix for the intermediate results.</td></tr><tr><td>objecttype</td><td>(mandatory) filetype for the intermediate results.</td></tr><tr><td>installvar</td><td>(optional) name of the install variable to add the
target to (default: INSTALL_EXEC) Set to an empty value to
omit installing</td></tr><tr><td>buildaction</td><td>(mandatory) name of the action used to turn the
intermediate results into the target</td></tr></tbody></table></div><p>
</p><p>
Can only be used at the recipe level.
</p></dd><dt><a name="cmd-program"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:program</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>target</code></em> : [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...] <em class="replaceable"><code>source</code></em>... </p></div></span></dt><dd><p>
Specify that "target" is a program, build from
"source ...". Dependencies will be added to compile
"source ..." into an object file and link the object
files together into "target".
</p><p>
When the basename of "target" does not contain a dot,
$EXESUF will be appended. The original name becomes
an alias name for the target, so that this works:
</p><pre class="programlisting">
all: foo bar
:program foo : foo.c
:program bar : bar.c
</pre><p>
On MS-Windows this builds foo.exe and bar.exe.
</p><p>
See <a href="ref-commands.html#cmd-produce">:produce</a> for the most important
options.
The default values used for ":program" are:
$EXESUF for "targetsuffix", nothing for "targetprefix"
$OBJSUF for "objectsuffix", "object" for "objecttype", "INSTALL_EXEC"
for "installvar" and "build" for "buildaction".
</p><p>
In addition, "{onestep}" can be used to make A-A-P build the program
without creating intermediate object files if it is supported by the
tools (see <a href="ref-tools.html" title="Chapter 40. Standard Tools">Chapter 40, <i>Standard Tools</i></a>). This solution might be faster
for very fast compilers.
</p><p>
"{attr = val}" is an optional attribute that apply to the generated
dependencies. Use the "scope" attribute to specify a user scope to be
used before other scopes, but after the local scope, in the generated
dependencies.
</p><p>
The target will be added to $INSTALL_EXEC. Use the "installvar"
option to select another variable name. Use {installvar=} when
installing the target is not wanted.
The target and intermediate files will be added to
$_recipe.CLEANFILES. The source files will be added
to $_recipe.DISTFILES, except the ones with a {nodist}
attribute.
</p><p>
Can only be used at the recipe level.
</p></dd><dt><a name="cmd-progsearch"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:progsearch</code> <em class="replaceable"><code>varname</code></em> <em class="replaceable"><code>progname</code></em>... </p></div></span></dt><dd><p>
Check if an executable <code class="literal">progname</code> exists in $PATH.
If not, check further arguments. The first one found is assigned to
variable <code class="literal">varname</code>. If none of the
<code class="literal">progname</code> could be found <code class="literal">varname</code>
will be set to an empty string.
</p><p>
Example:
</p><pre class="programlisting">
:progsearch BROWSER netscape opera
@if BROWSER:
:sys $BROWSER readme.html
</pre><p>
</p></dd><dt><a name="cmd-proxy"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:proxy</code> [<em class="replaceable"><code>protocol</code></em>] <em class="replaceable"><code>address</code></em> </p></div></span></dt><dd><p>
Specify a proxy server. Examples:
</p><pre class="programlisting">
:proxy ftp ftp://ftp.proxy.net:1234
:proxy http://www.someproxy.com:1080
</pre><p>
The "protocol" can be "ftp", "http" or "gopher". When
omitted "http" is used. Case doesn't matter.
</p><p>
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.
</p></dd><dt><a name="cmd-publish"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:publish</code> [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...] <em class="replaceable"><code>file</code></em>... </p></div></span></dt><dd><p>
Publish the files mentioned according to their
"publish" or "commit" attribute.
</p><p>
Creates directories when needed (for CVS only one level).
</p></dd><dt><a name="cmd-publishall"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:publishall</code> [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...]</p></div></span></dt><dd><p>
Publish all the files in the recipe (and child recipes) that
have the "publish" attribute and changed since the last time
they were published.
</p><p>
Note that this doesn't fall back to the "commit" attribute
like
<a href="ref-commands.html#cmd-publish">:publish</a> does.
</p></dd><dt><a name="cmd-pushdir"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:pushdir</code> <em class="replaceable"><code>dir</code></em> </p></div></span></dt><dd><p>
Change directory to "dir". The current directory is pushed onto the
directory stack, so that
<a href="ref-commands.html#cmd-popdir">:popdir</a> goes back to the old current
directory.
</p><p>
Note that at the start of each command block <span class="application">Aap</span>
changes directory to the directory of the recipe.
</p><p>
WARNING: variables with a relative path become
invalid! This includes $source and $target. Use
<a href="ref-python.html#python-var-abspath">var_abspath()</a>.
when needed.
</p></dd><dt><a name="cmd-python"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:python</code> <br><code class="command"> </code> <em class="replaceable"><code>python-command-block</code></em> </p></div></span></dt><dd><p>
A block of Python code. The block ends when the indent drops to the
level of
<a href="ref-commands.html#cmd-python">:python</a> or below.
</p></dd><dt><a name="cmd-python-term"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:python</code> <em class="replaceable"><code>terminator</code></em> <br><code class="command"> </code> <em class="replaceable"><code>python-command-block</code></em> <br><code class="command"> </code> <em class="replaceable"><code>terminator</code></em> </p></div></span></dt><dd><p>
A block of Python code. The block ends when "terminator" is found on
a line by itself. The Python commands may have any indent.
</p><p>
White space before and after "terminator" is allowod and a comment
after "terminator" is also allowed. "terminator" can contain any
characters except white space.
</p></dd><dt><a name="cmd-quit"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:quit</code> [<em class="replaceable"><code>exitval</code></em>]</p></div></span></dt><dd><p>
See <a href="ref-commands.html#cmd-exit">:exit</a>.
</p></dd><dt><a name="cmd-recipe"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:recipe</code> {fetch = <em class="replaceable"><code>URL</code></em>... } </p></div></span></dt><dd><p>
Location of this recipe. The "fetch" attribute is
used like with
<a href="ref-commands.html#cmd-child">:child</a>: a list of locations. The
first URL that works is used.
</p><p>
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
<a href="ref-commands.html#cmd-recipe">:recipe</a> 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.
</p><p>
Fetching a specific recipe is done only once per session.
</p></dd><dt><a name="cmd-remove"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:remove</code> [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...] <em class="replaceable"><code>fname</code></em>... </p></div></span></dt><dd><p>
Version control command, also see <a href="user-version.html" title="Chapter 18. Version Control">Chapter 18, <i>Version Control</i></a>.
</p><p>
Remove the files from the repository.
The file may still exist locally.
Implies a "commit" of the file.
</p></dd><dt><a name="cmd-removeall"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:removeall</code> [<em class="replaceable"><code>option</code></em>...] [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...] [<em class="replaceable"><code>directory</code></em>...]</p></div></span></dt><dd><p>
Version control command, also see <a href="user-version.html" title="Chapter 18. Version Control">Chapter 18, <i>Version Control</i></a>.
</p><p>
Apply the <code class="literal">:remove</code> command to all files in the directory that
exist in the repository but do hot have been given a "commit" attribute
in the recipe (and child recipes).
</p><p>
Careful: Only use this command when it is certain that all
files that should be in the VCS are explicitly mentioned and
do have a "commit" attribute!
</p><p>
</p><div class="informaltable"><table border="0"><colgroup><col width="150"><col></colgroup><thead><tr><th>options</th><td class="auto-generated"> </td></tr></thead><tbody><tr><td>{l} {local}</td><td>don't do current directory recursively</td></tr><tr><td>{r} {recursive}</td><td>do handle arguments recursively</td></tr></tbody></table></div><p>
</p><p>
When no directory argument is given, the current directory is
used. It is inspected recursively, unless the "{local}"
option was given.
</p><p>
When directory arguments are given, each directory is
inspected. Recursively when the "{recursive}" option was
given.
</p><p>
When no "commit" attribute is specified here, it will be
obtained from any node.
</p></dd><dt><a name="cmd-reviseall"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:reviseall</code> [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...]</p></div></span></dt><dd><p>
Version control command, also see <a href="user-version.html" title="Chapter 18. Version Control">Chapter 18, <i>Version Control</i></a>.
</p><p>
Just like using both <code class="literal">:checkinall</code> and
<code class="literal">:removeall</code> on the current directory recursively.
</p></dd><dt><a name="cmd-route"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:route</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>typelist</code></em>... <em class="replaceable"><code>typelist</code></em> [<em class="replaceable"><code>{attr = value}</code></em>...]<br><code class="command"> </code> <em class="replaceable"><code>action</code></em> <em class="replaceable"><code>filename</code></em> <br><code class="command"> </code> ... <br><code class="command"> </code> <em class="replaceable"><code>action</code></em> </p></div></span></dt><dd><p>
Specify the actions to be used to build sources with
a filetype in the first "typelist" into targets with a
filetype in the last "typelist". One or more steps
can be defined, resulting in intermediate results.
</p><p>
Each "typelist" is usually a single filetype name, but
the first and the last can also be a comma separated
list of filetype names. The route is defined for each
combination of the mentioned filetypes.
</p><p>
The last "typelist" may have attributes. These are passed to the final
target. A useful attribute is "buildaction", which tells the build
action which special action has to be used for this item.
</p><p>
There must be an "action" line for each step. The
number of steps is the number of "typelist" minus one.
All "action" lines except the last one must define a
"filename". This is the file used for the
result of the action, which becomes the input for the next action.
If the filename is not an absolute path $BDIR will be prepended (the
"var_BDIR" attribute is used if present on the source file).
</p><p>
Example:
</p><pre class="programlisting">
:route yacc c object
yacc $(source).c
compile
</pre><p>
</p><p>
This defines the route from a "yacc" file to an
"object" file, with an intermediate "c" result.
The step from "yacc" to "c" is done with an action
called "yacc". It will be invoked like this:
</p><pre class="programlisting">
:do yacc {target = $(source).c} $source
</pre><p>
The step from "c" to "object" is done with a "compile"
action. It will be invoked like this:
</p><pre class="programlisting">
:do compile {target = $target} $(source).c
</pre><p>
The steps will be generated as separate dependencies.
Thus, for the above example,
when an included header file of the intermediate C file
changes, only the "compile" action will be invoked.
</p><p>
</p><div class="informaltable"><table border="0"><colgroup><col width="150"><col></colgroup><thead><tr><th>options</th><td class="auto-generated"> </td></tr></thead><tbody><tr><td>{default}</td><td>This is a default route. No warning is given if the
route is redefined later.</td></tr></tbody></table></div><p>
</p><p>
The defined routes can be used explicitly with the
<a href="ref-commands.html#cmd-totype">:totype</a> command. They are also used
with the <a href="ref-commands.html#cmd-produce">:produce</a> command and
derivatives.
</p><p>
Note: In a later version of <span class="application">Aap</span> the defined routes may be used for
dependencies without build commands and without a matching rule.
Thus the routes may be used as rules based on filetypes.
</p></dd><dt><a name="cmd-rule"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:rule</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>tpat</code></em>... : [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...] <em class="replaceable"><code>spat</code></em>... <br><code class="command"> </code> <em class="replaceable"><code>command-block</code></em> </p></div></span></dt><dd><p>
Define a rule to build files matching the pattern
"tpat" from a file matching "spat".
</p><p>
Example:
</p><pre class="programlisting">
:rule %.html : header.part %.part footer.part
:cat $source > $target
</pre><p>
</p><p>
There can be several "tpat" patterns, the rule is used
if one of them matches.
</p><p>
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".
</p><p>
Can only be used at the recipe level.
</p><p>
A rule is used in the recipe where it is defined and
in its siblings, unless an option is used to specify
otherwise.
</p><p>
</p><div class="informaltable"><table border="0"><colgroup><col width="150"><col></colgroup><thead><tr><th>options</th><td class="auto-generated"> </td></tr></thead><tbody><tr><td>{global}</td><td>use this rule in all places</td></tr><tr><td>{local}</td><td>use this rule only for targets in this recipe</td></tr><tr><td>{default}</td><td>default rule, redefining it will not cause a
message</td></tr><tr><td>{sourceexists}</td><td>only use the rule when the matching source file exists;
useful for rules that generate source code</td></tr></tbody></table></div><p>
</p><p>
"attributes" can be used to set attributes for when
applying the rule.
</p><p>
The "skip" attribute on 'tpat' can be used to skip
certain matches.
</p><p>
$target and $source can be used in "commands" for the
actual file names. $match is what the "%" in the
pattern matched.
</p><p>
Alternative: instead of matching the file name with a
pattern,
<a href="ref-commands.html#cmd-action">:action</a>
uses filetypes to specify commands.
On non-Unix systems the pattern should contain only
lower case letters and forward slashes, because the
name it is compared with is made lower case and
backslashes have been replaced with forward slashes.
</p><p>
<a href="ref-commands.html#cmd-rule">:rule</a> is introduced in <a href="tutor-website.html" title="Chapter 3. Publishing a Web Site">Chapter 3, <i>Publishing a Web Site</i></a> of the tutorial.
Also see
<a href="ref-commands.html#cmd-delrule">:delrule</a>
and
<a href="ref-commands.html#cmd-clearrules">:clearrules</a> .
</p></dd><dt><a name="cmd-start"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:start</code> <em class="replaceable"><code>command</code></em> </p></div></span></dt><dd><p>
Like <a href="ref-commands.html#cmd-sys">:sys</a>
and <a href="ref-commands.html#cmd-sys">:system</a>,
but don't wait for the commands to finish. Errors of the executed
command are ignored.
</p><p>
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:
</p><pre class="programlisting">
:start xterm -e more README
</pre><p>
WARNING: Using
<a href="ref-commands.html#cmd-start">:start</a> probably makes your recipe non-portable.
</p></dd><dt><a name="cmd-symlink"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:symlink</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>from</code></em> <em class="replaceable"><code>to</code></em> </p></div></span></dt><dd><p>
Create a symbolic link, so that "to" points to "from".
Think of this as if making a copy of "from" without
actually copying the file.
</p><p>
Only for Unix and Mac OS X.
</p><p>
</p><div class="informaltable"><table border="0"><colgroup><col width="150"><col></colgroup><thead><tr><th>options</th><td class="auto-generated"> </td></tr></thead><tbody><tr><td>{q} or {quiet}</td><td>Don't complain when "to" already exists.</td></tr><tr><td>{f} or {force}</td><td>Overwrite an existing "to" file or symlink</td></tr></tbody></table></div><p>
</p></dd><dt><a name="cmd-sys"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:sys</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>command</code></em> <br><code class="command">:system</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>command</code></em> </p></div></span></dt><dd><p>
<a name="cmd-system"></a>
Execute "cmds" as system (shell) commands. Example:
</p><pre class="programlisting">
:system filter <foo >bar
:sys reboot universe
</pre><p>
The following lines with more indent are appended,
replacing the indent with a single space. Example:
</p><pre class="programlisting">
:sys echo one
two
</pre><p>
This echos "one two".
</p><p>
</p><div class="informaltable"><table border="0"><colgroup><col width="150"><col></colgroup><thead><tr><th>options</th><td class="auto-generated"> </td></tr></thead><tbody><tr><td>{i} or {interactive}</td><td>don't log output (see below)</td></tr><tr><td>{q} or {quiet}</td><td>Don't echo the command</td></tr><tr><td>{l} or {log}</td><td>Redirect all output to the log file, do not echo it</td></tr><tr><td>{f} or {force}</td><td>Ignore a non-zero exit value</td></tr></tbody></table></div><p>
</p><p>
{interactive} and {log} cannot be used at the same
time.
</p><p>
When using the {f} or {force} argument the exit value
of the command is available in $sysresult.
</p><p>
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:
</p><pre class="programlisting">
:system {i} vi bugreport
</pre><p>
<span class="application">Aap</span> attempts to execute consecutive commands with one
shell, to speed up the execution. This will not be
done when the {f} or {force} attribute is used, these
commands are executed separately.
</p><p>
<span class="application">Aap</span> waits for the command to finish.
Alternatively you can use <a href="ref-commands.html#cmd-start">:start</a>,
which runs the command asynchronously.
</p><p>
When the "async" variable is set and it is not empty,
<a href="ref-commands.html#cmd-sys">:sys</a> works like
<a href="ref-commands.html#cmd-start">:start</a>, except that consecutive
commands are executed all at once in one shell.
</p><p>
Also see <a href="ref-commands.html#cmd-asroot">:asroot</a> for executing a shell
command with super-user privileges.
</p><p>
On MS-Windows several commands use a forward slash for options and
require using backslashes in file names. But in Aap most file names
use forward slashes. To obtain the value of variable "var" with
slashes replaced with backslashes use "$/var".
See <a href="ref-varscope.html" title="Chapter 34. Variables and Scopes">Chapter 34, <i>Variables and Scopes</i></a>.
</p><p>
When using a variable as an argument, it may need to be put in quotes
to avoid it being interpreted as two arguments when it contains a
space. To obtain the value of variable "var" with quotes for the
shell use "$!var". See <a href="ref-varscope.html" title="Chapter 34. Variables and Scopes">Chapter 34, <i>Variables and Scopes</i></a>.
</p><p>
WARNING: Using
<a href="ref-commands.html#cmd-sys">:sys</a> or
<a href="ref-commands.html#cmd-system">:system</a> probably makes your
recipe non-portable.
</p></dd><dt><a name="cmd-sysdepend"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:sysdepend</code> {filepat = <em class="replaceable"><code>pattern</code></em>} [{srcpath = <em class="replaceable"><code>path ...</code></em>}] <em class="replaceable"><code>command</code></em> </p></div></span></dt><dd><p>
Execute shell command "command". It is supposed to figure out
automatic dependencies. When an included file cannot be found by the
shell command, an error message is expected that indicates which file
is missing. <span class="application">Aap</span> will then attempt to fetch or update the file and
run "command" again.
</p><p>
Error messages that match "pattern" are recognized and handled in a
special way. The "pattern" must contain one group (a pattern in
parenthesis), which matches the file name in an error message.
The files where the pattern matches are then updated, like <a href="ref-commands.html#cmd-update">:update</a> is invoked. The command is then
executed again.
</p><p>
The "srcpath" option is used to find the files from the error
messages. When it is omitted the following directories are searched:
</p><div class="orderedlist"><ol type="1"><li><p>
Directories from the $INCLUDE variable.
</p></li><li><p>
The first directory in the $source variable.
</p></li><li><p>
The current directory.
</p></li></ol></div><p>
</p><p>
The repetition of executing the command and finding matching file
names is repeated until there are no more matching error messages or
the list of file names is the same as the previous time.
</p><p>
An example:
</p><pre class="programlisting">
:sysdepend {filepat = .*: ([^:]*): File not found} depcheck $source > $target
</pre><p>
Be careful to exactly match the filename with the pattern inside ().
Leading and trailing white space is ignored. When necessary to use
another group, use "(?:pattern)" to avoid it's used as the file name.
</p><p>
WARNING: Using
<a href="ref-commands.html#cmd-syseval">:sysdepend</a> probably makes your recipe non-portable.
</p></dd><dt><a name="cmd-syseval"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:syseval</code> [{stderr}] [<em class="replaceable"><code>redir</code></em>] <em class="replaceable"><code>command</code></em> </p></div></span></dt><dd><p>
Execute shell command "command" and write its output
to stdout. Only stdout of the command is captured by default.
When {stderr} is just after the command name, stderr
is also captured. Example:
</p><pre class="programlisting">
:syseval hostname | :assign HOSTNAME
</pre><p>
When used in a pipe, the stdin is passed to the
command. Example:
</p><pre class="programlisting">
:print $var | :syseval sort | :assign var
</pre><p>
Leading and trailing blanks, including line breaks,
are removed. Thus the last line never ends in a
newline character.
</p><p>
See <a href="ref-commands.html#arg-redir">here</a> for [redir].
</p><p>
Note the difference with the
<a href="ref-commands.html#cmd-sys">:sys</a> command:
redirection in
<a href="ref-commands.html#cmd-sys">:sys</a> is handled by the shell, for
<a href="ref-commands.html#cmd-syseval">:syseval</a> it is handled by <span class="application">Aap</span>.
</p><p>
When executing the command fails, the result is empty.
The exit value of the command is available in $exit.
</p><p>
WARNING: Using
<a href="ref-commands.html#cmd-syseval">:syseval</a> probably makes your recipe non-portable.
</p></dd><dt><a name="cmd-syspath"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:syspath</code> <em class="replaceable"><code>path</code></em> <em class="replaceable"><code>arg</code></em>... </p></div></span></dt><dd><p>
Use "path" as a colon separated list of command names, use
the first command that works.
</p><p>
When %s appears in "path", it is replaced with the
arguments. If it does not appear, the arguments are appended.
</p><p>
Other appearences of % in "path" are removed, thereby
reducing %% to % and %: to : while avoiding their
special meaning.
</p><p>
Don't forget that "path" must be one argument, use
quotes around it to include white space.
</p><p>
Example:
</p><pre class="programlisting">
:syspath 'vim:vi:emacs' foobar.txt
</pre><p>
</p><p>
Output is not logged.
</p><p>
Note: on MS-Windows it's not possible to detect if a
command worked, the first item in the path will always
be used.
</p><p>
WARNING: Using
<a href="ref-commands.html#cmd-syspath">:syspath</a> probably makes your recipe non-portable.
</p></dd><dt><a name="cmd-tag"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:tag</code> [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...] <em class="replaceable"><code>fname</code></em>... </p></div></span></dt><dd><p>
Version control command, also see <a href="user-version.html" title="Chapter 18. Version Control">Chapter 18, <i>Version Control</i></a>.
</p><p>
Adds a tag to the current version of the files in the repository.
Uses the "tag" attribute.
</p></dd><dt><a name="cmd-tagall"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:tagall</code> [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...]</p></div></span></dt><dd><p>
Version control command, also see <a href="user-version.html" title="Chapter 18. Version Control">Chapter 18, <i>Version Control</i></a>.
</p><p>
Adds a tag to all items with a "commit" and "tag" attribute.
The tag should be simple name without special characters (no
dot or dash).
</p></dd><dt><a name="cmd-tee"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:tee</code> [<em class="replaceable"><code>redir</code></em>] <em class="replaceable"><code>fname</code></em>... </p></div></span></dt><dd><p>
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:
</p><p>
</p><pre class="programlisting">
:cat file1 file2 | :tee totfile | :assign foo
</pre><p>
</p></dd><dt><a name="cmd-toolsearch"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:toolsearch</code> <em class="replaceable"><code>toolname</code></em>... </p></div></span></dt><dd><p>
Specify a list of tools. The Python code for each tool is imported
and its "exist()" function invoked. The first tool that exists
becomes the default tool for the language(s) it supports.
See <a href="user-tools.html" title="Chapter 30. Customizing Default Tools">Chapter 30, <i>Customizing Default Tools</i></a> for more info.
</p><p>
For Unix systems three directories are used:
</p><table class="simplelist" border="0" summary="Simple list"><tr><td> - <code class="filename">~/.aap/tools/</code></td></tr><tr><td> - <code class="filename">/usr/local/share/aap/tools/</code> </td></tr><tr><td> - The <code class="filename">tools</code> directory of the <span class="application">Aap</span> installation</td></tr></table><p>
For other systems these directories are used:
</p><table class="simplelist" border="0" summary="Simple list"><tr><td> - <code class="filename">$HOME/aap/tools/</code> </td></tr><tr><td> - <code class="filename">$HOMEDRIVE/$HOMEPATH/aap/tools/</code></td></tr><tr><td> - <code class="filename">c:/aap/tools/</code></td></tr><tr><td> - The <code class="filename">tools</code> directory of the <span class="application">Aap</span> installation</td></tr></table><p>
$HOME, $HOMEDRIVE and $HOMEPATH are environment variables, not <span class="application">Aap</span>
variables.
</p><p>
<span class="emphasis"><em>Important:</em></span> The "tools" directory must have a
<code class="filename">__init__.py</code> file, so that it is recognized as a
package. The <code class="filename">__init__.py</code> file may be empty.
</p></dd><dt><a name="cmd-totype"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:totype</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>targettype</code></em> : [<em class="replaceable"><code>attribute</code></em>...] <em class="replaceable"><code>source</code></em>... </p></div></span></dt><dd><p>
Specify that each item in "source ..." is to be
turned into filetype "targettype". Dependencies
will be added to turn each source file into a file of
type "targettype". How this is done must have been
defined with
<a href="ref-commands.html#cmd-route">:route</a> commands before using the
<a href="ref-commands.html#cmd-totype">:totype</a> command!
</p><p>
Example:
</p><pre class="programlisting">
:totype footy {suffix = .foo} : aaa.cpp bbb.y
</pre><p>
This turns the file "aaa.cpp" into a file "aaa.foo" with filetype
"footy". Since "aaa.cpp" is recognized as a file with filetype
"cpp", this will use the route from "cpp" to "footy".
"bbb.y" is turned into "bbb.foo". "bbb.y" is recognized as a file
with filetype "yacc", this will use the route from "yacc" to
"footy".
</p><p>
If the resulting "targettype" files are additionally to be build
together into a program you can use the
<a href="ref-commands.html#cmd-program">:program</a> command instead.
A more generic form is the
<a href="ref-commands.html#cmd-produce">:produce</a> command.
</p><p>
The filename of each target is made from the source
file name, prepending $BDIR. The "prefix" and "suffix" attributes of
"targettype" are used ("prefix" is prepended, "suffix" replaces an
existing suffix).
When "targettype" is "object" the default for "suffix" is $OBJSUF, for
"dllobject" the default is $DLLOBJSUF and for "libobject" the default
is $LIBOBJSUF. Otherwise the "suffix" attribute must
be specified to avoid that the source and target have the same file
name.
</p><p>
[attributes] are optional attributes that apply to the
generated dependencies. Use the "scope" attribute to
specify a user scope to be used before other scopes
(except the local scope) in the generated
dependencies.
</p><p>
The targets and any intermediate files will be added
to $_recipe.CLEANFILES. The source files will be
added to $_recipe.DISTFILES, except the ones with a
{nodist} attribute.
</p><p>
Can only be used at the recipe level.
</p></dd><dt><a name="cmd-touch"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:touch</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>name</code></em>... </p></div></span></dt><dd><p>
Update timestamp of file or directory "name".
</p><p>
</p><div class="informaltable"><table border="0"><colgroup><col width="150"><col></colgroup><thead><tr><th>options</th><td class="auto-generated"> </td></tr></thead><tbody><tr><td>{f} {force}</td><td>create the file when it doesn't exist</td></tr><tr><td>{e} {exist}</td><td>create the file when it doesn't exist, don't update timestamp when the
file already exists</td></tr></tbody></table></div><p>
</p><p>
If "name" doesn't exist and {force} and {exist} are
not present the command fails.
</p><p>
If "name" doesn't exist and {force} or {exist} is
present an empty file will be created.
</p><p>
If "name" does exist and {exist} is present nothing
happens.
</p><p>
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.
</p><p>
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".
</p></dd><dt><a name="cmd-tree"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:tree</code> <em class="replaceable"><code>dirname</code></em> [<em class="replaceable"><code>option</code></em>...]<br><code class="command"> </code> <em class="replaceable"><code>command-block</code></em> </p></div></span></dt><dd><p>
Inspect the directory tree "dirname" and invoke the
command block for each selected file and/or directory.
In the command block $name has the name of the
selected item.
</p><p>
Example:
</p><pre class="programlisting">
:tree headers {filename = log}
:delete $name
</pre><p>
This deletes all "log" files below the "headers"
directory, possibly including "headers/log" and
"headers/sub/log".
</p><p>
The dirname itself is not part of the selected items.
</p><p>
</p><div class="informaltable"><table border="0"><colgroup><col width="200"><col></colgroup><thead><tr><th>options</th><td class="auto-generated"> </td></tr></thead><tbody><tr><td>{filename = pattern}</td><td>Select files where this Python re pattern matches
the whole filename.</td></tr><tr><td>{dirname = pattern}</td><td>Select directories where this Python re pattern matches
the whole filename.</td></tr><tr><td>{follow}</td><td>Do follow symbolic links.</td></tr><tr><td>{reject = pattern}</td><td>Exclude files and directories where this Python re
pattern matches the basename (the last component in the
path). Directories are still entered. For example, when the
pattern is "CVS" a file "CVS/Entries" can still be
included.</td></tr><tr><td>{skipdir = pattern}</td><td>Do not enter directories where this Python re
pattern matches the basename (the last component in the
path).</td></tr><tr><td>{contents = pattern}</td><td>Include only files that match the pattern in the file
contents. Does not apply to directories.</td></tr></tbody></table></div><p>
</p><p>
When neither the "filename" nor "dirname" is given,
all files are selected, as if {filename = .*} was used.
</p><p>
When the system ignores case for filenames the
patterns will ignore case differences for "filename",
"dirname" and "reject". The pattern for "contents" is
used with matching case.
</p><p>
The pattern for "filename", "dirname" and "reject"
must match the whole name, "^" is prepended and "$" is
appended. The pattern for "contents" is matched with
every line in the file, including the newline
character, and may match part of the line.
</p><p>
Hidden and system files are found as well, but the
directory entries "." and ".." are never selected.
</p><p>
The selected entries are ordered depth-first. For
example, "tree foo" would select:
</p><div class="literallayout"><p> foo/sub/f1<br>
foo/sub/subsub/f2<br>
foo/sub/subsub/<br>
foo/sub/f3<br>
foo/sub/<br>
foo/f4<br>
</p></div><p>
</p><p>
Without the "{follow}" option symbolic links to are not followed. The
symbolic link itself is included in the results (if the pattern
matches). Use os.path.islink() to test for symbolic
links. Hard links are not detected and may cause an
infinite loop.
</p><p>
Example that creates a list of C files, skipping "old" directories and
"test_" files:
</p><pre class="programlisting">
source =
:tree . {filename = .*\.c} {skipdir = old} {reject = test_.*}
source += $name
</pre></dd><dt><a name="cmd-unlock"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:unlock</code> [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...] <em class="replaceable"><code>fname</code></em>... </p></div></span></dt><dd><p>
Version control command, also see <a href="user-version.html" title="Chapter 18. Version Control">Chapter 18, <i>Version Control</i></a>.
</p><p>
Remove any lock on the files, don't change the file in the repository.
</p></dd><dt><a name="cmd-unlockall"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:unlockall</code> [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...]</p></div></span></dt><dd><p>
Version control command, also see <a href="user-version.html" title="Chapter 18. Version Control">Chapter 18, <i>Version Control</i></a>.
</p><p>
Apply the <code class="literal">:unlock</code> command to all files in the recipe (and
child recipes) that have the "commit" attribute.
</p></dd><dt><a name="cmd-update"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:update</code> [{force}] [{searchpath = <em class="replaceable"><code>path...</code></em>}] <em class="replaceable"><code>target</code></em>... </p></div></span></dt><dd><p>
Update "target" now, if it is outdated or when
"{force}" is used.
</p><p>
One or more targets can be specified, each will be
updated.
</p><p>
The "searchpath" argument can be used to search for the target in a
series of directories. Each item in "searchpath" is prepended to the
target name, unless it is an absolute path. The updating stops when
a path plus target is found that can be successfully updated.
</p><p>
When this appears at the top level, a dependency or
rule for the target to be used must already have been
specified, there is no look-ahead.
</p><p>
When the target exists and no dependency or rule
applies, the file is considered updated.
</p></dd><dt><a name="cmd-usetool"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:usetool</code> <em class="replaceable"><code>toolname</code></em> </p></div></span></dt><dd><p>
Specify a specific tool to be used. When used in the toplevel recipe
the tool becomes the default tool. Can also be used in a child recipe.
See <a href="user-tools.html" title="Chapter 30. Customizing Default Tools">Chapter 30, <i>Customizing Default Tools</i></a> for more info.
</p></dd><dt><a name="cmd-variant"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:variant</code> <em class="replaceable"><code>varname</code></em> <br><code class="command"> </code> <em class="replaceable"><code>value</code></em> <br><code class="command"> </code> <em class="replaceable"><code> commands</code></em> <br><code class="command"> </code> ... </p></div></span></dt><dd><p>
Define build variants. The "varname" is the name of a variable that
selects one of the possible "value" items.
</p><p>
The last "value" item can be a star. This item will be used when the
value of "varname" does not match one of the other values.
</p><p>
When the variable "varname" is not set or has an empty value, the first
entry is used.
</p><p>
The value of $BDIR is changed by appending a dash and the value of
"varname". The value is modified to avoid using an illegal filename.
</p><p>
See the User manual <a href="user-variant.html" title="Chapter 14. Variants">Chapter 14, <i>Variants</i></a> for examples.
</p><p>
Can only be used at the recipe level.
</p></dd><dt><a name="cmd-verscont"></a><span class="term"><div class="cmdsynopsis"><p><code class="command">:verscont</code> <em class="replaceable"><code>action</code></em> [{<em class="replaceable"><code>attr</code></em> = <em class="replaceable"><code>val</code></em>}...] <em class="replaceable"><code>fname</code></em>... </p></div></span></dt><dd><p>
Version control command, also see <a href="user-version.html" title="Chapter 18. Version Control">Chapter 18, <i>Version Control</i></a>.
</p><p>
Perform the version control "action" on the files.
This uses the "commit" attribute.
What happens is specific for the VCS.
</p></dd></dl></div><p>
</p><h2><a name="common-arguments"></a>Common arguments for Commands</h2><div class="variablelist"><dl><dt><a name="arg-redir"></a><span class="term"><div class="cmdsynopsis"><p>[<em class="replaceable"><code>redir</code></em>]</p></div></span></dt><dd><p>
Redirect the output of a command.
Can be one of these items:
</p><div class="informaltable"><table border="0"><colgroup><col width="100"><col></colgroup><tbody><tr><td>> <em class="replaceable"><code>fname</code></em></td><td>write output to file "fname"; fails when "fname" already exists</td></tr><tr><td>>! <em class="replaceable"><code>fname</code></em></td><td>write output to file "fname"; overwrite an existing file</td></tr><tr><td>>> <em class="replaceable"><code>fname</code></em></td><td>append output to file "fname"; create the file if it does not exist yet</td></tr><tr><td>| <em class="replaceable"><code>command</code></em></td><td>pipe output to the following "command"</td></tr></tbody></table></div><p>
The redirection can appear anywhere in the argument, except inside
quotes.
The normal place is either as the first or the last argument.
The pipe to the next command must appear at the end.
</p><p>
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.
</p><p>
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.
</p><p>
When a command produces text on stdout and no redirection or pipe is
used, the stdout is printed to the terminal.
</p></dd></dl></div><h2><a name="id2705606"></a>URLs</h2><p>
In various places URLs can be used to specify remote locations and the method
how to access it.
</p><p>
</p><div class="variablelist"><dl><dt><a name="url-http"></a><span class="term"> http://machine/path </span></dt><dd><p>
HTTP protocol, commonly used for web sites. read-only "machine" can
also be "machine:port".
</p></dd><dt><a name="url-ftp"></a><span class="term"> ftp://machine/path </span></dt><dd><p>
FTP protocol. "machine" can also be "machine:port". When ":port" is
omitted the default port 21 is used.
</p><p>
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).
</p><p>
Alternatively, login name and password can be
specified just before the machine name:
</p><div class="literallayout"><p> ftp://user@machine/path<br>
ftp://user:password@machine/path </p></div><p>
When ":password" is omitted, you will be prompted for
entering the password.
</p><p>
Either way: ftp sends passwords literally over the
net, thus THIS IS NOT SECURE! Should use "scp://"
instead.
</p></dd><dt><a name="url-scp"></a><span class="term"> scp://machine/path </span></dt><dd><p>
SCP protocol (using SSH, secure shell).
Requires the "scp" program installed (<span class="application">Aap</span> will
attempt installing it for you when needed).
Additionally a user name can be specified:
</p><div class="literallayout"><p> scp://user@machine/path </p></div><p>
"path" is a relative path to the directory where "ssh"
logs in to. To use an absolute path prepend a slash:
</p><div class="literallayout"><p> scp://machine//path </p></div><p>
The resulting path for the "scp" command uses a ":"
instead of the first slash.
</p><p>
Uses "scp -C" by default. Set the $SCPCMD variable to
use another command.
</p></dd><dt><a name="url-rcp"></a><span class="term"> rcp://machine/path </span></dt><dd><p>
RCP protocol (using rcp, "remote copy").
Very much like using "scp://", but WITHOUT SECURITY.
Requires the "rcp" program installed (<span class="application">Aap</span> will
attempt installing it for you when needed).
</p><p>
Uses "rcp" by default. Set the $RCPCMD variable to
use another command.
</p></dd><dt><a name="url-rsync"></a><span class="term"> rsync://machine/path </span></dt><dd><p>
RSYNC protocol (using rsync, "remote sync").
Like using "scp://", but only the difference between
files is transported. This is slower for transferring
a whole file but a lot faster if a file has few
changes.
</p><p>
Requires the "rsync" program installed (<span class="application">Aap</span> will
attempt installing it for you when needed).
Uses "rsync --rsh==ssh" by default. Set the $RSYNCCMD
variable to use another command.
</p></dd></dl></div><p>
</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref-python.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="appendix.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 41. A-A-P Python functions </td><td width="20%" align="center"><a accesskey="h" href="index.html">
Contents</a></td><td width="40%" align="right" valign="top"> Part IV. Appendixes</td></tr></table></div></body></html>
