A-A-P Commands

A-A-P home page | A-A-P Recipe Executive
--- | ---
Prev |  | Next

# 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:

  > `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".

    			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.

Prev | Contents | Next
Recipe Syntax and Semantics | Up | Common Attributes