This chapter describes SWIG usage on Microsoft Windows. Installing SWIG and running the examples is covered as well as building the SWIG executable. Usage within the Unix like environments MinGW and Cygwin is also detailed.
SWIG does not come with the usual Windows type installation program, however it is quite easy to get started. The main steps are:
The swigwin distribution contains the SWIG Windows 32-bit executable, swig.exe, which will run on both 32-bit and 64-bit versions of Windows. If you want to build your own swig.exe have a look at Building swig.exe on Windows.
Microsoft Visual C++ is the most commonly used compiler for compiling and linking SWIG's output on Windows. The Examples directory has a few Visual C++ project files (.dsp files). These were produced by Visual C++ 6. Newer versions of Visual Studio are able to open and convert these project files. Each C# example comes with a Visual Studio 2005 solution and associated project files instead of Visual C++ 6 project files. The project files have been set up to execute SWIG in a custom build rule for the SWIG interface (.i) file. Alternatively run the examples using Cygwin.
More information on each of the examples is available with the examples distributed with SWIG (Examples/index.html).
Ensure the SWIG executable is as supplied in the SWIG root directory in order for the examples to work. Most languages require some environment variables to be set before running Visual C++. Note that Visual C++ must be re-started to pick up any changes in environment variables. Open up an example .dsp file, Visual C++ will prompt you to upgrade the project and convert it into an MSBuild project (.vcxproj file) and Solution (.sln file). Note that older versions of Visual C++ will simply create a workspace for you (.dsw file). Ensure the Release build is selected then do a Rebuild Solution from the Build menu. The required environment variables are displayed with their current values during the build.
The list of required environment variables for each module language is also listed below. They are usually set from the Control Panel and System properties, but this depends on which flavour of Windows you are running. If you don't want to use environment variables then change all occurrences of the environment variables in the .dsp files with hard coded values. If you are interested in how the project files are set up there is explanatory information in some of the language module's documentation.
The C# examples do not require any environment variables to be set as a C# project file is included. Just open up the .sln solution file in Visual Studio 2005 or later, select Release Build, and do a Rebuild Solution from the Build menu. The accompanying C# and C++ project files are automatically used by the solution file.
JAVA_INCLUDE : Set this to the directory containing jni.h
JAVA_BIN : Set this to the bin directory containing javac.exe
Example using JDK1.3:
JAVA_INCLUDE: D:\jdk1.3\include
JAVA_BIN: D:\jdk1.3\bin
PERL5_INCLUDE : Set this to the directory containing perl.h
PERL5_LIB : Set this to the Perl library including path for linking
Example using nsPerl 5.004_04:
PERL5_INCLUDE: D:\nsPerl5.004_04\lib\CORE
PERL5_LIB: D:\nsPerl5.004_04\lib\CORE\perl.lib
PYTHON_INCLUDE : Set this to the directory that contains Python.h
PYTHON_LIB : Set this to the Python library including path for linking
Example using Python 2.1.1:
PYTHON_INCLUDE: D:\python21\include
PYTHON_LIB: D:\python21\libs\python21.lib
TCL_INCLUDE : Set this to the directory containing tcl.h
TCL_LIB : Set this to the TCL library including path for linking
Example using ActiveTcl 8.3.3.3
TCL_INCLUDE: D:\tcl\include
TCL_LIB: D:\tcl\lib\tcl83.lib
R_INCLUDE : Set this to the directory containing R.h
R_LIB : Set this to the R library (Rdll.lib) including path for linking. The library needs to be built as described in the R README.packages file (the pexports.exe approach is the easiest).
Example using R 2.5.1:
R_INCLUDE: C:\Program Files\R\R-2.5.1\include
R_LIB: C:\Program Files\R\R-2.5.1\bin\Rdll.lib
RUBY_INCLUDE : Set this to the directory containing ruby.h
RUBY_LIB : Set this to the ruby library including path for linking
Example using Ruby 1.6.4:
RUBY_INCLUDE: D:\ruby\lib\ruby\1.6\i586-mswin32
RUBY_LIB: D:\ruby\lib\mswin32-ruby16.lib
If you do not have access to Visual C++ you will have to set up project files / Makefiles for your chosen compiler. There is a section in each of the language modules detailing what needs setting up using Visual C++ which may be of some guidance. Alternatively you may want to use Cygwin as described in the following section.
The SWIG distribution provides a pre-built swig.exe and so it is not necessary for users to build the SWIG executable. However, this section is provided for those that want to modify the SWIG source code in a Windows environment. Normally this is not needed, so most people will want to ignore this section.
There are various ways to build the SWIG executable including CMake which is able to generate project files for building with Visual Studio. SWIG can also be compiled and run using MSYS2, Cygwin or MinGW, all of which provide a Unix like front end to Windows and comes free with the gcc C/C++ compiler.
SWIG can be built using CMake and Visual Studio rather than autotools. As with the other approaches to building SWIG the dependencies need to be installed. The steps below are one of a number of ways of installing the dependencies without requiring Cygwin or MinGW. For fully working build steps always check the Continuous Integration (CI) setups currently detailed in the GitHub Actions YAML file.
C:\Tools\nuget install CMake-win64 -Version 3.15.5 -OutputDirectory C:\Tools\CMakeUsing PowerShell the equivalent syntax is:
& "C:\Tools\nuget" install CMake-win64 -Version 3.15.5 -OutputDirectory C:\Tools\CMakeAlternatively you can download CMake from https://cmake.org/download/.
C:\Tools\nuget install Bison -Version 3.7.4 -OutputDirectory C:\Tools\bisonAlternatively download Bison from https://sourceforge.net/projects/winflexbison/files/ (Bison 3.7.4 is used in this example) and save to a folder e.g. C:\Tools\Bison
C:\Tools\nuget install PCRE2 -Version 10.39 -OutputDirectory C:\Tools\pcre2Note this is a x64 build, if this is not suitable PCRE2 can be built from source using https://github.com/PhilipHazel/pcre2/. Alternatively, set WITH_PCRE=OFF to disable PCRE2 support if you are sure you do not require it.
git clone https://github.com/swig/swig.gitIn this example we are assuming the source code is available at C:\swig
Now we have all the required dependencies we can build SWIG using PowerShell and the commands below. We are assuming Visual Studio 2019 is installed. For other versions of Visual Studio change "Visual Studio 16 2019 -A x64" to the relevant Visual Studio Generator and architecture. We add the required build tools to the system PATH, and then build a Release version of SWIG. If all runs successfully a new swig.exe should be generated in the C:/swig/install2/bin folder.
cd C:\swig $env:PATH="C:\Tools\CMake\CMake-win64.3.15.5\bin;C:\Tools\bison\Bison.3.7.4\bin;" + $env:PATH $PCRE_ROOT="C:\Tools\pcre2\PCRE2.10.39.0" $PCRE_PLATFORM="x64" cmake -G "Visual Studio 16 2019" -A "x64" ` -DCMAKE_INSTALL_PREFIX="C:/swig/install2" ` -DCMAKE_C_FLAGS="/DPCRE2_STATIC" ` -DCMAKE_CXX_FLAGS="/DPCRE2_STATIC" ` -DPCRE2_INCLUDE_DIR="$PCRE_ROOT/include" ` -DPCRE2_LIBRARY="$PCRE_ROOT/lib/pcre2-8-static.lib" ` -S . -B build cmake --build build --config Release cmake --install build --config Release # to test the exe built correctly cd install2/bin ./swig.exe -version ./swig.exe -help
In addition to Release builds you can create a Debug build using:
cmake --build build --config Debug
A Visual Studio solution file should be generated named swig.sln. This can be opened and debugged by running the swig project and setting Properties > Debugging > Command Arguments. For example to debug one of the test-suite .i files included with the SWIG source use the following:
-python -c++ -o C:\Temp\doxygen_parsing.cpp C:\swig\Examples\test-suite\doxygen_parsing.i
Download and install MSYS2 from www.msys2.org (tested with version msys2-x86_64-20201109). Launch the MSYS2 shell.
Install the packages needed to build swig:
pacman -S git autoconf automake bison gcc make pcre2-devel
Clone the repository to /usr/src/:
mkdir /usr/src/ cd /usr/src/ git clone https://github.com/swig/swig.git
Configure and build:
cd /usr/src/swig ./autogen.sh ./configure make
Finally you may also want to install SWIG:
make install
The short abbreviated instructions follow...
The step by step instructions to download and install MinGW and MSYS, then download and build the latest version of SWIG from Github follow... Note that the instructions for obtaining SWIG from Github are also online at SWIG Bleeding Edge.
Pitfall note: Execute the steps in the order shown and don't use spaces in path names. In fact it is best to use the default installation directories.
cd / tar -jxf msys-automake-1.8.2.tar.bz2 tar -jxf msys-autoconf-2.59.tar.bz2 tar -zxf bison-2.0-MSYS.tar.gz
mkdir /usr/src cd /usr/src git clone https://github.com/swig/swig.git
cd /usr/src/swig Tools/pcre-build.sh
cd /usr/src/swig ./autogen.sh ./configure make
Note that SWIG can also be built using Cygwin. However, SWIG will then require the Cygwin DLL when executing. Follow the Unix instructions in the README file in the SWIG root directory. Note that the Cygwin environment will also allow one to regenerate the autotool generated files which are supplied with the release distribution. These files are generated using the autogen.sh script and will only need regenerating in circumstances such as changing the build system.
The examples and test-suite work as successfully on Cygwin as on any other Unix operating system. The modules which are known to work are Python, Tcl, Perl, Ruby, Java and C#. Follow the Unix instructions in the README file in the SWIG root directory to build the examples.
A common problem when using SWIG on Windows are the Microsoft function calling conventions which are not in the C++ standard. SWIG parses ISO C/C++ so cannot deal with proprietary conventions such as __declspec(dllimport), __stdcall etc. There is a Windows interface file, windows.i, to deal with these calling conventions though. The file also contains typemaps for handling commonly used Windows specific types such as __int64, BOOL, DWORD etc. Include it like you would any other interface file, for example:
%include <windows.i> __declspec(dllexport) ULONG __stdcall foo(DWORD, __int32);
Note that if you follow Microsoft's recommendation of wrapping the __declspec calls in a preprocessor definition, you will need to make sure that the definition is included by SWIG as well, by either defining it manually or via a header. For example, if you have specified the preprocessor definition in a header named export_lib.h and include other headers which depend on it, you should use the %include directive to include the definition explicitly. For example, if you had a header file, bar.h, which depended on export_lib.h, your SWIG definition file might look like:
// bar.i %module bar %include <windows.i> %include "export_lib.h" %include "bar.h"
where export_lib.h may contain:
// export_lib.h #define BAR_API __declspec(dllexport)
and bar.h may look like:
// bar.h #include "export_lib.h" BAR_API void bar_function(int, double);
Using the preprocessor to remove BAR_API is a popular simpler solution:
// bar.i %module bar #define BAR_API %include "bar.h"