Commands grouped by functionality Dependencies :program Define the sources for an executable program. :lib Define the sources for a static library. :ltlib Define the sources for a library to be made with libtool. :dll Define the sources for a shared (dynamically loaded) library. :produce Generic way to build something from sources. :totype Use routes to turn one filetype into another. :rule Define build commands for files matching a pattern. :delrule Delete a specific rule. :clearrules Delete all rules. :update Update a target, build it when it is outdated. :changed Mark a file as changed.   Recipes :child Read a child recipe. :include Include another recipe. :import Include a module from the &Aap; distribution. :execute Execute a recipe. :recipe Define the URL where the recipe can be obtaind from.   Actions :action Define commands for an action. :do Invoke an action. :route Define a route of actions to turn one filetype into another. :filetype Define filetype detection.   Up- and Downloading :fetch Download files. :fetchall Download all files with a "fetch" attribute. :publish Upload the specified files. :publishall Upload all files with a "publish" attribute. :mkdownload Create a recipe to download files. :proxy Define a proxy server.   Version control :add Add a file to the version control repository. :addall Add all files with a "commit" attribute to the version control repository. :checkin Checkin a file into the version control repository. :checkinall Checkin all files with a "commit" attribute into the version control repository. :checkout Checkout a file from the version control repository. :checkoutall Checkout all files with a "commit" attribute from the version control repository. :commit Commit files to the version control repository. :commitall Commit all files with a "commit" attribute to the version control repository. :remove Remove a file from the version control repository. :removeall Remove all file without the "commit" attribute from the version control repository. :reviseall combination of :checkinall and :removeall. :tag Add a tag in the version control repository for a file. :tagall Add a tag in the version control repository for all files with the "commit" attribute . :unlock Unlock a checked out file. :unlockall Unlock all checked out files with the "commit" attribute. :verscont Generic version control command.   System commands :asroot Execute a command as the system administrator. :sys Execute a system command. :system Execute a system command. :start Run a system command asynchronously. :syseval Execute a system command and catch the output. :sysdepend Execute a system command to figure out dependencies. :syspath Execute one of a number of commands.   Pipe commands :assign Assign stdin to a variable. :cat List or concatenate files. :print Print a message :log Write a message to the log file :tee Echo stdin to stdout and also write it in a file. :eval Evaluate a Python expression :syseval Execute a system command and catch the output.   File system commands :copy Copy files. :move Rename or move a file. :symlink Create a symbolic link. :chmod Change the protection bits of a file. :del Delete files. :delete Delete files. :deldir Delete directories. :mkdir Create a directory. :touch Create a file and/or update its timestamp. :tree Execute commands for a directory tree. :cd Change directory. :chdir Change directory. :pushdir Change directory and remember the previous one. :popdir Change to an older directory.   Various :attr Attach attributes to items. :attribute Attach attributes to items. :buildcheck Add a string to the build command signature. :exit Stop execution. :quit Stop execution. :pass Do nothing. :variant Define build variants. :python Execute Python commands. :conf Do a configuration check. :progsearch Search for an executable program. :assertpkg Check if a package is present, install it when not. :installpkg Install a package unconditionally. :usetool Specify what tool to use. :toolsearch Search for tools that can be used. Alphabetical list of Commands This is the alphabetical list of all A-A-P commands. Common arguments are explained at the end. Some commands can be used in a pipe. A pipe is a sequence of commands separated by '|', where the output of one command is the input for the next command. Example: :cat foo | :eval re.sub('this', 'that', stdin) | :assign bar Unix tradition calls the output that can be redirected or piped "stdout". Reading input from a pipe is called "stdin". In the commands below [redir] indicates the possibility to redirect stdout. :action action filetype-out filetype-in Define the commands for an action. See . :action makeme {primary} me moo :sys me < $source > $target 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. See :do for executing actions. :add {attr = val} fname Version control command, also see . Add the files to the repository. The files must exist locally. Implies a "commit" of the files. :addall option {attr = val} directory Version control command, also see . Apply the :add 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. options {l} {local} don't do current directory recursively {r} {recursive} do handle arguments recursively When no directory argument is given, the current directory is used. It is inspected recursively, unless the "{local}" option was given. When directory arguments are given, each directory is inspected. Recursively when the "{recursive}" option was given. When no "commit" attribute is specified here, it will be obtained from any node. :asroot command 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). 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. On non-Unix systems and when running &Aap; as root this command is equivalent to :system . 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. To execute recipe commands you need to start &Aap;, for example: :asroot $AAP -c 'copy {r} foodir /usr/local/share' $AAP includes the Python interpreter, so that it works the same way as how the current &Aap; was started. :assertpkg package 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. 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. See about using packages. See :installpkg for installing a package unconditionally. :assign varname Assign stdin to a variable. Can only be used after a "|". See here about using stdin. :attr {attrname} itemname {attrname} :attribute {attrname} itemname {attrname} 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. A node is created for each "itemname". This also means wildcards in item names will be expanded. Example: :attr {fetch = cvs://} foo.c patch12 {constant} This adds the "fetch" attribute to both foo.c and patch12, and the "constant" attribute only to patch12. This does the same in two commands: :attr {fetch = cvs://} foo.c patch12 :attr {constant} patch12 Note: the attributes are added internally. When using ":print $var" this only shows the attributes given by an assignment, not the ones added with :attr. :buildcheck argument 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. :cat redir fname Concatenate the arguments and write the result to stdout. Files are read like text files. The "-" argument can be used to get the output of a previous pipe command. When redirecting to a file this output file is created before the arguments are read, thus you cannot use the same file for input. See here for [redir]. :cd dir Change directory to "dir". When "dir" is "-" it goes back to the previous directory (it is an error if there was no previous :cd command in the current command block). When multiple arguments are given, they are concatenated with path separators inserted where needed. This is similar to doing a :cd for each argument, except that each argument but the first one is as handled as a relative path: :cd /tmp /usr/local bin Is equivalent to: :cd /tmp :cd ./usr/local :cd bin If the target directory does not exist this command fails. Use :mkdir first if needed (note: :mkdir does not contatenate its arguments!). Note that at the start of each command block &Aap; changes directory to the directory of the recipe. WARNING: variables with a relative path become invalid! This includes $source and $target. Use var_abspath(). when needed. :changed option name Consider file "name" changed, no matter whether it was really changed. Similar to the command line argument "--changed FILE". options {r} {recursive} Targets build from file "name" will also be considered changed, recursively. :chdir dir Same as :cd . :checkin {attr = val} fname Version control command, also see . Commit the files to the repository and unlock them. Just like :commit and :unlock. :checkinall {attr = val} Version control command, also see . Apply the :checkin command to all files in the recipe (and child recipes) that have the "commit" attribute. :checkout {attr = val} fname Version control command, also see . Obtain the latest version of the files from the repository. Lock the files for editing if possible. :checkoutall {attr = val} Version control command, also see . Apply the :checkout command to all files in the recipe (and child recipes) that have the "commit" attribute. :checksum file 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. This command is useful to check if a downloaded file was not damaged when downloading it. :child {nopass} name Read recipe "name" as a child. Works like the commands were in the parent recipe, with a number of exceptions: When "name" is in another directory, change to that directory and accept all items in it relative to that directory. Build commands defined in the child are executed in the directory of the child. Thus it works as if executing the child recipe in the directory where it is located. The child recipe defines a new scope. Variables set there without a scope specification will be local to the child recipe. 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. Build commands defined in the child recipe will be executed in the scope of that recipe. The "fetch" attribute is supported like with :include. The :child command can only appear at the recipe level. :chmod option mode name Change the protection flags of a file or directory. Currently "mode" must be an octal number, like used by the Unix "chmod" command. Useful values: modemeaning 755 executable for everyone, writable by user 444 read-only 600 read-write for the user only 660 read-write for user and group options {c} {continue} when an item with a wildcard does not have matches continue with the next item {f} {force} don't give an error when the file doesn't exist :clearrules Delete all rules. Also see :delrule. :commit {attr = val} fname Version control command, also see . 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). Do checkout/checkin when checkout is required. Don't change locking of the file. 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. Adds new files when needed. Creates directories when needed (CVS: only one level). :commitall {attr = val} Version control command, also see . Apply the :commit command to all files in the recipe (and child recipes) that have the "commit" attribute. :conf checkname arg Configuration command. See . :copy option from to Copy files or directory trees. "from" and "to" may be URLs. This means :copy can be used to upload and download a file, or even copy a file from one remote location to another. Examples: :copy file_org.c file_dup.c :copy {r} onedir twodir :copy *.c backups :copy http://vim.sf.net/download.php download.php :copy $ZIP ftp://upload.sf.net//incoming/$ZIP :copy ftp://foo.org/README ftp://bar.org//mirrors/foo/README Note that "ftp://machine/path" uses "path" relative to the login directory, while "ftp://machine//path" uses "/path" absolutely. When "from" and "to" are directories, "from" is created in "to". Unlike the Unix "cp" command, where this depends on whether "to" exists or not. Thus: :copy {recursive} foo bar will create the directory "bar/foo" if it doesn't exist yet. If the contents of "foo" is to be copied without creating "bar/foo", use this: :copy {recursive} foo/* bar options {c} {continue} when an item with a wildcard does not have matches continue with the next item {e} {exist} {exists} don't overwrite an existing file or directory {f} {force} forcefully overwrite an existing file or dir (default) {i} {interactive} before overwriting a local file, prompt for confirmation (currently doesn't work for remote files) {k} {keepdir} 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 {m} {mkdir} create destination directory when needed {p} {preserve} preserve file permissions and timestamps as much as possible {q} {quiet} don't report copied files {r} {recursive} recursive, copy a directory tree. "to" is created and should not exist yet. {u} {unlink} when used with {recursive}, don't copy a symlink, make a copy of the file or dir it links to Wildcards in local files are expanded. This uses Unix style wildcards. When there is no matching file the command fails (also when there are enough other arguments). When (after expanding wildcards) there is more than one "from" item, the "to" item must be a directory. For "to" only local files, ftp://, rcp://, rsync:// and scp:// can be used. See "URLs" for info on forming URLs. Attributes for "from" and "to" are currently ignored. :del option file :delete option file Delete files and/or directories. options {f} {force} don't fail when a file doesn't exist {r} {recursive} delete directories and their contents recursively. {q} {quiet} don't report deleted files Wildcards in local files are expanded. This uses Unix style wildcards. When there is no matching file the command fails (also when there are enough other arguments). When deleting a symbolic link, the link itself is deleted, not the file or directory it refers to. CAREFUL: if you make a mistake in the argument, anything might be deleted. For example, accidentally inserting a space before a wildcard: :del {r} dir/temp * To give you some protection, the command aborts on the first error. Thus if "dir/temp" didn't exist in the example, "*" would not be deleted. :deldir option dir Delete a directory. Fails when the directory is not empty. options {c} {continue} when an item with a wildcard does not have matches continue with the next item {f} {force} don't fail when a directory doesn't exist; still fails when it exists but is not a directory or could not be deleted {q} {quiet} don't report deleted directories :delrule option tpat spat Delete an existing rule. Can be used when one of the default rules would be used when this is not wanted. options {q} {quiet} don't complain when there is no matching rule Also see :clearrules. :dll option target : {attr = val} source 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". 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: all: foo bar :dll foo : foo.c :dll bar : bar.c On Unix this builds libfoo.so and libbar.so. See :produce 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". In addition, the "{onestep}" option explained for :command can be used. "{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. 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. Can only be used at the recipe level. :do action fname Execute an action. The commands executed may depend on the types of the first input file and/or the output file. See . 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. :do build {target = prog} foo.c options {filetype} The "filetype" attribute can be used to override the output filetype used to select the action to be executed. Example: :do build {filetype = libtoolexe} $Objects 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. {scope} 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. s_opti.DEFINE = -DFOOBAR ... :do build {scope = s_opti} foo.c {remove} 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: tmp = `tempfname()` :print >tmp Buy more Spam! :do email {remove} {to = everybody@world.org} {subject = Spam} tmp See :action for defining actions. :eval redir python-expression Filter stdin using a Python expression. See here for [redir]. When not used after "|" evaluate the Python expression. The Python expression is evaluated as specified in the argument. The "stdin" variable holds the value of the input as a string, it must be present when :eval is used after "|". See var2string() for information about using &Aap; variables in the Python expression. The expression must result in the filtered string or something that can be converted to a string with str(). This becomes stdout. The result may be empty. Examples: :print $foo | :eval re.sub('<.*?>', '', stdin) > tt :eval os.name | :assign OSNAME Note that the expression must not contain a "|" preceded by white space, it will be recognized as a pipe. Also there must be no ">" preceded by white space, it will be recognized as redirection. :execute {pass} name argument Execute recipe "name" right away. This works like executing aap on "name". The recipe is executed in a new scope. This is used as the toplevel scope, unless the "{pass}" option is used. The "fetch" attribute is supported like with :include. Optional arguments may be given, like on the command line. This is useful for specifying targets and variable values. "-f recipe" is ignored. Example: TESTPROG = ./myprog :execute test.aap test1 test2 The following command line options are also used for the executed recipe. Thus when &Aap; 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. -C --contents -k --continue -F --force -n --nobuild -a --nocache -N --nofetch-recipe -s --silent -S --stop -t --touch -v --verbose This command is useful when a recipe does not contain dependencies that interfere with sources and targets in the current recipe. For example, to build a command the current recipe depends on. For example, when the program "mytool" is required and it doesn't exist yet, execute a recipe to build and install it: @if not program_path("mytool"): :execute mytool.aap install :sys mytool See the program_path() function. Another example: build two variants: :execute build.aap GUI=motif :execute build.aap GUI=gtk :exit exitval Quit executing recipes. When used in build commands, the "finally" targets will still be executed. But a :quit or :exit in the commands of a "finally" target will quit further execution. When "exitval" is given Aap will use it as the exit value of the program. :fetch {attr = val} file Fetch the files mentioned according to their "fetch" or "commit" attribute. When a file does not have these attributes or fetching fails you will get an error message. An attribute that appears before the files it is applied to all files. Files that exist and have a "fetch" attribute with value "no" are skipped. The name "." can be used to update the current directory: :fetch . {fetch = cvs://$CVSROOT} 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. "{nocache}" does the opposite: never use a cached file. 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}". :fetchall {attr = val} Fetch all the files in the recipe (and child recipes) that have the "fetch" attribute. Extra attributes for fetching can be specified here, they overrule the attributes of the file itself. :filetype argument Specify filetype detection. See . :import name Read a module stored in the main &Aap; directory or elsewhere. This happens in a special scope, does not change directory, and has no effect on the recipe containing the :import command except that the actions, filetypes and routes defined in the module become available globally. This is the easiest way to add additional language support to &Aap;. See . The recipe(s) read have the name of the module with ".aap" appended. Thus for ":import java" the "java.aap" recipe is used. 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: - ~/.aap/modules/ - /usr/local/share/aap/modules/ - The modules directory of the &Aap; installation For other systems these directories are used: - $HOME/aap/modules/ - $HOMEDRIVE/$HOMEPATH/aap/modules/ - c:/aap/modules/ - The modules directory of the &Aap; installation $HOME, $HOMEDRIVE and $HOMEPATH are environment variables, not &Aap; variables. 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. 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. :include option name 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. The -I or --include 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. 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. options {q} {quiet} Don't give a warning for a file that can't be read. Used to optionally include a recipe. {o} {once} 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. :installpkg package Install packages. Each argument is the name of a package. This works like :assertpkg but without checking if the package is already present or asking the user whether it should be installed. See about using packages. :lib option target : {attr = val} source 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". 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: all: foo bar :lib foo : foo.c :lib bar : bar.c On Unix this builds libfoo.a and libbar.a. See :produce 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". In addition, the "{onestep}" option explained for :command can be used. "{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. 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. Can only be used at the recipe level. :log text Write the arguments to the log file AAPDIR/log. This is like :print, but the text is not echoed. The output cannot be redirected or piped, since there isn't any. :ltlib option target : {attr = val} source 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". Very similar to :lib. Using libtool requires importing the libtool module. Since :ltlib will not work without it, the libtool module is automatically imported. See :produce 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". 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. Can only be used at the recipe level. :mkdir option dir Create directory. This fails when "dir" already exists and is not a directory. Each argument is handled separately (they are not concatenated like with :cd!). A "mode" attribute on a directory can be used to specify the protection flags for the new directory. Example: :mkdir {r} ~/secret/dir {mode = 0700} The default mode is 0644. The effective umask may reset some of the bits though. options {f} {force} Don't fail when a directory already exist; still fails when it is not a directory or could not be created. {q} {quiet} don't report created directories. {r} {recursive} Also create intermediate directories, not just the deepest one. Note: automatic creation of directories can be done by adding the {directory} attribute to a source item. :mkdownload name file Generate a recipe "name" that downloads the specified files. Each file must have a "fetch" attribute, which is used in the generated recipe. When the file "name" already exists it is overwritten without warning. Wildcards in "file ..." are expanded. Not in "name". MD5 checksums are generated and used in the recipe to fetch a file only when the checksum differs. Example of one item: file = foobar.txt @if get_md5(file) != "a5dba5bce69918c040703e9b8eb35f1d": :fetch {fetch = ftp://foo.org/files/%file%} $file When there is a "fetch" attribute on "name", this will be used to add a :recipe command at the start of the generated recipe. :move option from to Move files or directories. Mostly like :copy, except that the "from" files/directories are renamed or, when renaming isn't possible, copied and deleted. options {c} {continue} when an item with a wildcard does not have matches continue with the next item {e} {exist} {exists} don't overwrite an existing file or directory {f} {force} forcefully overwrite an existing file or directory (default) {i} {interactive} before overwriting a local file, prompt for confirmation (currently doesn't work for remote files) {m} {mkdir} create destination directory when needed {q} {quiet} don't report moved files :pass Do nothing. Useful to define a target with build commands to avoid a dependency is added automatically. clean: :pass :popdir Change back to directory on top of the directory stack, undoing a previous :pushdir. It is an error if the directory stack is empty (more :popdir than :pushdir used). :print redir text Print the arguments on stdout. Without arguments a line feed is produced. $var items are expanded, otherwise the arguments are produced literally, including quotes: :print "hello" results in: "hello" 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: :print $( ) indented text results in: indented text When used in a pipe the stdin variable holds the input. See here for [redir]. See :log for writing a message to the log file without echoing. :produce what option target : {attr = val} source 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". 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 :program, for building a shared library use :dll, for building a static library use :lib, for building a libtool library use :ltlib. The building is split up in two parts: Dependencies are added to compile the source files into files specified with the "objecttype" option. The routes specified with :route are used to decide which actions to invoke. These :route commands must precede the :produce command! Each step in the route becomes a separate dependency, so that intermediate results are produced. This is similar to what the :totype command does. 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. 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: all: foo bar :produce drink $drinkoptions foo : foo.c :produce snack $snackoptions bar : bar.c options targetsuffix (optional) appended to the target if it doesn't contain a dot targetprefix (optional) prepended to the target if it doesn't contain a dot comment (optional) description of type of building displayed for "aap --comment target". A "comment" attribute on the target overrules this. objectprefix (optional) prefix for the intermediate results. objectsuffix (optional) suffix for the intermediate results. objecttype (mandatory) filetype for the intermediate results. installvar (optional) name of the install variable to add the target to (default: INSTALL_EXEC) Set to an empty value to omit installing buildaction (mandatory) name of the action used to turn the intermediate results into the target Can only be used at the recipe level. :program option target : {attr = val} source 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". 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: all: foo bar :program foo : foo.c :program bar : bar.c On MS-Windows this builds foo.exe and bar.exe. See :produce 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". 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 ). This solution might be faster for very fast compilers. "{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. 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. Can only be used at the recipe level. :progsearch varname progname Check if an executable progname exists in $PATH. If not, check further arguments. The first one found is assigned to variable varname. If none of the progname could be found varname will be set to an empty string. Example: :progsearch BROWSER netscape opera @if BROWSER: :sys $BROWSER readme.html :proxy protocol address Specify a proxy server. Examples: :proxy ftp ftp://ftp.proxy.net:1234 :proxy http://www.someproxy.com:1080 The "protocol" can be "ftp", "http" or "gopher". When omitted "http" is used. Case doesn't matter. The {address} is a URL with the port number included. The result of this command is that an environment variable is set, as the Python library "urllib" requires. Therefore it must be done early in the startup phase, before accessing the internet. :publish {attr = val} file Publish the files mentioned according to their "publish" or "commit" attribute. Creates directories when needed (for CVS only one level). :publishall {attr = val} Publish all the files in the recipe (and child recipes) that have the "publish" attribute and changed since the last time they were published. Note that this doesn't fall back to the "commit" attribute like :publish does. :pushdir dir Change directory to "dir". The current directory is pushed onto the directory stack, so that :popdir goes back to the old current directory. Note that at the start of each command block &Aap; changes directory to the directory of the recipe. WARNING: variables with a relative path become invalid! This includes $source and $target. Use var_abspath(). when needed. :python   python-command-block A block of Python code. The block ends when the indent drops to the level of :python or below. :python terminator   python-command-block   terminator A block of Python code. The block ends when "terminator" is found on a line by itself. The Python commands may have any indent. White space before and after "terminator" is allowod and a comment after "terminator" is also allowed. "terminator" can contain any characters except white space. :quit exitval See :exit. :recipe {fetch = URL } Location of this recipe. The "fetch" attribute is used like with :child: a list of locations. The first URL that works is used. When aap was started with the "fetch" argument, fetch the recipe and restart reading it. Using the "fetch" or "update" target causes this as well. The commands before :recipe have already been executed, thus this may cause a difference from executing the new recipe directly. The values of variables are restored to the values before executing the recipe. Fetching a specific recipe is done only once per session. :remove {attr = val} fname Version control command, also see . Remove the files from the repository. The file may still exist locally. Implies a "commit" of the file. :removeall option {attr = val} directory Version control command, also see . Apply the :remove 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). 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! options {l} {local} don't do current directory recursively {r} {recursive} do handle arguments recursively When no directory argument is given, the current directory is used. It is inspected recursively, unless the "{local}" option was given. When directory arguments are given, each directory is inspected. Recursively when the "{recursive}" option was given. When no "commit" attribute is specified here, it will be obtained from any node. :reviseall {attr = val} Version control command, also see . Just like using both :checkinall and :removeall on the current directory recursively. :route option typelist typelist {attr = value}   action filename   ...   action 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. 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. 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. 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). Example: :route yacc c object yacc $(source).c compile 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: :do yacc {target = $(source).c} $source The step from "c" to "object" is done with a "compile" action. It will be invoked like this: :do compile {target = $target} $(source).c 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. options {default} This is a default route. No warning is given if the route is redefined later. The defined routes can be used explicitly with the :totype command. They are also used with the :produce command and derivatives. Note: In a later version of &Aap; 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. :rule option tpat : {attr = val} spat   command-block Define a rule to build files matching the pattern "tpat" from a file matching "spat". Example: :rule %.html : header.part %.part footer.part :cat $source > $target There can be several "tpat" patterns, the rule is used if one of them matches. There can be several "spat" patterns, the rule is used if they all exist (or no better rule is found). When "commands" is missing this only defines that "tpat" depends on "spat". Can only be used at the recipe level. A rule is used in the recipe where it is defined and in its siblings, unless an option is used to specify otherwise. options {global} use this rule in all places {local} use this rule only for targets in this recipe {default} default rule, redefining it will not cause a message {sourceexists} only use the rule when the matching source file exists; useful for rules that generate source code "attributes" can be used to set attributes for when applying the rule. The "skip" attribute on 'tpat' can be used to skip certain matches. $target and $source can be used in "commands" for the actual file names. $match is what the "%" in the pattern matched. Alternative: instead of matching the file name with a pattern, :action uses filetypes to specify commands. 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. :rule is introduced in of the tutorial. Also see :delrule and :clearrules . :start command Like :sys and :system, but don't wait for the commands to finish. Errors of the executed command are ignored. Runs in the same terminal, which will cause problems when the command waits for input. Open a new terminal to run that command in. Example: :start xterm -e more README WARNING: Using :start probably makes your recipe non-portable. :symlink option from to 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. Only for Unix and Mac OS X. options {q} or {quiet} Don't complain when "to" already exists. {f} or {force} Overwrite an existing "to" file or symlink :sys option command :system option command Execute "cmds" as system (shell) commands. Example: :system filter <foo >bar :sys reboot universe The following lines with more indent are appended, replacing the indent with a single space. Example: :sys echo one two This echos "one two". options {i} or {interactive} don't log output (see below) {q} or {quiet} Don't echo the command {l} or {log} Redirect all output to the log file, do not echo it {f} or {force} Ignore a non-zero exit value {interactive} and {log} cannot be used at the same time. When using the {f} or {force} argument the exit value of the command is available in $sysresult. Output is logged by default. If this is undesirable (e.g., when starting an interactive command) prepend "{i}" or "{interactive}" to the command. It will be removed before executing it. Example: :system {i} vi bugreport &Aap; 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. &Aap; waits for the command to finish. Alternatively you can use :start, which runs the command asynchronously. When the "async" variable is set and it is not empty, :sys works like :start, except that consecutive commands are executed all at once in one shell. Also see :asroot for executing a shell command with super-user privileges. 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 . 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 . WARNING: Using :sys or :system probably makes your recipe non-portable. :sysdepend {filepat = pattern} {srcpath = path ...} command 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. &Aap; will then attempt to fetch or update the file and run "command" again. 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 :update is invoked. The command is then executed again. The "srcpath" option is used to find the files from the error messages. When it is omitted the following directories are searched: Directories from the $INCLUDE variable. The first directory in the $source variable. The current directory. 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. An example: :sysdepend {filepat = .*: ([^:]*): File not found} depcheck $source > $target 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. WARNING: Using :sysdepend probably makes your recipe non-portable. :syseval {stderr} redir command 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: :syseval hostname | :assign HOSTNAME When used in a pipe, the stdin is passed to the command. Example: :print $var | :syseval sort | :assign var Leading and trailing blanks, including line breaks, are removed. Thus the last line never ends in a newline character. See here for [redir]. Note the difference with the :sys command: redirection in :sys is handled by the shell, for :syseval it is handled by &Aap;. When executing the command fails, the result is empty. The exit value of the command is available in $exit. WARNING: Using :syseval probably makes your recipe non-portable. :syspath path arg Use "path" as a colon separated list of command names, use the first command that works. When %s appears in "path", it is replaced with the arguments. If it does not appear, the arguments are appended. Other appearences of % in "path" are removed, thereby reducing %% to % and %: to : while avoiding their special meaning. Don't forget that "path" must be one argument, use quotes around it to include white space. Example: :syspath 'vim:vi:emacs' foobar.txt Output is not logged. Note: on MS-Windows it's not possible to detect if a command worked, the first item in the path will always be used. WARNING: Using :syspath probably makes your recipe non-portable. :tag {attr = val} fname Version control command, also see . Adds a tag to the current version of the files in the repository. Uses the "tag" attribute. :tagall {attr = val} Version control command, also see . 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). :tee redir fname Write stdin to each file in the argument list and also write it to stdout. This works like a T shaped connection in a water pipe. Example: :cat file1 file2 | :tee totfile | :assign foo :toolsearch toolname 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 for more info. For Unix systems three directories are used: - ~/.aap/tools/ - /usr/local/share/aap/tools/ - The tools directory of the &Aap; installation For other systems these directories are used: - $HOME/aap/tools/ - $HOMEDRIVE/$HOMEPATH/aap/tools/ - c:/aap/tools/ - The tools directory of the &Aap; installation $HOME, $HOMEDRIVE and $HOMEPATH are environment variables, not &Aap; variables. Important: The "tools" directory must have a __init__.py file, so that it is recognized as a package. The __init__.py file may be empty. :totype option targettype : attribute source 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 :route commands before using the :totype command! Example: :totype footy {suffix = .foo} : aaa.cpp bbb.y 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". If the resulting "targettype" files are additionally to be build together into a program you can use the :program command instead. A more generic form is the :produce command. 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. [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. 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. Can only be used at the recipe level. :touch option name Update timestamp of file or directory "name". options {f} {force} create the file when it doesn't exist {e} {exist} create the file when it doesn't exist, don't update timestamp when the file already exists If "name" doesn't exist and {force} and {exist} are not present the command fails. If "name" doesn't exist and {force} or {exist} is present an empty file will be created. If "name" does exist and {exist} is present nothing happens. A "directory" attribute can be used to specify a non-existing "name" is to be created as a directory. There is no check if an existing "name" actually is a directory. A "mode" attribute can be used to specify the mode with which a new file or directory is to be created. The value is in the usual octal form, e.g., "0644". :tree dirname option   command-block 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. Example: :tree headers {filename = log} :delete $name This deletes all "log" files below the "headers" directory, possibly including "headers/log" and "headers/sub/log". The dirname itself is not part of the selected items. options {filename = pattern} Select files where this Python re pattern matches the whole filename. {dirname = pattern} Select directories where this Python re pattern matches the whole filename. {follow} Do follow symbolic links. {reject = pattern} 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. {skipdir = pattern} Do not enter directories where this Python re pattern matches the basename (the last component in the path). {contents = pattern} Include only files that match the pattern in the file contents. Does not apply to directories. When neither the "filename" nor "dirname" is given, all files are selected, as if {filename = .*} was used. 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. 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. Hidden and system files are found as well, but the directory entries "." and ".." are never selected. The selected entries are ordered depth-first. For example, "tree foo" would select: foo/sub/f1 foo/sub/subsub/f2 foo/sub/subsub/ foo/sub/f3 foo/sub/ foo/f4 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. Example that creates a list of C files, skipping "old" directories and "test_" files: source = :tree . {filename = .*\.c} {skipdir = old} {reject = test_.*} source += $name :unlock {attr = val} fname Version control command, also see . Remove any lock on the files, don't change the file in the repository. :unlockall {attr = val} Version control command, also see . Apply the :unlock command to all files in the recipe (and child recipes) that have the "commit" attribute. :update {force} {searchpath = path...} target Update "target" now, if it is outdated or when "{force}" is used. One or more targets can be specified, each will be updated. 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. 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. When the target exists and no dependency or rule applies, the file is considered updated. :usetool toolname 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 for more info. :variant varname   value     commands   ... Define build variants. The "varname" is the name of a variable that selects one of the possible "value" items. 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. When the variable "varname" is not set or has an empty value, the first entry is used. 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. See the User manual for examples. Can only be used at the recipe level. :verscont action {attr = val} fname Version control command, also see . Perform the version control "action" on the files. This uses the "commit" attribute. What happens is specific for the VCS. Common arguments for Commands redir Redirect the output of a command. Can be one of these items: > fname write output to file "fname"; fails when "fname" already exists >! fname write output to file "fname"; overwrite an existing file >> fname append output to file "fname"; create the file if it does not exist yet | command pipe output to the following "command" The 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. The file name can be a URL. The text will first be written to a local file and then the file is moved to the final destination. The white space before the file name may be omitted. White space before the ">" and "|" is required. To avoid recognizing the ">" and "|" for redirection and pipes, use $gt and $pipe. When a command produces text on stdout and no redirection or pipe is used, the stdout is printed to the terminal. URLs In various places URLs can be used to specify remote locations and the method how to access it. http://machine/path HTTP protocol, commonly used for web sites. read-only "machine" can also be "machine:port". ftp://machine/path FTP protocol. "machine" can also be "machine:port". When ":port" is omitted the default port 21 is used. For authentication the ~/.netrc file is used if possible (unfortunately, the Python netrc module has a bug that prevents it from understanding many netrc files). Alternatively, login name and password can be specified just before the machine name: ftp://user@machine/path ftp://user:password@machine/path When ":password" is omitted, you will be prompted for entering the password. Either way: ftp sends passwords literally over the net, thus THIS IS NOT SECURE! Should use "scp://" instead. scp://machine/path SCP protocol (using SSH, secure shell). Requires the "scp" program installed (&Aap; will attempt installing it for you when needed). Additionally a user name can be specified: scp://user@machine/path "path" is a relative path to the directory where "ssh" logs in to. To use an absolute path prepend a slash: scp://machine//path The resulting path for the "scp" command uses a ":" instead of the first slash. Uses "scp -C" by default. Set the $SCPCMD variable to use another command. rcp://machine/path RCP protocol (using rcp, "remote copy"). Very much like using "scp://", but WITHOUT SECURITY. Requires the "rcp" program installed (&Aap; will attempt installing it for you when needed). Uses "rcp" by default. Set the $RCPCMD variable to use another command. rsync://machine/path 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. Requires the "rsync" program installed (&Aap; will attempt installing it for you when needed). Uses "rsync --rsh==ssh" by default. Set the $RSYNCCMD variable to use another command.