<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 37. Attributes</title><meta name="generator" content="DocBook XSL Stylesheets V1.71.1"><link rel="start" href="index.html" title="A-A-P Recipe Executive"><link rel="up" href="reference.html" title="Part III. Reference Manual"><link rel="prev" href="ref-assign.html" title="Chapter 36. Assignments"><link rel="next" href="ref-filetype.html" title="Chapter 38. Filetype Detection"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table width="100%" id="navtable"><tbody><tr><td align="left" class="left" width="33%"><b><a href="http://www.a-a-p.org">A-A-P home page</a></b></td><td align="center" class="center" width="34%"><b><a href="index.html">A-A-P Recipe Executive</a></b></td><td align="right" class="right" width="33%"></td></tr><tr><td align="left" class="left"><a accesskey="p" href="ref-assign.html">Prev</a></td><td align="center" class="center">Reference Manual</td><td align="right" class="right"><a accesskey="n" href="ref-filetype.html">Next</a></td></tr></tbody></table><hr><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-attributes"></a>Chapter 37. Attributes</h2></div></div></div><p>
Attributes can be added to an item with the
<a href="ref-commands.html#cmd-attr">:attr</a> command and by using them
in a dependency or rule. Note that an assignment does not directly associate
the attribute with a node. This only happens when the variable is used in an
<a href="ref-commands.html#cmd-attr">:attr</a> command or a dependency.
</p><p>
The form for an attribute is:
</p><div class="literallayout"><p> {name = value} </p></div><p>
</p><p>
"value" is expanded like other items, with the addition that "}" cannot appear
outside of quotes.
</p><p>
This form is also possible and uses the default value of 1:
</p><div class="literallayout"><p> {name} </p></div><p>
Examples:
</p><pre class="programlisting">
bar : thatfile {check = $MYCHECK}
foo {virtual} : somefile
</pre><p>
The "virtual" attribute is used for targets that don't exist (as file or
directory) but are used for selecting the dependency to be built. These
targets have the "virtual" attribute set by default:
</p><div class="table"><a name="virtual-targets"></a><p class="title"><b>Table 37.1. Virtual Targets</b></p><div class="table-contents"><table summary="Virtual Targets" border="0"><colgroup><col width="150"><col></colgroup><thead><tr><th>Target</th><th>Commonly used for</th></tr></thead><tbody><tr><td>all</td><td>build the default targets</td></tr><tr><td>clean</td><td>remove generated files that are not distributed
(added automatically)</td></tr><tr><td>cleanmore</td><td>remove all generated files (added automatically)</td></tr><tr><td>cleanALL</td><td>remove all generated files, AAPDIR and build-*
directories below the toplevel recipe</td></tr><tr><td> </td><td> </td></tr><tr><td>test</td><td>run tests</td></tr><tr><td>check</td><td>same as "test"</td></tr><tr><td>install</td><td>build and install for use (added automatically)</td></tr><tr><td>uninstall</td><td>uninstall for use (added automatically)</td></tr><tr><td>tryout</td><td>build and install for trying out</td></tr><tr><td> </td><td> </td></tr><tr><td>reference </td><td>generate or update the cross-reference database</td></tr><tr><td> </td><td> </td></tr><tr><td>fetch</td><td>obtain the latest version of each file</td></tr><tr><td>update</td><td>fetch and build the default targets</td></tr><tr><td> </td><td> </td></tr><tr><td>checkout</td><td>checkout (and lock) from version control system</td></tr><tr><td>commit</td><td>commit changes to VCS without unlocking</td></tr><tr><td>checkin</td><td>checkin and unlock to VCS</td></tr><tr><td>unlock</td><td>unlock files from a VCS</td></tr><tr><td>add</td><td>add new files to VCS</td></tr><tr><td>remove</td><td>remove deleted files from VCS</td></tr><tr><td>revise</td><td>like checkin + remove</td></tr><tr><td>tag</td><td>add a tag to the current version</td></tr><tr><td> </td><td> </td></tr><tr><td>prepare</td><td>prepare for publishing (generated docs but no exe) </td></tr><tr><td>publish</td><td>distribute all files for the current version</td></tr><tr><td> </td><td> </td></tr><tr><td>finally</td><td>always executed last (using "aap finally" is uncommon)</td></tr></tbody></table></div></div><p><br class="table-break">
</p><p>
The targets marked with "(added automatically)" will be added by Aap if they
are not present. This is done for the toplevel and each child recipe.
</p><p>
These specific targets may have multiple build commands. They are all
executed to update the virtual target. Normally there is up to one target in
each (child) recipe.
</p><p>
Note that virtual targets are not related to a specific directory. Make sure
no other item in this recipe or any child recipe has the same name as the
virtual target to avoid confusion. Specifically using a directory "test"
while there also is a virtual target "test". Name the directory "testdir"
to avoid confusion.
</p><p>
The "comment" attribute can be used for targets that are to be specified at
the command line. "aap comment" will show them.
</p><p>
</p><div class="literallayout"><p> % <strong class="userinput"><code>aap comment</code></strong><br>
target "all": build everything<br>
target "foo": link the program </p></div><p>
</p><h2><a name="id2683390"></a>Sticky Attributes</h2><p>
When attributes are used in a rule or dependency, most of them are only used
for that dependency. But some attributes are "sticky": Once used for an item
they are used everywhere for that item. Sticky attributes are:
</p><div class="table"><a name="id2683396"></a><p class="title"><b>Table 37.2. Sticky attributes</b></p><div class="table-contents"><table summary="Sticky attributes" border="0"><colgroup><col width="100"><col></colgroup><tbody><tr><td>virtual</td><td>virtual target, not a file</td></tr><tr><td>remember</td><td>virtual target that is remembered</td></tr><tr><td>directory</td><td>item is a directory</td></tr><tr><td>filetype</td><td>type of file</td></tr><tr><td>constant</td><td>file contents never changes</td></tr><tr><td>fetch</td><td>list of locations where to fetch from (first
one that works is used)</td></tr><tr><td>commit</td><td>list of locations for VCS</td></tr><tr><td>publish</td><td>list of locations to publish to (they are all used)</td></tr><tr><td>force</td><td>rebuild a target always</td></tr><tr><td>depdir</td><td>directory to put an automatically generated
dependency file in; when omitted $BDIR is used</td></tr><tr><td>var_BDIR</td><td>directory to put the related object or
generated file in; when omitted $BDIR is used</td></tr><tr><td>signfile</td><td>file used to store signatures for this target</td></tr></tbody></table></div></div><p><br class="table-break">
</p><h2><a name="check-attribute"></a>The check attribute</h2><p>
The check attribute is used to specify what kind of signature is used for an
item.
</p><p>
The default check for a file that was changed is an md5 checksum. Each time a
recipe is executed the checksums for the relevant items are computed and
stored in the file "AAPDIR/sign". The next time the recipe is executed the
current and the old checksums are compared. When they are different, the
build commands are executed. This means that when you put back an old version
of a file, rebuilding will take place even though the timestamp of the source
might be older than the target.
</p><p>
Another check can be specified with {check = name}, where "name" is the kind
of check. Example:
</p><pre class="programlisting">
foo.txt : foo.db {check = time}
:sys db_extract $source >$target
</pre><p>
The default check is "md5". This is specified with the $DEFAULTCHECK
variable. You can set this variable to "time" or "newer" to use timestamps
instead of md5 signatures. The value of $DEFAULTCHECK is used when a node
does not have a "check" attribute.
</p><p>
</p><div class="table"><a name="id2683699"></a><p class="title"><b>Table 37.3. supported check attribute values</b></p><div class="table-contents"><table summary="supported check attribute values" border="0"><colgroup><col width="100"><col></colgroup><tbody><tr><td>time</td><td>Build the target when the timestamp of the source
differs from the last time the target was
built.</td></tr><tr><td>newer</td><td>Build the target if its timestamp is older than the
timestamp of the source. This is what the good old
"make" program uses.</td></tr><tr><td>md5</td><td>Build the target if the md5 checksum of the source
differs from the last time the target was built.
This is the default.</td></tr><tr><td>c_md5</td><td>Like "md5", but ignore changes in comments and amount
of white space. Appropriate for C programs. Slows
down computations considerably.</td></tr><tr><td>none</td><td>Don't check time or contents, only existence. Used
for directories.</td></tr></tbody></table></div></div><p><br class="table-break">
</p><p>
When mixing "newer" with other methods, the build rules are executed if the
target is older than the source with the "newer" check, or when one of the
signatures for the other items differs.
</p><p>
The "AAPDIR/sign" file is normally stored in the directory of the target. This
means it will be found even when using several recipes that produce the same
target. But for targets that get installed in system directories (use an
absolute path), virtual targets and remote targets this is avoided. For these
targets the "AAPDIR/sign" file is stored in the directory of the recipe that
specifies how to build the target.
</p><p>
To overrule the directory where the "sign" file is written, use the attribute
{signdirectory = name} for the target.
To overrule the file where the signatures are written, use the attribute
{signfile = name} for the target. "name" cannot end in "sign".
</p><h2><a name="id2683780"></a>Handling Circular Dependencies</h2><p>
Two attributes can be used to handle circular dependencies:
</p><div class="informaltable"><table border="0"><colgroup><col width="100"><col></colgroup><tbody><tr><td>update</td><td>Can be set to "no" to avoid updating a source that a
target depends on.</td></tr><tr><td>recursive</td><td>Can be set to a number, which indicates the maximum
recursive depth allowed.</td></tr></tbody></table></div><p>
</p><p>
The use can best be illustrated with an example:
</p><pre class="programlisting">
:attr {recursive = 3} index file.out
index: file.out {update = no}
# Get the current checksum for the index file.
@sum = get_md5("index")
# Generate the new index file from the output file.
:system wc file.out >$target
# Update the output file if the index file changed.
@if sum != get_md5("index"):
:update file.out
file.out: file.in index {update = no}
# Make sure index exists.
@if not os.path.exists("index"):
:print empty > index
# Generate the output file.
:cat $source >! $target
# Need to generate the index file again.
:update index
all: file.out
</pre><p>
The goal is to produce the file "file.out". It is created from "test.in" and
"index". The "index" is created from "file.out", which includes the "index"
file, thus a circular dependency exists. The idea is to repeat generating
"file.out" until it no longer changes.
</p><p>
The "recursive" attribute is set to 3 for "index" and "file.out". This allows
rebuilding "file.out" three times before giving up.
</p><p>
In the first dependency the "{update = no}" attribute is used to avoid
updating "file.out". The build commands first update the "index" file before
using
<a href="ref-commands.html#cmd-update">:update</a> to update "file.out". But this is
only done when the index file has changed. That is where the circular
dependency stops: When the
generated index file no longer changes.
</p><p>
In the second dependency a similar thing is done: The "index" file is not
updated before executing the build commands but as part of the build commands.
</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref-assign.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref-filetype.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 36. Assignments </td><td width="20%" align="center"><a accesskey="h" href="index.html">
Contents</a></td><td width="40%" align="right" valign="top"> Chapter 38. Filetype Detection</td></tr></table></div></body></html>
