swig

Generate a binding between C++ and Python

$ swig -c++ -python -o [path/to/output_wrapper.cpp] [path/to/swig_file.i]

$ swig -go -cgo -intgosize 64 -c++ [path/to/swig_file.i]

$ swig -java [path/to/swig_file.i]

$ swig -ruby -prefix "[foo::bar::]" [path/to/swig_file.i]

swig [OPTIONS]... FILE

-c++
    Generate C++ wrapper code. By default, SWIG generates C-compatible wrappers.

-java
    Generate Java language bindings.

-python
    Generate Python language bindings.

-perl
    Generate Perl language bindings.

-ruby
    Generate Ruby language bindings.

-php
    Generate PHP language bindings.

-octave
    Generate Octave language bindings.

-tcl
    Generate Tcl language bindings.

-go
    Generate Go language bindings.

-o
    Specify the name of the output C/C++ wrapper file. If not specified, SWIG generates a default name.

-outdir
    Specify the output directory for generated language-specific files (e.g., Python .py files, Java .java files).

-I
    Add a directory to the SWIG include path, similar to -I in C/C++ compilers.

-D
    Define a preprocessor symbol, equivalent to #define.

-U
    Undefine a preprocessor symbol.

-Wall
    Enable all warnings generated by SWIG.

-Wextra
    Enable extra warnings (implies -Wall).

-module
    Set the name of the generated module or package.

-version
    Display SWIG version information and exit.

-help
    Display a help message with available options.

SWIG (Simplified Wrapper and Interface Generator) is an open-source tool designed to connect programs and libraries written in C and C++ with various high-level scripting languages. It automates the tedious and error-prone process of writing "glue code" or "wrapper code" that enables seamless communication between different language environments.

Users provide SWIG with an interface file (typically ending in .i) that describes the C/C++ API to be exposed. SWIG then parses this file and generates both C/C++ wrapper code (which handles the low-level calls) and language-specific binding code (e.g., Python extension modules, Java JNI code, Perl XS modules, etc.). This makes it possible to leverage the performance and extensive libraries of C/C++ from the rapid development environments of languages like Python, Perl, Ruby, Java, C#, PHP, R, Tcl, and Go. It's widely used for creating language bindings for existing C/C++ libraries.

While powerful, SWIG can be complex to master, especially with advanced C++ features like templates, operator overloading, or complex inheritance hierarchies. Error messages can sometimes be cryptic, requiring a deep understanding of both C/C++ and the target scripting language. Users must also handle the compilation and linking of the generated C/C++ wrapper code manually, often requiring a separate build system (e.g., make, cmake, or specific language build tools like setuptools for Python).

The core input to SWIG is an interface file, typically with a .i extension. This file is similar to a C/C++ header file but includes special SWIG directives (starting with %) that guide the wrapper generation process. These directives allow users to specify which functions, classes, and variables to expose, apply renaming rules, ignore certain declarations, or embed custom code for the target language. It serves as the primary mechanism for customizing the generated bindings.

Typemaps are one of SWIG's most powerful features. They define how data types are converted between C/C++ and the target scripting language. Typemaps allow developers to customize the marshaling and unmarshaling of complex data structures, handle memory management, manage pointers, and integrate custom data types. They provide fine-grained control over the generated interface, ensuring data is passed correctly and efficiently across language boundaries.

SWIG was initially developed by David Beazley in the mid-1990s as a tool to simplify the process of interfacing C/C++ code with scripting languages, particularly Tcl and Python. Its development was driven by the need for a robust and automated solution to generate language bindings, avoiding the manual and error-prone process of writing glue code. Over the years, SWIG has grown significantly, adding support for a vast array of target languages and continuously improving its C++ parsing capabilities. It remains an actively maintained and widely adopted tool for high-performance language integration.

gcc(1), make(1), cmake(1), python(1), perl(1), ruby(1)