<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 8. Filetypes and Actions</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="tutorial.html" title="Part I. Tutorial"><link rel="prev" href="tutor-cvs.html" title="Chapter 7. Version Control with CVS"><link rel="next" href="tutor-include.html" title="Chapter 9. More Than One Recipe"></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="tutor-cvs.html">Prev</a></td><td align="center" class="center">Tutorial</td><td align="right" class="right"><a accesskey="n" href="tutor-include.html">Next</a></td></tr></tbody></table><hr><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="tutor-actions"></a>Chapter 8. Filetypes and Actions</h2></div></div></div><p>
A-A-P can recognize what the type of a file is, either by looking at the file
name or by inspecting the contents of the file. The filetype can then be
used to decide how to perform an action with the file.
</p><h2><a name="id2629545"></a>A New Type of File</h2><p>
Suppose you are using the "foo" programming language and want to use A-A-P to
compile your programs. Once this is has been setup you can compile
"hello.foo" into the "hello" program with a simple recipe:
</p><pre class="programlisting">
:program hello : hello.foo
</pre><p>
You need to explain <span class="application">Aap</span> how to deal with "foo" files. This is done with
a recipe:
</p><pre class="programlisting">
:filetype
suffix foo foo
:action compile foo
:sys foocomp $?FOOFLAGS $source -o $target
:route foo object
compile
</pre><p>
For Unix, write this recipe as "/usr/local/share/aap/startup/foo.aap" or
"~/.aap/startup/foo.aap". The recipes in these "startup" directories are
always read when <span class="application">Aap</span> starts up.
</p><p>
Now try it out, using the simple recipe at the top as "main.aap":
</p><div class="literallayout"><p> % <strong class="userinput"><code>aap</code></strong><br>
Aap: foocomp hello.foo -o build-FreeBSD4_5_RELEASE/hello.o<br>
Aap: cc -L/usr/local/lib -g -O2 -o hello build-FreeBSD4_5_RELEASE/hello.o<br>
% </p></div><p>
The "foo.aap" recipe does three things:
</p><div class="orderedlist"><ol type="1"><li><p>
The <code class="computeroutput">:filetype</code> command is used to tell A-A-P to recognize
your "hello.foo" file as being a "foo" file.
</p></li><li><p>
The <code class="computeroutput">:action</code> command is used to specify how the "foocomp"
compiler is used to compile a "foo" program into an object file.
The user can set the FOOFLAGS variable to options he wants to use.
The convention is that the option variable is in uppercase, starts with the
filetype and ends in "FLAGS".
</p></li><li><p>
The <code class="computeroutput">:route</code> command is used to specify which actions are to
be used to turn a "foo" file into an "object" file.
</p></li></ol></div><p>
</p><h2><a name="id2630731"></a>Defining a Filetype by Suffix</h2><p>
The <code class="computeroutput">:filetype</code> command is followed by the line "suffix foo
foo". The first word "suffix" means that recognizing is done by the suffix of
the file name (the suffix is what comes after the last dot in the name).
The second word is the suffix and the third word is the type. Quite often the
type is equal to the suffix, but not always. Here are a few more examples of
lines used with <code class="computeroutput">:filetype</code>:
</p><pre class="programlisting">
:filetype
suffix fooh foo
suffix bash sh
</pre><p>
It is also possible to recognize a file by matching the name with a pattern,
checking the contents of the file or using a Python script. See the user
manual.
</p><h2><a name="id2630758"></a>Defining a Compile Action</h2><p>
The lower half of "foo.aap" specifies the compile action for the "foo"
filetype:
</p><pre class="programlisting">
:action compile foo
:sys foocomp $source -o $target
</pre><p>
The <code class="computeroutput">:action</code> command has two arguments. The first one
specifies the kind of action that is being defined. In this case "compile".
This action is used to make an object file from a source file. The second
argument specifies the type of source file this action is used for, in this
case "foo".
</p><p>
Below the <code class="computeroutput">:action</code> line the build commands are specified. In
this case just one, there could be more.
The <code class="computeroutput">:sys</code> command invokes an exteral program, "foocomp", and
passes the arguments. In an action <code class="computeroutput">$source</code> is expanded to
the source of the action and <code class="computeroutput">$target</code> to the target. These
are obtained from the <code class="computeroutput">:do</code> command that invokes the action.
Example:
</p><pre class="programlisting">
:do compile {target = `src2obj("main.foo")`} main.foo
</pre><p>
This <code class="computeroutput">:do</code> command invokes the compile action, specified with
its first argument. The target is specified as an attribute to the action,
the source is the following argument "main.foo".
When executing the <code class="computeroutput">:do</code> command the filetype of "main.foo"
is detected to be "foo", resulting in the compile action for "foo" to be
invoked. In the build command of the action
<code class="computeroutput">$source</code> and <code class="computeroutput">$target</code> are replaced,
resulting in:
</p><pre class="programlisting">
:sys foocomp main.foo -o `src2obj("main.foo")`
</pre><p>
Note that in many cases <code class="computeroutput">$target</code> is passed implicitly from a
dependency and does not appear in the <code class="computeroutput">:do</code> command argument.
</p><h2><a name="id2630862"></a>Another Use of Filetypes</h2><p>
When building a program you often want to include the date and time when it
was built. A simple way of doing this is creating a source file "version.c"
that contains the timestamp. This file needs to be compiled every time your
program is built. Here is an example how this can be done:
</p><pre class="programlisting">
1 :program prog : main.c work.c
2
3 :attr prog {filetype = myprog}
4
5 :action build myprog object
6 version_obj = `src2obj("version.c")`
7 :do compile {target = $version_obj} version.c
8 :do build {filetype = program} $source $version_obj
</pre><p>
The target "prog" is explicitly given a different filetype in line 3. The
default filetype for a program is "program", here it is set to "myprog". This
allows us to specify a different build action for "prog".
</p><p>
Write the recipe as "main.aap" (without the line numbers) and execute it with
<strong class="userinput"><code>aap</code></strong>. The first time all the files will be compiled and linked
together. Executing <strong class="userinput"><code>aap</code></strong> again will do nothing. Thus the
timestamp used in "version.c" will not be updated if the files were not
changed. If you now make a change in "main.c" and run <strong class="userinput"><code>aap</code></strong> you
will see that both "main.c" and "version.c" are compiled.
</p><p>
The <code class="computeroutput">:action</code> command in line 5 has three arguments. The
first one "build" is the kind of action, like before. The second argument
"myprog" specifies the target filetype, the third one "object" the source
filetype. Thus the template is:
</p><div class="literallayout"><p> <code class="computeroutput">:action</code> kind-of-action target-filetype source-filetype<br>
</p></div><p>
This order may seem a bit strange. Remember that putting the target left of
the source also happens in a dependency and an assignment.
</p><p>
There are three commands for the build action, lines 6 to 8. The first one
assigns the name of the object file for "version.c" to
<code class="literal">version_obj</code>. "version.c" was not included in the
<code class="literal">:program</code> command at
the top, it is compiled here explicitly in line 7. This is what makes sure
"version.c" is compiled each time "prog" is built. The other source files
will be compiled with the default rules for <code class="literal">:command</code>.
</p><p>
Finally the <code class="computeroutput">:do build</code> command in line 8 invokes the build
action to link all the object files together. Note that the filetype for the
build action is explicitly defined to "program". This is required for this
<code class="computeroutput">:do</code> command to use the default action for a program target.
Otherwise the action would invoke itself, since the filetype for $target is
"myprog".
</p><p>
For more information about customizing filetype detection and actions see
<a href="user-filetype.html" title="Chapter 28. Customizing Filetype Detection and Actions">Chapter 28, <i>Customizing Filetype Detection and Actions</i></a>.
</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutor-cvs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="tutorial.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="tutor-include.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 7. Version Control with CVS </td><td width="20%" align="center"><a accesskey="h" href="index.html">
Contents</a></td><td width="40%" align="right" valign="top"> Chapter 9. More Than One Recipe</td></tr></table></div></body></html>
