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

  Part of the A-A-P recipe executive: Differences with make

  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

-->

<para>
An &Aap; recipe has the same structure as a Makefile.
But there are many differences.
The most important and unexpected ones are mentioned here.
</para>

<bridgehead>Build if file does not exist</bridgehead>

<para>
In a Makefile a dependency with only a target is not executed if the target
exists.
With &Aap; the build commands will be executed in more situations:
<itemizedlist>
  <listitem><para>when the build commands were never executed</para></listitem>
  <listitem><para>when the build commands have changed</para></listitem>
</itemizedlist>

For example, this dependency is often used in a Makefile to create a symbolic
link when it doesn't exist yet:
</para>

<programlisting>
    gvim:
        ln -s vim gvim
</programlisting>

<para>
  The &Aap; recipe for this would be:
</para>

<programlisting>
    gvim:
        :symlink vim gvim
</programlisting>

<para>
When running &Aap; with this recipe for the first time and the "gvim" link
already exists, you will get an error message.
</para>

<para>
To avoid this problem, set the buildcheck attribute to an empty string:
</para>

<programlisting>
    gvim: {buildcheck=}
        :symlink vim gvim
</programlisting>

<para>
Note: if the symbolic link exists but the file that it points to doesn't exist
you still get an error.  That's probably what you want.
</para>

<bridgehead>Use Of Environment Variables</bridgehead>

<para>
The "make" program uses all environment variables for variables in the
Makefile.  This can cause unexpected results, because you may have a large
number of environment variables and some of them you didn't set yourself thus
don't even know about them.
</para>

<para>
&Aap; does not use environment variables for recipe variables.
A few environment variables are explicitly used.  For example, $PATH is used
to locate programs.  To access an environment variable Python code must be
used.  The "os.environ" dictionary stores them.  Example:
</para>

<programlisting>
        Home = `os.environ.get("HOME")`
</programlisting>

<para>
  Note that some systems are case sensitive (e.g., Unix), some systems are not
  (e.g., MS-Windows).
</para>


<bridgehead>Signatures Instead Of Timestamps</bridgehead>

<para>
Make checks for outdated files by comparing timestamps.
A target file is considered out-of-date when it's older than one of the source
files.
This means that Make will not notice a source file that was changed back to an
older version.  And Make has big problems when a source file has a timestamp
in the future (happens when the system clock is turned back for some reason).
The target will always be older, thus Make will build it every time.
</para>

<para>
  The default check for &Aap; is to use MD5 signatures.
  This means a target is considered out-of-date if one of the source files is
  different from when this target was last build.
  Additionally, a signature is made for the build commands.  If you change the
  commands that build the target it will also be considered out-of-date.
  Mostly this means &Aap; will build the target in many more situations.
</para>

<para>
If you want &Aap; to use timestamps like Make does, set the
<link linkend="var-defaultcheck">$DEFAULTCHECK</link> variable to "newer".
Also see the <link linkend="check-attribute">check</link> attribute, it can be
used to change the check for a specific dependency.
</para>


