Chapter 27. A-A-P Commands

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 Chapter 23.
	:do build {target = prog} foo.c

See :do for executing actions.

:add			Version control command, see Chapter 16.
:addall			Version control command, see Chapter 16.

:assign varname		Assign stdin to a variable.  Can only be used after a
			"|".

:attr {attrname} ... itemname ...
:attribute {attrname} ... itemname ...
			Add the list of attributes "{attrname} ..." to each
			item in the list of items "itemname ...".
			Creates a node for each "itemname".

:attr itemname {attrname} ...
:attribute itemname {attrname} ...
			Add attributes "{attrname} ..." to item "itemname".

	      The above two forms can be mixed.  Example:

		      :attr {fetch = cvs://} foo.c patch12 {constant}

	      This adds the "fetch" attribute to both foo.c and patch12, and
	      the "constant" attribute only to patch12.  This does the same in
	      two commands:

		      :attr {fetch = cvs://} foo.c patch12
		      :attr {constant} patch12

	      Note: the attributes are added internally.  When using ":print
	      $var" this only shows the attributes given by an assignment, not
	      the ones added with ":attr".

:cat [redir] fname...

Concatenate the arguments and write the result to stdout. Files are read like text files. The "-" argument can be used to get the output of a previous pipe command. When redirecting to a file this output file is created before the arguments are read, thus you cannot use the same file for input.

See here for [redir].

:checkin		Version control command, see Chapter 16.
:checkinall		Version control command, see Chapter 16.
:checkout		Version control command, see Chapter 16.
:checkoutall		Version control command, see Chapter 16.

:child [{nopass}] name
			Read recipe "name" as a child.  Mostly works like the
			commands were in the parent recipe, with a few
			exceptions:
			- When "name" is in another directory, change to that
			  directory and accept all items in it relative to
			  that directory.
			- Build commands defined in the child are executed in
			  the directory of the child.  Thus it works as if
			  executing the child recipe in the directory where it
			  is located.
			- Variables from the parent recipe can be used but
			  changes to them will be used in the child only.
			  When the {nopass} option is used, variables from the
			  parent recipe are not passed to the child.
			  New variables are local to the child recipe.  Except
			  for the variables exported with ":export".
			- Build commands are executed with the variables of
			  the child recipe available, plus the variables of
			  the toplevel parent.  For exported variables the
			  value of the toplevel parent is used, for others the
			  local values are used.
			The "fetch" attribute is supported like with
			":include".

:chmod [options] mode name ...
			Change the protection flags of a file or directory.
			Currently "mode" must be an octal number, like used by
			the Unix "chmod" command.  Useful values:
				755	executable for everyone, writable by
					user
				444	read-only
				600	read-write for the user only
				660	read-write for user and group

			OPTIONS
			{f} {force}	don't give an error when the file
					doesn't exist

:commit			Version control command, see Chapter 16.
:commitall		Version control command, see Chapter 16.

:copy [options] from ... to
			Copy files or directory trees.  "from" and "to" may be
			URLs.  This means :copy can be used to upload and
			download a file, or even copy a file from one remote
			location to another.  Examples:
		:copy file_org.c  file_dup.c
		:copy {r}  onedir  twodir
		:copy *.c backups
		:copy http://vim.sf.net/download.php download.php
		:copy $ZIP ftp://upload.sf.net/incoming/$ZIP
		:copy ftp://foo.org/README ftp://bar.org/mirrors/foo/README
			
			When "from" and "to" are directories, "from" is
			created in "to".  Unlike the Unix "cp" command, where
			this depends on whether "to" exists or not.  Thus:

				:copy {recursive} foo bar

			will create the directory "bar/foo" if it doesn't
			exist yet.  If the contents of "foo" is to be copied
			without creating "bar/foo", use this:

				:copy {recursive} foo/* bar

			OPTIONS
			{f} {force}	forcefully overwrite an existing file
					or dir (default)
			{e} {exist} {exists}	don't overwrite an existing
					file or directory
			{i} {interactive}	before overwriting a local
					file, prompt for confirmation
					(currently doesn't work for remote
					files)
			{u} {unlink}	when used with {recursive}, don't copy
					a symlink, make a copy of the file or
					dir it links to
			{p} {preserve}	preserve file permissions and
					timestamps as much as possible
			{r} {recursive}	recursive, copy a directory tree.
					"to" is created and should not exist
					yet.
			{q} {quiet}	don't report copied files

			Wildcards in local files are expanded.  This uses Unix
			style wildcards.  When there is no matching file the
			command fails (also when there are enough other
			arguments).

			When (after expanding wildcards) there is more than
			one "from" item, the "to" item must be a directory.

			For "to" only local files, ftp:// and scp:// can be
			used.  See "URLs" for info on forming URLs.

			Attributes for "from" and "to" are currently ignored.

:del [options] file ...
:delete [options] file ...
			Delete files and/or directories.

			OPTIONS
			{f} {force}	don't fail when a file doesn't exist
			{r} {recursive}	delete directories and their contents
					recursively
			{q} {quiet}	don't report deleted files

			Wildcards in local files are expanded.  This uses Unix
			style wildcards.  When there is no matching file the
			command fails (also when there are enough other
			arguments).

			CAREFUL: if you make a mistake in the argument,
			anything might be deleted.  For example, accidentally
			inserting a space before a wildcard:

				:del {r} dir/temp *

			To give you some protection, the command aborts on the
			first error.  Thus if "dir/temp" didn't exist in the
			example, "*" would not be deleted.

:deldir [options] dir ...
			Delete a directory.  Fails when the directory is not
			empty.

			OPTIONS
			{f} {force}	don't fail when a directory doesn't
					exist; still fails when it exists but
					is not a directory or could not be
					deleted
			{q} {quiet}	don't report deleted directories

:do action [fname...]

Execute an action. The commands executed may depend on the types of the input and/or output files. See Chapter 23.
	:do build {target = prog} foo.c

See :action for defining actions.


:eval [redir] python-expression
			Filter stdin using a Python expression.
			When not used after "|" evaluate the Python
			expression.
			The Python expression is evaluated as specified in the
			argument.  The "stdin" variable holds the value of the
			input as a string, it must be present when ":eval"
			is used after "|".
			$var items are not expanded before evaluating the
			python expression.  To get the value of $var use
			"var" as a Python variable.
			The expression must result in the filtered string or
			something that can be converted to a string with
			str().  This becomes stdout.  The result may be empty.
			Examples:

			:print $foo | :eval re.sub('<.*?>', '', stdin) > tt
			:eval os.name | :assign OSNAME

			Note that the expression must not contain a "|"
			preceded by white space, it will be recognized as a
			pipe.  Also there must be no ">" preceded by white
			space, it will be recognized as redirection.
			$VAR items will be expanded in the filter command.


:execute [{pass}] name [ argument ] ...
			Execute recipe "name" right away.  This works like
			executing aap on "name".
			Variables from the current recipe are passed to
			the executed recipe when the "{pass}" option is
			used.
			":export" can be used to get variables from the
			executed recipe into the current recipe.
			The "fetch" attribute is supported like with
			":include".
			Optional arguments may be given, like on the command
			line.  This is useful for specifying targets and
			variable values. "-f recipe" is ignored.
			Example:
				TESTPROG = ./myprog
				:execute test.aap test1 test2

			This command is useful when a recipe does not contain
			dependencies that interfere with sources and targets
			in the current recipe.  For example, to build a
			command the current recipe depends on.  For example,
			when the program "mytool" is required and it doesn't
			exist yet, execute a recipe to build and install it:

				@if not program_path("mytool"):
					:execute mytool.aap install
				:sys mytool

			Another example: build two variants:

				:execute build.aap GUI=motif
				:execute build.aap GUI=gtk

:exit			Quit executing recipes.  When used in build commands,
			the "finally" targets will still be executed.  But a
			":quit" or ":exit" in the commands of a "finally"
			target will quit further execution.

:export varname ...	When used at the toplevel, export variable "varname"
			with its current value to the recipe that uses the
			current recipe as a child or executes it.
			When used in build commands, export variable "varname"
			to the recipe or build commands that invoked and
			export to the toplevel of the current recipe.  Useful
			to pass a value to the "finally" target or remember a
			value for the next invocation.
			When the variable was assigned a value with "$=" the
			argument will be evaluated now.
			Note: When exporting a variable that contains the name
			of a file, a relative file name will not be valid in
			another directory.  When using these commands:
				:child dir/main.aap
				:cat $RESULT
			using the following in dir/main.aap causes trouble:
				RESULT = foo.txt bar.txt
				export RESULT
			Instead use:
				RESULT = foo.txt bar.txt
				RESULT = `aap_abspath(RESULT)`
				export RESULT


:global name ...	Define variable "name" to be global to other recipes.
			Even when "name" has been assigned a value, build
			commands (actions, dependencies or rules) will still
			use the value passed on by who invoked the build
			commands.  Example:
				CFLAGS = -O4
				:global CFLAGS
			This means that when the value of CFLAGS is changed
			this value will be used for build commands defined in
			this recipe.

:include [options] name
			Read recipe "name" as if it was included in the
			current recipe.  Does not change directory and file
			names are considered to be relative to the current
			recipe, not the included recipe.
			The "fetch" attribute can be used to specify a list
			of locations where the recipe can be fetched from.

			OPTIONS
			{q} {quiet}	don't give a warning for a file that
			                can't be read.


:local name ...		Define variable "name" to be local to this recipe.  It
			will not be passed on to child recipes.  Build commands
			defined in this recipe (actions, dependencies or rules)
			will use the value from the recipe instead of a value
			passed from who invoked the commands.

:mkdir [options] dir ...
			Create directory.  This fails when "dir" already
			exists and is not a directory.
			A "mode" attribute on a directory can be used to
			specify the protection flags for the new directory.
			Example:
				:mkdir {r} ~/secret/dir {mode = 0700}
			The default mode is 0644.  The effective umask may
			reset some of the bits though.

			OPTIONS
			{f} {force}	don't fail when a directory already
					exist; still fails when it is not a
					directory or could not be created
			{q} {quiet}	don't report created directories
			{r} {recursive}	also create intermediate directories,
					not just the deepest one

			Note: automatic creation of directories can be done by
			adding the {directory} attribute to a source item.

:mkdownload name file ...
			Generate a recipe "name" that downloads the specified
			files.  Each file must have a "fetch" attribute, which
			is used in the generated recipe.
			When the file "name" already exists it is overwritten
			(without warning).

			MD5 checksums are generated and used in the recipe to
			fetch a file only when the checksum differs.  Example
			of one item:
			  file = foobar.txt
			  @if get_md5(file) != "a5dba5bce69918c040703e9b8eb35f1d":
			      :fetch {fetch = ftp://foo.org/files/%file%} $file

			When there is a "fetch" attribute on "name", this will
			be used to add a ":recipe" command at the start of the
			generated recipe.

:move [options] from ... to
			Move files or directories.  Mostly like ":copy",
			except that the "from" files/directories are renamed
			or, when renaming isn't possible, copied and deleted.

			OPTIONS
			{f} {force}	forcefully overwrite an existing file
					or directory (default)
			{e} {exist} {exists}	don't overwrite an existing
					file or directory
			{i} {interactive}	before overwriting a local
					file, prompt for confirmation
					(currently doesn't work for remote
					files)
			{q} {quiet}	don't report moved files

:print [redir] [text...]

Print the arguments on stdout. Without arguments a line feed is produced. $var items are expanded, otherwise the arguments are produced literally, including quotes:
	:print "hello"
results in:

"hello"

Leading white space is skipped, but white space in between arguments is kept. To produce leading white space start with the "empty" variable:
	:print $empty   indented text
results in:

indented text

When used in a pipe the stdin variable holds the input.

See here for [redir].


:proxy [protocol] {address}
			Specify a proxy server.  Examples:

			    :proxy ftp ftp://ftp.proxy.net:1234
			    :proxy http://www.someproxy.com:1080
			
			The [protocol] can be "ftp", "http" or "gopher".  When
			omitted "http" is used.  Case doesn't matter.
		        
			The {address} is a URL with the port number included.
			The result of this command is that an environment
			variable is set, as the Python library "urllib"
			requires.  Therefore it must be done early in the
			startup phase, before accessing the internet.


:publish file ...
:publish {attribute} ... file ...
			Publish the files mentioned according to their
			"publish" or "commit" attribute.
			Creates directories when needed (for CVS only one
			level).

:publishall file ...
			Like ":publish" but also remove files that are not
			an argument.  Careful!

:python			
    python-commands	A block of Python code.  The block ends when the indent
			drops to the level of ":python" or below.

:python  {term}
python-commands
   {term}		A block of Python code.  The block ends when {term} is
			found on a line by itself.  The Python commands may
			have any indent.
			White space before and after {term} is allowod and a
			comment after {term} is also allowed.  {term} can
			contain any characters but no white space.

:quit			See ":exit".

:recipe {fetch = URL ... }
			Location of this recipe.  The "fetch" attribute is
			used like with ":child": a list of locations.  The
			first one that works is used.
			When aap was started with the "fetch" argument,
			fetch the recipe and restart reading it.  Using the
			"fetch" or "update" target causes this as well.
			The commands before ":recipe" have already been
			executed, thus this may cause a difference from
			executing the new recipe directly.  The values of
			variables are restored to the values before executing
			the recipe.
			Fetching the recipe is done only once per session.


:fetch file ...
			Fetch the files mentioned according to their
			"fetch" or "commit" attribute.  When a file does not
			have these attributes or fetching fails you will get
			an error message.
			Files that exist and have a "fetch" attribute with
			value "no" are skipped.
			The name "." can be used to update the current
			directory:
				:fetch . {fetch = cvs://$CVSROOT}
:fetch {attribute} ... file ...
			Like above, apply {attribute} to all following items.

:remove			Version control command, see Chapter 16.
:removeall		Version control command, see Chapter 16.
:reviseall		Version control command, see Chapter 16.

:rule tpat ... : spat ...
	commands
			Define a rule to build files matching the pattern
			"tpat" from a file matching "spat".
			There can be several "tpat" patterns, the rule is used
			if one of them matches.
			There can be several "spat" patterns, the rule is used
			if they all exist (or no better rule is found).
			When "commands" is missing this only defines that
			"tpat" depends on "spat".
			Can only be used at the toplevel.
			The "skip" attribute on 'tpat' can be used to skip
			certain matches.
			$target and $source can be used in "commands" for the
			actual file names.  $match is what the "%" in the
			pattern matched.
			Alternative: instead of matching the file name with a
			pattern, ":action" uses filetypes to specify commands.

:start cmds		Like ":sys" and ":system", but don't wait for the
			commands to finish.  Errors are ignored.
			Runs in the same terminal, which will cause problems
			when the command waits for input.  Open a new terminal
			to run that command in.  Example:

		:start xterm -e more README

			WARNING: Using ":start" probably makes your recipe
			non-portable.

:sys [options] cmds
:system [options] cmds
			Execute "cmds" as system (shell) commands.  Example:

		:system filter <foo >bar
		:sys echo one
			two

			The following lines with more indent are appended,
			replacing the indent with a single space.  Example:

		:sys echo one
			two

			This echos "one two".

			Options:
			    {i} or {interactive}: don't log output (see below)
			    {q} or {quiet}: Don't echo the command
			    {l} or {log}: Redirect all output to the log file,
			                  do not echo it
			{interactive} and {log} cannot be used at the same
			time.

			Output is logged by default.  If this is undesirable
			(e.g., when starting an interactive command) prepend
			"{i}" or "{interactive}" to the command.  It will be
			removed before executing it.  Example:

		:system {i} vi bugreport

			When the "async" variable is set and it is not empty,
			":sys" works like "start", except that consecutive
			commands are executed all at once in one shell.

			WARNING: Using ":sys" or ":system" probably makes your
			recipe non-portable.

:syseval [redir] command
			Execute shell command "command" and write its output
			to stdout.  Only stdout of the command is captured.
			When {stderr} is just after the command name, stderr
			is also captured.  Example:

				:syseval hostname | :assign HOSTNAME

			When used in a pipe, the stdin is passed to the
			command.  Example:

				:print $var | :syseval sort | :assign var

			Note the difference with the ":sys" command:
			redirection in ":sys" is handled by the shell, for
			":syseval" it is handled by aap.

			When executing the command fails, the result is empty.
			The exit value of the command is available in $exit.

			WARNING: Using ":syseval" probably makes your recipe
			non-portable.

:syspath path arg ...
			Use "path" as a colon separated list of commands, use
			the first one that works.
			When %s appears in "path", it is replaced with the
			arguments.  If it does not appear, the arguments are
			appended.
			Other appearences of % in "path" are removed, thereby
			reducing %% to % and %: to : while avoiding their
			special meaning.
			Don't forget that "path" must be one argument, use
			quotes around it to include white space.
			Example:

		:syspath 'vim:vi:emacs' foobar.txt

			Output is not logged.
			Note: on MS-Windows it's not possible to detect if a
			command worked, the first item in the path will always
			be used.

			WARNING: Using ":syspath" probably makes your recipe
			non-portable.

:tag			Version control command, see Chapter 16.
:tagall			Version control command, see Chapter 16.

:tee [redir] fname ...
			Write stdin to each file in the argument list and also
			write it to stdout.  This works like a T shaped
			connection in a water pipe.  Example:

			:cat file1 file2 | :tee totfile | :assign foo

:touch [options] name ...
			Update timestamp of file or directory "name".

			OPTIONS
			{f} {force}	create the file when it doesn't exist
			{e} {exist}	create the file when it doesn't exist,
					don't update timestamp when the file
					already exists
			If "name" doesn't exist and {force} and {exist} are
			not present the command fails.
			If "name" doesn't exist and {force} or {exist} is
			present an empty file will be created.
			If "name" does exist and {exist} is present nothing
			happens.
			A "directory" attribute can be used to specify a
			non-existing "name" is to be created as a directory.
			There is no check if an existing "name" actually is a
			directory.
			A "mode" attribute can be used to specify the mode
			with which a new file or directory is to be created.
			The value is in the usual octal form, e.g., "0644".

:unlock			Version control command, see Chapter 16.
:unlockall		Version control command, see Chapter 16.

:update [{force}] target ...
			Update "target" now, if it is outdated or when
			"{force}" is used.
			One or more targets can be specified, each will be
			updated.
			When this appears at the top level, a dependency or
			rule for the target must already have been specified,
			there is no look-ahead.

:verscont		Version control command, see Chapter 16.

Common arguments for Commands

[redir]

Redirect the output of a command. Can be one of these items:

> fnamewrite output to file "fname"; fails when "fname" already exists
>! fnamewrite output to file "fname"; overwrite an existing file
>> fnameappend output to file "fname"; create the file if it does not exist yet
| commandpipe 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".

			For authentication the ~/.netrc file is used if
			possible (unfortunately, the Python netrc module has a
			bug that prevents it from understanding many netrc
			files).

			Alternatively, login name and password can be
			specified just before the machine name:
				ftp://user@machine/path
				ftp://user:password@machine/path
			When ":password" is omitted, you will be prompted for
			entering the password.
			Either way: ftp sends passwords literally over the
			net, thus this is not secure!  Should use "scp://"
			instead.

scp://machine/path	SCP protocol (using SSH, secure shell).
			Requires the "scp" program installed.
			Additionally a user name can be specified:
				scp://user@machine/path
			"path" is a relative path to the directory where "ssh"
			logs in to.  To use an absolute path prepend a slash:
				scp://machine//path
			The resulting path for the "scp" command uses a ":"
			instead of the first slash.