<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 31. Adding A Language Module</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="user.html" title="Part II. User Manual"><link rel="prev" href="user-tools.html" title="Chapter 30. Customizing Default Tools"><link rel="next" href="reference.html" title="Part III. Reference Manual"></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="user-tools.html">Prev</a></td><td align="center" class="center">User Manual</td><td align="right" class="right"><a accesskey="n" href="reference.html">Next</a></td></tr></tbody></table><hr><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="user-language"></a>Chapter 31. Adding A Language Module</h2></div></div></div><p>
This chapter explains how to add support for a language to <span class="application">Aap</span>.
Both for your own setup and for a module that is to be included in an <span class="application">Aap</span>
release.
</p><p>
Although the text explains modules for a language, this can also be used for
adding a module for other purposes. It is a generic method to have <span class="application">Aap</span>
load a module that defines actions, sets variables, etc.
</p><p>
In a recipe a module can be used with the
<a href="ref-commands.html#cmd-import">:import</a> command.
Thus when your recipe uses Java, you would add this line:
</p><pre class="programlisting">
:import java
</pre><p>
For the standard modules see <a href="ref-modules.html" title="Chapter 39. Standard Modules">Chapter 39, <i>Standard Modules</i></a>.
</p><h2><a name="id2663516"></a>Module Name</h2><p>
It is important to chose a good name for the module, because it must be
unique on your system. For a programming language simply use the name of
the language. For Java you would use "java", for the D language "d". In
case there are variants of a language that are different enough to justify
using a different module, add something to the name to make this clear.
You can use letters, digits and the underscore. Examples: "foo", "foo2004",
"foo_latest".
</p><p>
If you have a specific module with different functionality, you could
prepend "my". For example, "myjava".
</p><p>
After the module has been imported, the variables in it can be accessed
through the "m_name" scope, where "name" is the name of the module. For
example the variable "$m_d.DMD" holds the command used for the "d" language
to execute the compiler.
</p><p>
Note: It is not possible to have a variable and a scope with the same name.
Thus if you have a module called "foo", which uses the scope "m_foo", you
cannot have a variable "m_foo" anywhere in a recipe.
</p><p>
Since the modules are <span class="application">Aap</span> recipes the file names always end in ".aap".
</p><h2><a name="id2663542"></a>Module directories</h2><p>
Modules that are included with <span class="application">Aap</span> are located in the <span class="application">Aap</span> sub-directory
"modules". If you are working on a module that is to be submitted for a
next <span class="application">Aap</span> release you may also want to put the module there for testing.
But be aware that this directory may be overwritten or deleted when updating
<span class="application">Aap</span>!
</p><p>
Modules that you want to share with all users on your system should be
placed in a system-wide directory. For Unix this usually is
<code class="filename">/usr/local/share/aap/modules</code>. This can be changed with
<a href="ref-variables.html#var-aapsysdir">$AAPSYSDIR</a>.
</p><p>
Modules that you only use for yourself are placed in
<code class="filename">$HOME/.aap/modules</code> (for Unix and Mac OS X),
<code class="filename">$HOME/aap/modules/</code>,
<code class="filename">$HOMEDRIVE/$HOMEPATH/aap/modules/</code> or
<code class="filename">c:/aap/modules/</code> (MS-Windows).
</p><p>
If you only want to change a few settings after the module is loaded, you
can place these in the <code class="filename">modules2</code> directory. See
<a href="ref-commands.html#cmd-import">:import</a> for details.
</p><h2><a name="id2664308"></a>Parts Of A Module</h2><p>
In a module you will usually find these parts:
</p><div class="variablelist"><dl><dt><span class="term">(1) filetype recognition</span></dt><dd><p>How to recognize files used in the module. For a module
included with <span class="application">Aap</span> this is normally missing, since it can be added to
the generic Python filetype module.
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></dd><dt><span class="term">(2) default values</span></dt><dd><p>
Give default values to variables used in the commands further on. The
user can change these values if he needs to. It is a good habit to
put all specific command names, directories and arguments in a
variable.
</p></dd><dt><span class="term">(3) object file suffixes</span></dt><dd><p>
If the language uses different suffixes for object files, for static
or dynamic libraries, this can be specified.
See <a href="user-language.html#lang-suffix">below</a>.
</p></dd><dt><span class="term">(4) search for tools</span></dt><dd><p>
Usually there are different ways to invoke the compiler on different
platforms. And on one platforms various tools may be installed. The
<a href="ref-commands.html#cmd-toolsearch">:toolsearch</a> command is used to
locate the tools.
See <a href="user-language.html#lang-toolsearch">below</a>.
</p></dd><dt><span class="term">(5) actions, rules and routes</span></dt><dd><p>
The generic methods for compiling and building.
See <a href="user-language.html#lang-actions">below</a>.
</p></dd></dl></div><p>
</p><h2><a name="id2664412"></a>Example</h2><p>
This example is for the "D" language. This module is included with <span class="application">Aap</span>.
</p><pre class="programlisting">
# (1) Filetype recognition
:filetype
suffix d d
# (2) Default values
DMD = dmd
# (3) Object file suffixes
# dll and lib objects are equal to normal objects.
_top.D_LIBOBJSUF = $OBJSUF
_top.D_DLLOBJSUF = $OBJSUF
# (4) Search for tools
# Actions are installed for every toolchain that exists.
# The first one found sets $D_COMPILE_ACTION and friends.
:toolsearch dmd
# (5) Actions, Rules and Routes
# :do compile
:action compile object,libobject,dllobject,default d
@if not _no.get("target"):
target = `src2obj(fname)`
# Use the d_build action for building and also for :dll and :lib.
:attr {buildaction = d_build} $target
@if _no.get("D_COMPILE_ACTION"):
:do $D_COMPILE_ACTION {target = $target} $source
@else:
:sys $DMD $?DFLAGS -of$target -c $source
:rule {global} {default} %$OBJSUF : {buildcheck = $DMD $?DFLAGS } %.d
:do compile {target = $target} $source
# :do build for object files resulting from "d" source files.
:action d_build default
@if _no.get("D_BUILD_ACTION"):
:do $D_BUILD_ACTION {target = $target} $source
@else:
:sys $DMD $?DLINKFLAGS -of$target $source
# default route
:route {default} d object,libobject,dllobject
compile
</pre><h2><a name="lang-suffix"></a>Object File Suffixes</h2><p>
Many languages use the same object file suffixes as used for C: ".o" on Unix
and ".obj" on MS-Windows. But for some languages a different suffix is
used and the suffixes for building a static and shared library are
different.
</p><p>
The simplest example is when a language always uses the same suffix for all
kinds of object files. For example, the "d" language does not make a
difference between normal object files, static library objects, etc. This
can be specified like this:
</p><pre class="programlisting">
_top.D_DLLOBJSUF = $OBJSUF
_top.D_LIBOBJSUF = $OBJSUF
</pre><p>
Note that the "_top" scope is used. If this would be left out the variables
would only be set in the scope of the module and would not be available in
the user recipe.
</p><p>
The name of the variable is made from the filetype in upper case, and
underscore and the name of the generic variable.
The <a href="ref-python.html#python-src2obj">src2obj()</a> function will look for
these variables.
Note that the <span class="emphasis"><em>filetype</em></span> is used, not the module name!
</p><p>
An extreme example is when all suffixes are different:
</p><pre class="programlisting">
_top.FOO_OBJSUF = .fo
_top.FOO_DLLOBJSUF = .dfo
_top.FOO_LIBOBJSUF = .lfo
_top.FOO_LTOBJSUF = .tfo
</pre><p>
An advantage of using a different suffix for every type of object file is
that all types can be generated in the same directory.
</p><p>
If the compiler or linker does not support using different suffixes, but the
various object files are different, the user must make sure that the object
files are put in different build directories. This can be done by
specifying an attribute on the source files to use a different build
directory:
</p><pre class="programlisting">
:program foo : foo.c # uses $BDIR
:dll foo : foo.c {var_BDIR = $BDIR-dll}
:lib foo : foo.c {var_BDIR = $BDIR-lib}
</pre><h2><a name="lang-toolsearch"></a>Searching For Tools</h2><p>
When there is only one compiler that always uses the same (type of)
arguments you can simply invoke it directly from the actions in the module.
Otherwise, <span class="application">Aap</span> can search for tools that are currently installed.
The working of tools is explained in <a href="user-tools.html" title="Chapter 30. Customizing Default Tools">Chapter 30, <i>Customizing Default Tools</i></a>
</p><p>
As an example, let's look at how <span class="application">Aap</span> searches for C compilers:
</p><pre class="programlisting">
@if osname() == 'mswin':
:toolsearch msvc mingw gcc icc bcc
@elif osname() == 'os2':
:toolsearch icc gcc msvc
</pre><p>
The <a href="ref-commands.html#cmd-toolsearch">:toolsearch</a> command is used with a
list of tools that need to be checked for. The first tool for which the
exists() function returns True is then used. This works by setting
variables to the name of the action to be used. For example, the "msvc"
tool sets $C_COMPILE_ACTION to "compile_msvc".
</p><p>
The list of tools to be searched depends on the platform. Note that the
"msvc" tool is the first choice for MS-Windows, but the last choice for
OS/2. This ordering is based on what works best for most people.
</p><p>
Note that for Unix systems there is no search for tools. That is because
the default command for the C compiler "always" works there.
</p><p>
There is one trick you should be aware of, which is using the "buildaction"
attribute on object files. When a specific compiler is used to turn a
source file into an object file, this often means a specific action needs to
be used to turn this object file into a program or library. The
compile action must then add a "buildaction" attribute to the object file,
so that the generic build action can inspect the object files and invoke the
proper build action. You can see this in the example above: The compile
action for the "d" language contains:
</p><pre class="programlisting">
# Use the d_build action for building and also for :dll and :lib.
:attr {buildaction = d_build} $target
</pre><p>
The action is not executed when the target is already up-to-date. Therefore
the "buildaction" attribute should also be set by the dependency or rule,
using a ">always" section. See <a href="user-depend.html#build-sections">the section called “Command block sections”</a>.
Example:
</p><pre class="programlisting">
:rule %$OBJSUF : $.cpp
>always
:attr {buildaction = cxx_build} $target
>build
:do compile {target = $target} $source
</pre><p>
Note that the generic build action cannot handle the situation that object
files with different "buildaction" attributes are linked together. And
object files that do not have a "buildaction" attribute are taken along,
<span class="application">Aap</span> assumes they can be linked together with the object files that specify
the "buildaction" attribute. If this does not do what you intend, you can
specify another build action to use with $BUILD_ACTION. Similarly,
$BUILDDLL_ACTION and $BUILDLIB_ACTION are used for building libraries. Look
in the distributed <code class="filename">default.aap</code> for the details.
</p><h2><a name="lang-actions"></a>Actions, Rules and Routes</h2><p>
Actions are used to specify how files are to be compiled and build into a
program or library. Rules are used to specify which actions to use for
files matching a pattern. Routes are used to specify which actions to use
to turn one filetype into another. Thus these three items are closely
related.
</p><p>
The most obvious thing for a language module is to define an action for
compiling the language. Here is an excerpt from the "d" module:
</p><pre class="programlisting">
:action compile object,libobject,dllobject,default d
@if not _no.get("target"):
target = `src2obj(fname)`
# Use the d_build action for building and also for :dll and :lib.
:attr {buildaction = d_build} $target
@if _no.get("D_COMPILE_ACTION"):
:do $D_COMPILE_ACTION {target = $target} $source
@else:
:sys $DMD $?DFLAGS -of$target -c $source
</pre><p>
This action is specified for all kind of object files, including dllobject
and libobject. If compiling for a library has to be done differently you
should specify a separate action for libobject and/or dllobject.
</p><p>
The action starts with checking if $target is set. In rare cases it isn't
set and needs to be derived from $source. Since the object file suffixes
have been defined (see <a href="user-language.html#lang-suffix">above</a>) calling
<a href="ref-python.html#python-src2obj">src2obj()</a> takes care of this.
$fname is the first item in $source.
</p><p>
When a D file has been compiled into an object file it needs to be build in
a special way. To accomplish this the "buildaction" attribute of the target
is set to "d_build". This action is also defined in the D module.
</p><p>
The check for $D_COMPILE_ACTION takes care of invoking the action that was
defined by a tool. The first tool found with
<a href="ref-commands.html#cmd-toolsearch">:toolsearch</a> will set this variable.
It can later be changed with a
<a href="ref-commands.html#cmd-usetool">:usetool</a> command.
</p><p>
When $D_COMPILE_ACTION is not set, the default command to compile a D file
is executed with <a href="ref-commands.html#cmd-sys">:sys</a>. This happens when no
appropriate tool could be found. Often this is used for Unix, where the
compile command is the same for various compilers. The user may set
$m_d.DMD to the name of the compiler to be used and set $DFLAGS
to additional arguments. What could be added here is using $DINCLUDE and
$DDEFINE, like what <a href="ref-variables.html#var-include">$INCLUDE</a> and
<a href="ref-variables.html#var-define">$DEFINE</a> do for C.
A compiler may also use <a href="ref-variables.html#var-debug">$DEBUG</a> and
<a href="ref-variables.html#var-optimize">$OPTIMIZE</a>. Note that these can't be
directly used as an argument but must be translated.
</p><p>
The other actions defined in the module are similar. You can see in the
example for the D module how the build action is defined:
</p><pre class="programlisting">
:action d_build default
@if _no.get("D_BUILD_ACTION"):
:do $D_BUILD_ACTION {target = $target} $source
@else:
:sys $DMD $?DLINKFLAGS -of$target $source
</pre><p>
Defining a rule is optional. The
<a href="ref-commands.html#cmd-rule">:rule</a> command selects the source and target
based on a match of the file name with a pattern. This is useful when
a list of source files is defined without telling how they are to be turned
into object files. This is the way the rule is defined in the D module:
</p><pre class="programlisting">
:rule {global} {default} %$OBJSUF : {buildcheck = $DMD $?DFLAGS } %.d
:do compile {target = $target} $source
</pre><p>
The {global} option is needed to make the rule available everywhere
(otherwise it would only work in the module recipe). The {default} option
allows overruling this rule without getting a warning.
</p><p>
The <a href="ref-commands.html#cmd-route">:route</a> command is used to tell <span class="application">Aap</span>
how to turn a source file into an object file. This is used for the
<a href="ref-commands.html#cmd-program">:program</a>,
<a href="ref-commands.html#cmd-dll">:dll</a> and
<a href="ref-commands.html#cmd-lib">:lib</a> commands. For the D language it's
simply a matter of invoking the compile action. for other languages it may
consist of several steps with intermediate results.
</p><pre class="programlisting">
:route {default} d object,libobject,dllobject
compile
</pre></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="user-tools.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="user.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="reference.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 30. Customizing Default Tools </td><td width="20%" align="center"><a accesskey="h" href="index.html">
Contents</a></td><td width="40%" align="right" valign="top"> Part III. Reference Manual</td></tr></table></div></body></html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
a6d417e36f6bb1154f4c003e6717e298
>
files
>
158
