Building language interfaces with Vaucanswig

Author: Raphael Poss
Contact: raph@lrde.epita.fr
Date: January 2005
Version: $Id$

This document describes how to use Vaucanswig to produce interfaces with other languages.

Contents

Background

Vaucanswig is a set of SWIG wrapper definitions for the Vaucanson library.

SWIG takes Vaucanswig as input, and generates code to link between any supported scripting language and C++. In that sense, Vaucanswig is already "meta", because it ultimately supports several scripting languages. But still, even Vaucanswig itself is automatically generated, and this "meta-build" process is described in a separate document.

The document you are reading explains how to use Vaucanswig once it has been generated.

General idea

Once Vaucanswig has been generated, it is composed of input files to SWIG.

To use Vaucanson in a target scripting language, two steps are necessary:

  1. Produce C++ sources for the interface (running SWIG).
  2. Compile these sources.

Step 1 only requires Vaucanswig sources and a decent version of SWIG.

Step 2 requires the Vaucanson library and the extension libraries for the selected target language.

SWIG modules (MODULES)

Vaucanswig defines a number of SWIG modules.

The list of SWIG modules, hereinafter named MODULES, contains:

Name of module Description
core the core of vaucanswig.
K_context for each K, the definition of the algebraic context K ("K" can be "usual", "numerical", "tropical" and so on)
K_automaton definition of the Automaton and Expression types in context K
K_alg_A for each algorithm A, the definition of the specific instance of A in context K. (A can be "complete", "standard", "product" and so on)
K_algorithms a convienient wrapper for context K with "shortcuts" to all the algorithms instanciated for K.

Note that the name of SWIG modules are closely related to the namespace where the corresponding features can be found in the target scripting language.

Then, for each module M, two items are available:

Item Description
src/vaucanswig_M.i the dedicated SWIG source file
src/M.deps

(optional, may not exist) a file containing a list of modules that M is dependent upon. If the file is empty, two cases apply:

  • M is "core" - no dependency
  • M is not "core" - it depends on "core".

The first item is the most important. The second is only useful to create automated build processes which require dependency rules.

C++ sources specific to the target scripting language (T.S.L.)

Each TSL needs a different set of wrapper for the Vaucanswig modules.

For any given TSL, source files for the MODULES can be created by SWIG by running the following pseudo-algorithm:

$ for M in ${MODULES}; do
    ${SWIG} -noruntime -c++ -${TSL} \
       -I${VAUCANSWIGDIR}/src \
       -I${VAUCANSWIGDIR}/meta \
       -I${VAUCANSON_INCLUDES}  \
       ${VAUCANSWIGDIR}/src/vaucanswig_${M}.i
  done

Where:

Compilation of the binaries for the target scripting language

The previous step creates a bunch of C++ source files of the form:

vaucanswig_${M}_wrap.cxx

They should be compiled with the C++ compiler supported by the TSL.

The C++ compilation should use the following flags:

-DINTERNAL_CHECKS -DSTRICT -DEXCEPTION_TRAPS: Use for more secure code in Vaucanson.

-I${VAUCANSON_INCLUDES}: Specify the location of the Vaucanson library headers.

-I${VAUCANSWIGDIR}/src -I${VAUCANSWIGDIR}/meta: Needed by Vaucanswig.

In addition, any "compatibility" flags required by Vaucanson for this particular C++ compiler should be used as well.

Automake support for Python as a TSL

According to the previous section, a Makefile.am file is generated in the subdirectory python/.

It contains four main parts:

Additionnaly, the following (not important) parts are generated for convenience purposes:

Automake support for the TSL-independent code

In order to make things comply to the spirit of the Autotools, a convenience Makefile.am is generated in the src/ directory.

It contains a definition of EXTRA_DIST with all the SWIG module source files, of the form: vaucanswig_$(MODULE).i