<!--  vim: set sw=2 sts=2 et ft=docbk:

  Part of the A-A-P recipe executive: Aap Command Line Arguments

  Copyright (C) 2002-2003 Stichting NLnet Labs
  Permission to copy and use this file is specified in the file COPYING.
  If this file is missing you can find it here: http://www.a-a-p.org/COPYING

-->

<bridgehead>Three Kinds Of Arguments</bridgehead>

<para>
<userinput>
  aap [option]... [assignment]... [target]...
</userinput>
</para>
<para>
The order of arguments is irrelevant.
Options are explained in the next section.
</para>

<para>
Assignments take the form "VAR=value".  This works just like putting this at
the top of the main recipe used.  But the shell used to start Aap may require
escaping special characters, such as spaces.  Putting the argument in double
quotes often works (but not always).
</para>

<para>
Targets specify what needs to be done.
If no target is given, one of the targets in the recipe is executed, see
<link linkend="recipe-execution"> Recipe Execution Details</link>.
</para>

<para>
Variables in the targets are expanded.  This makes it possible to build a
target in a directory whose name is set in the recipe.  For example, to build
a target in $BDIR:
</para>
<para>
<programlisting>
       aap '$BDIR/foo.o'
</programlisting>
</para>
<para>
Note: you must make sure that the variable is not expanded by the shell.  In
the example this is done by putting the argument in single quotes.  This works
for most Unix shells.  To use a target with a $ character in the name use $($)
in place of the $.
</para>


<bridgehead id="ref-options">Options</bridgehead>

<para>
An option must appear only once, except for the ones that are noted to be
allowed multiple times.

<variablelist>

  <varlistentry id='option-nocache'>
    <term><cmdsynopsis>
      <command>-a</command>
      <command>--nocache</command>
    </cmdsynopsis></term>
    <listitem>
      <para>
       For a remote file, don't use a cached copy. Download it once for this
       invocation.  Note that the file may be downloaded anyway, because it is
       not always possible to check if the cached copy is still valid.  Use
       the {usecache} or {constant} attribute on a file to use the cached
       version whenever possible, see <link linkend="cmd-fetch">:fetch</link>.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id='option-command'>
    <term><cmdsynopsis>
      <command>-c</command>
      <arg choice='plain'><replaceable>command</replaceable></arg>
      <command>--command</command>
      <arg choice='plain'><replaceable>command</replaceable></arg>
    </cmdsynopsis></term>
    <listitem>
      <para>
        After reading the recipe, execute <replaceable>command</replaceable>.  May appear
        several times, all the commands are executed.
      </para>

      <para>
        Commands to be executed can be specified on the command line.
        This is useful, for example, to fetch individual files:
        </para>

      <para>
<programlisting>
        aap -c ":fetch main.c"
        aap -c ":commit common.h"
</programlisting>
        </para>

        <para>
        Since the recipe is first read (and all child recipes), the
        attributes that are given to "main.c" will be used for
        fetching.
        </para>

      <para>
        The commands are executed before updating targets.
        When no target is specified nothing is built, only the
        specified commands are executed.  But the toplevel commands in
        the recipe are always executed, before executing the command
        arguments.
        </para>

      <para>
        Keep in mind that the shell must not change the argument, use
        single quotes to avoid $VAR to be expanded by the shell:
        </para>

      <para>
<programlisting>
        aap -c ':print $SOURCE'
</programlisting>
        </para>

    </listitem>
  </varlistentry>


  <varlistentry id='option-changed'>
    <term><cmdsynopsis>
      <command>--changed</command>
      <arg choice='plain'><replaceable>file</replaceable></arg>
    </cmdsynopsis></term>
    <listitem>
      <para>
        The file <replaceable>file</replaceable> is considered changed, no matter whether
        it was
        really changed.  Targets build from <replaceable>file</replaceable> will also be
        considered changed, recursively.
        </para>
        <para>
          Similar to the recipe command
          <link linkend="cmd-changed">:changed</link> <replaceable>file</replaceable>.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id='option-contents'>
    <term><cmdsynopsis>
      <command>-C</command>
      <command>--contents</command>
    </cmdsynopsis></term>
    <listitem>
      <para>
        Only take action when file contents was changed, not when build
        commands or attributes changed.
      </para>
      <para>
        For normal dependencies the buildcheck is ignored.  This means
        that the build commands can be changed without causing them to
        be executed.  The commands are executed anyway when one of the
        sources is out-of-date.
      </para>
      <para>
        For publishing the "publish" attribute is ignored.  The file
        is still published when its contents changed since the last
        time it was published to any destination, or if it was never
        published.
      </para>
      <para>
        The signatures are updated as usual (unless --nobuild is used as
        well).  Thus the new buildcheck and "publish" attribute are stored.
        This is useful if the buildcheck or "publish" argument changed in a
        way that you know does not require building or publishing.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id='option-debug'>
    <term><cmdsynopsis>
      <command>-d</command>
      <arg choice='plain'><replaceable>flags</replaceable></arg>
      <command>--debug</command>
      <arg choice='plain'><replaceable>flags</replaceable></arg>
    </cmdsynopsis></term>
    <listitem>
      <para>
      Switch on debugging for <replaceable>flags</replaceable>.  Not implemented yet.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id='option-recipe'>
    <term><cmdsynopsis>
      <command>-f</command>
      <arg choice='plain'><replaceable>file</replaceable></arg>
      <command>--recipe</command>
      <arg choice='plain'><replaceable>file</replaceable></arg>
    </cmdsynopsis></term>
    <listitem>
      <para>
       Specify the main recipe to read.  When an URL is used the recipe is
       downloaded to the current directory before it is used.  The name is the
       last part of the path.  If it already exists the user is asked whether
       it should be overwritten.  Example:
      </para>
      <literallayout>        cd /usr/local/share/vim/vim62/runtime
        aap -f ftp://ftp.vim.org/pub/vim/runtime/main.aap </literallayout>
      <para>
        When the file is "NONE" no recipe is read.  This is useful when only a
        command is to be executed.  Example:
      </para>
      <literallayout>        aap -f NONE -c ':print $AAP' </literallayout>
    </listitem>
  </varlistentry>

  <varlistentry id='option-force'>
    <term><cmdsynopsis>
      <command>-F</command>
      <command>--force</command>
    </cmdsynopsis></term>
    <listitem>
      <para>
       Force rebuilding everything.
       That a target is already up-to-date is ignored.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id='option-help'>
    <term><cmdsynopsis>
      <command>-h</command>
      <command>--help</command>
    </cmdsynopsis></term>
    <listitem>
      <para>
        Print a help message and exit.
        Does not read a recipe.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id='option-include'>
    <term><cmdsynopsis>
      <command>-I</command>
      <arg choice='plain'><replaceable>directory</replaceable></arg>
      <command>--include</command>
      <arg choice='plain'><replaceable>directory</replaceable></arg>
    </cmdsynopsis></term>
    <listitem>
      <para>
        Add a directory to search for included recipes.
        This option may appear multiple times.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id='option-install'>
    <term><cmdsynopsis>
      <command>--install</command>
      <arg choice='plain'><replaceable>package</replaceable></arg>
    </cmdsynopsis></term>
    <listitem>
      <para>
        Install the package <replaceable>package</replaceable>.  Only works for those
        packages that are supported, such as "cvs" and "rcp".
      </para>
      <para>
      Does not read a recipe in the usual way, only the specified package is
      installed.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id='option-jobs'>
    <term><cmdsynopsis>
      <command>-j</command>
      <arg choice='plain'><replaceable>number</replaceable></arg>
      <command>--jobs</command>
      <arg choice='plain'><replaceable>number</replaceable></arg>
    </cmdsynopsis></term>
    <listitem>
      <para>
        Maximum number of parallel jobs.  Not implemented yet.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id='option-continue'>
    <term><cmdsynopsis>
      <command>-k</command>
      <command>--continue</command>
    </cmdsynopsis></term>
    <listitem>
      <para>
        Continue after encountering an error.
        </para>
        <para>
        When an error is detected in a block of build commands, the execution
        of that block is aborted.  Building continues for other targets, but a
        target that depends on a target that failed to build will not be
        build.
        </para>
        <para>
        To continue execution after an error in the same block of commands
        use the Python ":try" statement.  Example:
        <programlisting>
        @try:
            :print  this is an $error
        @except UserError, e:
            :print caught error: `str(e)`
</programlisting>
        </para>
        <para>
        Not fully implemented, still stops at some errors.
        Careful: When an error has side effects strange things may happen.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id='option-local'>
    <term><cmdsynopsis>
      <command>-l</command>
      <command>--local</command>
    </cmdsynopsis></term>
    <listitem>
      <para>
         Do not recurse into subdirectories.  Only applies to "add" and
         "remove" targets on the command line.  Also for "revise" for its
         remove action.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id='option-nobuild'>
    <term><cmdsynopsis>
      <command>-n</command>
      <command>--nobuild</command>
    </cmdsynopsis></term>
    <listitem>
      <para>
       Only print messages about what will be done, don't execute
        build rules.  Commands at the toplevel and commands to
        discover dependencies are executed, but system commands,
        commands that download, upload, write or delete files and
        version control commands are skipped.
        </para>
        <para>
          Note: since no files are downloaded,
          <link linkend="cmd-child">:child</link> commands won't
        work for not existing recipes.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id='option-nofetch-recipe'>
    <term><cmdsynopsis>
      <command>-N</command>
      <command>--nofetch-recipe</command>
    </cmdsynopsis></term>
    <listitem>
      <para>
        Do not fetch recipes when using the "fetch" and "update"
        targets.  Useful if the current recipe is to be used while
        files must be fetched.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id='option-profile'>
    <term><cmdsynopsis>
      <command>--profile</command>
      <arg choice='plain'><replaceable>file</replaceable></arg>
    </cmdsynopsis></term>
    <listitem>
      <para>
        Profile the execution of A-A-P and write the results in
        <replaceable>file</replaceable>.
        This file can then be examined with the standard Python module
        "pstats".  The PrintProfile.py script can be used for this (it is
        located with the other &Aap; modules).
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id='option-fetch-recipe'>
    <term><cmdsynopsis>
      <command>-R</command>
      <command>--fetch-recipe</command>
    </cmdsynopsis></term>
    <listitem>
      <para>
        Fetch the recipe and child recipes.  This is impled by using
        a "refresh", "fetch" or "update" target, unless
        "--nofetch-recipe" is used.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id='option-stop'>
    <term><cmdsynopsis>
      <command>-S</command>
      <command>--stop</command>
    </cmdsynopsis></term>
    <listitem>
      <para>
        Stop building after encountering an error.
        This is the default, thus this option has no effect.
        Also see <link linkend="option-continue">--continue</link>.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id='option-silent'>
    <term><cmdsynopsis>
      <command>-s</command>
      <command>--silent</command>
    </cmdsynopsis></term>
    <listitem>
      <para>
       Print less information, see <link linkend="var-message">$MESSAGE</link>.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id='option-touch'>
    <term><cmdsynopsis>
      <command>-t</command>
      <command>--touch</command>
    </cmdsynopsis></term>
    <listitem>
      <para>
         Update signatures on targets without executing build commands.
          After doing this the specified targets and intermediate
          results are considered up-to-date.
        </para>
        <para>
          Commands at the toplevel will be executed, except system
          commands, commands that write a file and version control
          commands.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id='option-up'>
    <term><cmdsynopsis>
      <command>-u</command>
      <command>--up</command>
      <command>--search-up</command>
    </cmdsynopsis></term>
    <listitem>
      <para>
        Search the directory tree upwards for the main.aap recipe.
        Useful when in a sub-directory of a large project, where the main.aap
        recipe is an unknown number of directory levels upwards.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id='option-version'>
    <term><cmdsynopsis>
      <command>-V</command>
      <command>--version</command>
    </cmdsynopsis></term>
    <listitem>
      <para>
        Print version information and exit.
        Does not read a recipe.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id='option-verbose'>
    <term><cmdsynopsis>
      <command>-v</command>
      <command>--verbose</command>
    </cmdsynopsis></term>
    <listitem>
      <para>
       Print more information, see <link linkend="var-message">$MESSAGE</link>.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry id='option-end'>
    <term><cmdsynopsis>
      <command>--</command>
    </cmdsynopsis></term>
    <listitem>
      <para>
          End of options, only targets and assignments follow.  Use this when
          a target starts with a "-".
      </para>
    </listitem>
  </varlistentry>

</variablelist>
</para>
