<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 30. Customizing Default Tools</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-autodep.html" title="Chapter 29. Customizing Automatic Depedencies"><link rel="next" href="user-language.html" title="Chapter 31. Adding A Language Module"></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-autodep.html">Prev</a></td><td align="center" class="center">User Manual</td><td align="right" class="right"><a accesskey="n" href="user-language.html">Next</a></td></tr></tbody></table><hr><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="user-tools"></a>Chapter 30. Customizing Default Tools</h2></div></div></div><p>
Tools are used to execute actions. Examples are a compiler and a linker.
Each tool must be executed with specific arguments. But the recipe attempts
to be portable, thus not include the literal command to be executed.
The mechanism described in this chapter takes care of translating the generic
action into invoking a specific tool with its arguments.
</p><p>
It all starts with an action. Let us use the C compile action as an example.
In the default recipe a default C compile action is defined. This one works
for most C compilers that take arguments like the Unix "cc" command. If
another kind of compiler is to be used, the $C_COMPILE_ACTION variable is set
to the name of the action to be used, for example "compile_msvc".
The default compile action will check the $C_COMPILE_ACTION variable and
invoke the "compile_msvc" action instead of using its generic compile command.
</p><p>
During startup the default recipe will check for existence of tools for C and
C++. A specific sequence of tools is checked for, depending on the platform.
Thus in MS-Windows "msvc" will be checked for, while on Unix this doesn't
happen. This is implemented with a Python module. For msvc it is
"tools/msvc.py".
</p><p>
Each tool module defines an exists() function. It contains a check if the
tool can be found. Mostly this is done by looking for a certain executable
program. The msvc tool searches for "cl" (the compiler) and "vcvars32" (a
command to start using the MSVC command line tools).
</p><p>
If a tool is detected, the actions for it are defined. This is always done,
also when another tool was already detected. This allows the user to invoke
specific actions or switch toolchain where he wants to. For MSVC the
"compile_msvc" action is defined. That is like the normal "compile" action
but with MSVC specific arguments.
</p><p>
The first tool that is detected will be used by default. The
use_actions() function of the tool is invoked, which sets a number of
variables, such as $C_COMPILE_ACTION, to the name of the action to be used.
As mentioned above, the result will be that the generic actions will invoke
the tool-specific action.
</p><h2><a name="id2662970"></a>Building in a different way</h2><p>
The default build action works for object files generated from C source files.
It might also work for other object files, in that case you do not need to do
anything.
</p><p>
When building needs to be done in a different way, depending on the kind of
source files used, add a "buildaction" attribute to the object file. This will
make the default build action invoke the action specified with "buildaction"
instead of the default build commands. Sources without a "buildaction"
attribute do not influence this choice.
</p><p>
Note that it is not possible to have two different "buildaction" attributes on
the sources of the build action. If you want to handle this set the
$BUILD_ACTION variable to the build action that can handle this.
</p><p>
If a tool needs to do building for C and C++ files differently, set the
$C_BUILD_ACTION and/or $CXX_BUILD_ACTION variables to the action that will
do the building.
</p><h2><a name="id2662986"></a>Adding A New Tool</h2><p>
You need to write a Python module and place it in the "tools" directory. Copy
one of the existing tool files to start with. Then make changes to the
functions:
</p><div class="variablelist"><dl><dt><span class="term">
exists()
</span></dt><dd><p>
Return True if the tool can be located. This is mostly done by simply
checking for an executable program with the
<a href="ref-python.html#python-program-path">program_path()</a> function.
But you might do something more complicated, such as running the
program with a "--version" argument and check the output.
</p></dd><dt><span class="term">
define_actions()
</span></dt><dd><p>
Define the actions that this tool can accomplish. Each action
name should be formed from the basic action name with "_toolname"
appended. Thus a compile action for the MSVC compiler uses the action
name "compile_msvc". You can define this action for several file
types.
</p><p>
The action usually supports using variables, so that the user can
modify them in a recipe. Some variables are generic and can be used
by all tools, such as $CFLAGS. Your tool may need to translate it
from the generic form to the tool-specific argument. For example, if
$DEFINE contains "-DFOO=foo" you might have to translate this to
"/D:FOO=foo".
</p><p>
You can also support specific variables for your tool. For example
$MSVC is used to specify the name of the compiler. You give it a
default value in the toplevel scope, but only when the user didn't do
that already. The toplevel scope can be obtained from the Global
module: "Global.globals".
</p></dd><dt><span class="term">
use_actions(scope)
</span></dt><dd><p>
This function is called when the actions of the tool will be used
as the default actions in "scope". When the tool is the first one
found it will be called from the startup code. But the user may also
use this to select a specific tool to be used in one recipe, or even
one dependency.
</p></dd></dl></div><p>
</p><h2><a name="id2663726"></a>Using A Specific Tool</h2><p>
The
<a href="ref-commands.html#cmd-usetool">:usetool</a> command can be used to specify a
specific tool to be used in
the current scope. When used in the toplevel recipe the tool becomes the
default tool. When used in a child recipe the tool will be used in that
recipe or by all actions invoked there. It can also be used in build
commands, the tool will be used by invoked actions and dependencies.
</p><p>
Example:
</p><pre class="programlisting">
:usetool mingw
:update prog_A
:usetool msvc
:update prog_B
</pre><p>
</p><p>
This actually works by defining the tool-specific actions and defining
variables such as $C_COMPILE_ACTION in the current scope.
</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="user-autodep.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="user-language.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 29. Customizing Automatic Depedencies </td><td width="20%" align="center"><a accesskey="h" href="index.html">
Contents</a></td><td width="40%" align="right" valign="top"> Chapter 31. Adding A Language Module</td></tr></table></div></body></html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
a6d417e36f6bb1154f4c003e6717e298
>
files
>
164
