path: root/SCons/Tool/swig.xml

<?xml version="1.0"?>
<!--
__COPYRIGHT__

This file is processed by the bin/SConsDoc.py module.
See its __doc__ string for a discussion of the format.
-->

<!DOCTYPE sconsdoc [
<!ENTITY % scons SYSTEM '../../doc/scons.mod'>
%scons;
<!ENTITY % builders-mod SYSTEM '../../doc/generated/builders.mod'>
%builders-mod;
<!ENTITY % functions-mod SYSTEM '../../doc/generated/functions.mod'>
%functions-mod;
<!ENTITY % tools-mod SYSTEM '../../doc/generated/tools.mod'>
%tools-mod;
<!ENTITY % variables-mod SYSTEM '../../doc/generated/variables.mod'>
%variables-mod;
]>

<sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">

<tool name="swig">
<summary>
<para>
Sets construction variables for the &swig; interface compiler.
</para>
</summary>
<sets>
<item>SWIG</item>
<item>SWIGFLAGS</item>
<item>SWIGDIRECTORSUFFIX</item>
<item>SWIGCFILESUFFIX</item>
<item>SWIGCXXFILESUFFIX</item>
<item>_SWIGINCFLAGS</item>
<item>SWIGINCPREFIX</item>
<item>SWIGINCSUFFIX</item>
<item>SWIGCOM</item>
<item>SWIGPATH</item>
<item>SWIGVERSION</item>
</sets>
<uses>
<item>SWIGCOMSTR</item>
</uses>
</tool>

<cvar name="SWIG">
<summary>
<para>
The name of the &swig; compiler to use.
</para>
</summary>
</cvar>

<cvar name="SWIGCFILESUFFIX">
<summary>
<para>
The suffix that will be used for intermediate C
source files generated by &swig;.
The default value is <literal>'_wrap$CFILESUFFIX'</literal> -
that is, the concatenation of the string
<literal>_wrap</literal>
and the current C suffix &cv-link-CFILESUFFIX;.
By default, this value is used whenever the
<option>-c++</option>
option is
<emphasis>not</emphasis>
specified as part of the
&cv-link-SWIGFLAGS;
construction variable.
</para>
</summary>
</cvar>

<cvar name="SWIGDIRECTORSUFFIX">
<summary>
<para>
The suffix that will be used for intermediate C++ header
files generated by &swig;.
These are only generated for C++ code when the &swig; 'directors' feature is
turned on.
The default value is
<filename>_wrap.h</filename>.
</para>
</summary>
</cvar>

<cvar name="SWIGCOM">
<summary>
<para>
The command line used to call &swig;.
</para>
</summary>
</cvar>

<cvar name="SWIGCOMSTR">
<summary>
<para>
The string displayed when calling &swig;.
If this is not set, then &cv-link-SWIGCOM; (the command line) is displayed.
</para>
</summary>
</cvar>

<cvar name="SWIGCXXFILESUFFIX">
<summary>
<para>
The suffix that will be used for intermediate C++
source files generated by &swig;.
The default value is <literal>'_wrap$CXXFILESUFFIX'</literal> -
that is, the concatenation of the string
<literal>_wrap</literal>
and the current C++ suffix &cv-link-CXXFILESUFFIX;.
By default, this value is used whenever the
<option>-c++</option>
option is specified as part of the
&cv-link-SWIGFLAGS;
construction variable.
</para>
</summary>
</cvar>

<cvar name="SWIGFLAGS">
<summary>
<para>
General options passed to &swig;.
This is where you should set the target language
(<option>-python</option>,
<option>-perl5</option>,
<option>-tcl</option>, etc.)
and whatever other options you want to specify to &swig;,
such as the <option>-c++</option> to generate C++ code
instead of C Code.
</para>
</summary>
</cvar>

<cvar name="_SWIGINCFLAGS">
<summary>
<para>
An automatically-generated construction variable
containing the &swig; command-line options
for specifying directories to be searched for included files.
The value of &cv-_SWIGINCFLAGS; is created
by respectively prepending and appending
&cv-SWIGINCPREFIX; and &cv-SWIGINCSUFFIX;
to the beginning and end
of each directory in &cv-SWIGPATH;.
</para>
</summary>
</cvar>

<cvar name="SWIGINCPREFIX">
<summary>
<para>
The prefix used to specify an include directory on the &swig; command line.
This will be prepended to the beginning of each directory
in the &cv-SWIGPATH; construction variable
when the &cv-_SWIGINCFLAGS; variable is automatically generated.
</para>
</summary>
</cvar>

<cvar name="SWIGINCSUFFIX">
<summary>
<para>
The suffix used to specify an include directory on the &swig; command line.
This will be appended to the end of each directory
in the &cv-SWIGPATH; construction variable
when the &cv-_SWIGINCFLAGS; variable is automatically generated.
</para>
</summary>
</cvar>

<cvar name="SWIGOUTDIR">
<summary>
<para>
Specifies the output directory in which &swig;
should place generated language-specific files.
This will be used by SCons to identify
the files that will be generated by the &swig; call,
and translated into the
<literal>swig -outdir</literal> option on the command line.
</para>
</summary>
</cvar>

<cvar name="SWIGPATH">
<summary>
<para>
The list of directories that &swig;
will search for included files.
&SCons;' SWIG implicit dependency scanner will search these
directories for include files. The default value is an empty list.
</para>

<para>
Don't explicitly put include directory
arguments in &cv-link-SWIGFLAGS;
the result will be non-portable
and the directories will not be searched by the dependency scanner.
Note: directory names in &cv-link-SWIGPATH;
will be looked-up relative to the SConscript
directory when they are used in a command.
To force
&scons;
to look-up a directory relative to the root of the source tree use
a top-relative path (<literal>#</literal>):
</para>

<example_commands>
env = Environment(SWIGPATH='#/include')
</example_commands>

<para>
The directory look-up can also be forced using the
&Dir;()
function:
</para>

<example_commands>
include = Dir('include')
env = Environment(SWIGPATH=include)
</example_commands>

<para>
The directory list will be added to command lines
through the automatically-generated
&cv-_SWIGINCFLAGS;
construction variable,
which is constructed by
respectively prepending and appending the values of the
&cv-SWIGINCPREFIX; and &cv-SWIGINCSUFFIX;
construction variables
to the beginning and end
of each directory in &cv-SWIGPATH;.
Any command lines you define that need
the SWIGPATH directory list should
include &cv-_SWIGINCFLAGS;:
</para>

<example_commands>
env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SOURCES")
</example_commands>
</summary>
</cvar>

<cvar name="SWIGVERSION">
<summary>
<para>
The detected version string of the &swig; tool.
</para>
</summary>
</cvar>

</sconsdoc>