| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <head> |
| <title>Getting started on Windows</title> |
| <link rel="stylesheet" type="text/css" href="style.css"> |
| <meta http-equiv="content-type" content="text/html; charset=UTF-8"> |
| </head> |
| |
| <body bgcolor="#ffffff"> |
| <H1><a name="Windows">3 Getting started on Windows </a></H1> |
| <!-- INDEX --> |
| <div class="sectiontoc"> |
| <ul> |
| <li><a href="#Windows_installation">Installation on Windows</a> |
| <ul> |
| <li><a href="#Windows_executable">Windows Executable</a> |
| </ul> |
| <li><a href="#Windows_examples">SWIG Windows Examples</a> |
| <ul> |
| <li><a href="#Windows_visual_studio">Instructions for using the Examples with Visual Studio</a> |
| <ul> |
| <li><a href="#Windows_csharp">C#</a> |
| <li><a href="#Windows_java">Java</a> |
| <li><a href="#Windows_perl">Perl</a> |
| <li><a href="#Windows_python">Python</a> |
| <li><a href="#Windows_tcl">TCL</a> |
| <li><a href="#Windows_r">R</a> |
| <li><a href="#Windows_ruby">Ruby</a> |
| </ul> |
| <li><a href="#Windows_other_compilers">Instructions for using the Examples with other compilers</a> |
| </ul> |
| <li><a href="#Windows_cygwin_mingw">SWIG on Cygwin and MinGW</a> |
| <ul> |
| <li><a href="#Windows_swig_exe">Building swig.exe on Windows</a> |
| <ul> |
| <li><a href="#Windows_cmake">Building swig.exe using CMake</a> |
| <li><a href="#Windows_mingw_msys">Building swig.exe using MSYS2</a> |
| <li><a href="#Windows_mingw_msys">Building swig.exe using MinGW and MSYS</a> |
| <li><a href="#Windows_cygwin">Building swig.exe using Cygwin</a> |
| </ul> |
| <li><a href="#Windows_examples_cygwin">Running the examples on Windows using Cygwin</a> |
| </ul> |
| <li><a href="#Windows_interface_file">Microsoft extensions and other Windows quirks</a> |
| </ul> |
| </div> |
| <!-- INDEX --> |
| |
| |
| |
| <p> |
| 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. |
| </p> |
| |
| |
| <H2><a name="Windows_installation">3.1 Installation on Windows</a></H2> |
| |
| |
| <p> |
| SWIG does not come with the usual Windows type installation program, however it is quite easy to get started. The main steps are: |
| </p> |
| <ul> |
| <li>Download the swigwin zip package from the <a href="http://www.swig.org">SWIG website</a> and unzip into a directory. This is all that needs downloading for the Windows platform. |
| <li>Set environment variables as described in the <a href="#Windows_examples">SWIG Windows Examples</a> section in order to run examples using Visual C++. |
| </ul> |
| |
| <H3><a name="Windows_executable">3.1.1 Windows Executable</a></H3> |
| |
| |
| <p> |
| 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 <a href="#Windows_swig_exe">Building swig.exe on Windows</a>. |
| </p> |
| |
| |
| <H2><a name="Windows_examples">3.2 SWIG Windows Examples</a></H2> |
| |
| |
| <p> |
| 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 <a href="#Windows_examples_cygwin">examples using Cygwin</a>. |
| |
| <p> |
| More information on each of the examples is available with the examples distributed with SWIG (Examples/index.html). |
| |
| <H3><a name="Windows_visual_studio">3.2.1 Instructions for using the Examples with Visual Studio</a></H3> |
| |
| |
| <p> |
| 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 <b>before</b> 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. |
| </p> |
| <p> |
| 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. |
| </p> |
| |
| <H4><a name="Windows_csharp">3.2.1.1 C#</a></H4> |
| |
| |
| <p> |
| 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. |
| </p> |
| |
| |
| <H4><a name="Windows_java">3.2.1.2 Java</a></H4> |
| |
| |
| <p> |
| <b><tt>JAVA_INCLUDE</tt></b> : Set this to the directory containing jni.h<br> |
| <b><tt>JAVA_BIN</tt></b> : Set this to the bin directory containing javac.exe<p> |
| Example using JDK1.3:<br> |
| <tt> |
| JAVA_INCLUDE: D:\jdk1.3\include<br> |
| JAVA_BIN: D:\jdk1.3\bin<br> |
| </tt> |
| </p> |
| |
| |
| <H4><a name="Windows_perl">3.2.1.3 Perl</a></H4> |
| |
| |
| <p> |
| <b><tt>PERL5_INCLUDE</tt></b> : Set this to the directory containing perl.h<br> |
| <b><tt>PERL5_LIB</tt></b> : Set this to the Perl library including path for linking<p> |
| Example using nsPerl 5.004_04:<p> |
| <tt> |
| PERL5_INCLUDE: D:\nsPerl5.004_04\lib\CORE<br> |
| PERL5_LIB: D:\nsPerl5.004_04\lib\CORE\perl.lib<br> |
| </tt> |
| </p> |
| |
| |
| <H4><a name="Windows_python">3.2.1.4 Python</a></H4> |
| |
| |
| <p> |
| <b><tt>PYTHON_INCLUDE</tt></b> : Set this to the directory that contains Python.h<br> |
| <b><tt>PYTHON_LIB</tt></b> : Set this to the Python library including path for linking<p> |
| Example using Python 2.1.1:<br> |
| <tt> |
| PYTHON_INCLUDE: D:\python21\include<br> |
| PYTHON_LIB: D:\python21\libs\python21.lib<br> |
| </tt> |
| </p> |
| |
| |
| <H4><a name="Windows_tcl">3.2.1.5 TCL</a></H4> |
| |
| |
| <p> |
| <b><tt>TCL_INCLUDE</tt></b> : Set this to the directory containing tcl.h<br> |
| <b><tt>TCL_LIB</tt></b> : Set this to the TCL library including path for linking<p> |
| Example using ActiveTcl 8.3.3.3<br> |
| <tt> |
| TCL_INCLUDE: D:\tcl\include<br> |
| TCL_LIB: D:\tcl\lib\tcl83.lib<br> |
| </tt> |
| </p> |
| |
| |
| <H4><a name="Windows_r">3.2.1.6 R</a></H4> |
| |
| |
| <p> |
| <b><tt>R_INCLUDE</tt></b> : Set this to the directory containing R.h<br> |
| <b><tt>R_LIB</tt></b> : 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).<p> |
| Example using R 2.5.1:<br> |
| <tt> |
| R_INCLUDE: C:\Program Files\R\R-2.5.1\include<br> |
| R_LIB: C:\Program Files\R\R-2.5.1\bin\Rdll.lib<br> |
| </tt> |
| </p> |
| |
| |
| <H4><a name="Windows_ruby">3.2.1.7 Ruby</a></H4> |
| |
| |
| <p> |
| <b><tt>RUBY_INCLUDE</tt></b> : Set this to the directory containing ruby.h<br> |
| <b><tt>RUBY_LIB</tt></b> : Set this to the ruby library including path for linking<p> |
| Example using Ruby 1.6.4:<br> |
| <tt> |
| RUBY_INCLUDE: D:\ruby\lib\ruby\1.6\i586-mswin32<br> |
| RUBY_LIB: D:\ruby\lib\mswin32-ruby16.lib<br> |
| </tt> |
| </p> |
| |
| |
| <H3><a name="Windows_other_compilers">3.2.2 Instructions for using the Examples with other compilers</a></H3> |
| |
| |
| <p> |
| 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. |
| </p> |
| |
| <H2><a name="Windows_cygwin_mingw">3.3 SWIG on Cygwin and MinGW</a></H2> |
| |
| |
| <p> |
| SWIG can also be compiled and run using <a href="http://www.cygwin.com">Cygwin</a> or <a href="http://www.mingw.org">MinGW</a> which provides a Unix like front end to Windows and comes free with gcc, an ISO C/C++ compiler. However, this is not a recommended approach as the prebuilt executable is supplied. |
| </p> |
| |
| <H3><a name="Windows_swig_exe">3.3.1 Building swig.exe on Windows</a></H3> |
| |
| |
| <p> |
| If you want to replicate the build of swig.exe that comes with the download, follow the MinGW instructions below. |
| This is not necessary to use the supplied swig.exe. |
| This information 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. |
| </p> |
| |
| <H4><a name="Windows_cmake">3.3.1.1 Building swig.exe using CMake</a></H4> |
| |
| |
| <p> |
| SWIG can also be built using <a href="https://cmake.org/">CMake</a> 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 setups currently detailed in the <a href="https://github.com/swig/swig/blob/master/appveyor.yml">Appveyor YAML file</a>. |
| </p> |
| |
| <ol> |
| <li> |
| Install Nuget from <a href="https://www.nuget.org/downloads">https://www.nuget.org/downloads</a> (v5.8.1 is used in this example, and installed to C:\Tools). Nuget is the package manager |
| for .NET, but allows us to easily install <a href="https://www.pcre.org/">PCRE</a> and other dependencies required by SWIG. |
| </li> |
| <li> |
| Install CMake using the following command: <pre>C:\Tools\nuget install CMake-win64 -Version 3.15.5 -OutputDirectory C:\Tools\CMake</pre> |
| Alternatively you can download CMake from <a href="https://cmake.org/download/">https://cmake.org/download/</a>. |
| </li> |
| <li> |
| Install Bison using the following command: <pre>C:\Tools\nuget install bison-win32 -Version 2.4.1.1 -OutputDirectory C:\Tools\bison</pre> |
| Alternatively download Bison from <a href="https://sourceforge.net/projects/gnuwin32/files/bison/">https://sourceforge.net/projects/gnuwin32/files/bison/</a> (2.4.1 is used in this example) |
| and save to a folder e.g. C:\Tools\Bison |
| </li> |
| <li> |
| Install PCRE using Nuget using the following command: <pre>C:\Tools\nuget install pcre -Version 8.33.0.1 -OutputDirectory C:\Tools\pcre</pre> |
| </li> |
| <li> |
| We will also need the SWIG source code. Either download a zipped archive from GitHub, or if git is installed clone the latest codebase |
| using <pre>git clone https://github.com/swig/swig.git</pre> |
| In this example we are assuming the source code is available at C:\swig |
| </li> |
| </ol> |
| |
| <p> |
| We are assuming Visual Studio 2017 is installed. For other versions of Visual Studio change <i>"Visual Studio 15 2017 Win64"</i> to the relevant |
| <a href="https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#visual-studio-generators">Visual Studio Generator</a>. |
| Now we have all the required dependencies we can build SWIG using the commands below. 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 a /Release folder. |
| </p> |
| |
| <div class="shell"> |
| <pre> |
| cd C:\swig |
| SET PATH=C:\Tools\CMake\CMake-win64.3.15.5\bin;C:\Tools\bison\bison-win32.2.4.1.1\tools\native\bin;%PATH% |
| SET PCRE_ROOT=C:\Tools\pcre\pcre.8.33.0.1\build\native |
| SET PCRE_PLATFORM=x64 |
| cmake -G "Visual Studio 15 2017 Win64" -DCMAKE_INSTALL_PREFIX="%CD:\=/%/install2" -DCMAKE_C_FLAGS="/DPCRE_STATIC" ^ |
| -DPCRE_INCLUDE_DIR=%PCRE_ROOT%/include -DPCRE_LIBRARY=%PCRE_ROOT%/lib/v110/%PCRE_PLATFORM%/Release/static/utf8/pcre8.lib . |
| cmake --build . --config Release |
| |
| REM to test the exe |
| cd /Release |
| swig.exe -help |
| </pre> |
| </div> |
| |
| <p> |
| In addition to Release builds you can create a Debug build using: |
| </p> |
| <div class="shell"> |
| <pre>cmake --build . --config Debug</pre> |
| </div> |
| <p> |
| A Visual Studio solution file should be generated named swig.sln. This can be opened and debugged by running the swig project and setting the |
| Debugging Command Arguments. For example to debug one of the test-suite .i files included with the SWIG source use the following: |
| </p> |
| <div class="shell"> |
| <pre>-python -c++ -o C:\Temp\doxygen_parsing.cpp C:\swig\Examples\test-suite\doxygen_parsing.i</pre> |
| </div> |
| |
| <H4><a name="Windows_mingw_msys">3.3.1.2 Building swig.exe using MSYS2</a></H4> |
| |
| |
| <p> |
| Download and install MSYS2 from <a href="https://www.msys2.org/">www.msys2.org</a> (tested with version msys2-x86_64-20201109). |
| Launch the MSYS2 shell. |
| </p> |
| <p> |
| Install the packages needed to build swig:<br> |
| </p> |
| |
| <div class="shell"> |
| <pre> |
| pacman -S git autoconf automake bison gcc make pcre-devel |
| </pre> |
| </div> |
| |
| <p> |
| Clone the repository to /usr/src/: |
| </p> |
| |
| <div class="shell"> |
| <pre> |
| mkdir /usr/src/ |
| cd /usr/src/ |
| git clone https://github.com/swig/swig.git |
| </pre> |
| </div> |
| |
| <p> |
| Configure and build: |
| </p> |
| |
| <div class="shell"> |
| <pre> |
| cd /usr/src/swig |
| ./autogen.sh |
| ./configure |
| make |
| </pre> |
| </div> |
| |
| <p> |
| Finally you may also want to install SWIG: |
| </p> |
| |
| <div class="shell"> |
| <pre> |
| make install |
| </pre> |
| </div> |
| |
| <H4><a name="Windows_mingw_msys">3.3.1.3 Building swig.exe using MinGW and MSYS</a></H4> |
| |
| |
| <p> |
| The short abbreviated instructions follow... |
| </p> |
| |
| <ul> |
| <li>Install MinGW and MSYS from the <a href="http://www.mingw.org">MinGW</a> site. This provides a Unix environment on Windows. |
| <li>Follow the usual Unix instructions in the README file in the SWIG root directory to build swig.exe from the MinGW command prompt. |
| </ul> |
| |
| <p> |
| 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 <a href="http://www.swig.org/svn.html">SWIG Bleeding Edge</a>. |
| </p> |
| |
| <p> |
| <b>Pitfall note:</b> |
| 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. |
| </p> |
| |
| <ol> |
| <li> |
| Download the following packages from the <a href="http://www.mingw.org/download.shtml">MinGW download page</a> |
| or <a href="https://sourceforge.net/projects/mingw/files/">MinGW SourceForge download page</a>. |
| Note that at the time of writing, the majority of these are in the Current |
| release list and some are in the Snapshot or Previous release list. |
| <ul> |
| <li>MinGW-3.1.0-1.exe</li> |
| <li>MSYS-1.0.11-2004.04.30-1.exe</li> |
| <li>msysDTK-1.0.1.exe</li> |
| <li>bison-2.0-MSYS.tar.gz</li> |
| <li>msys-autoconf-2.59.tar.bz2</li> |
| <li>msys-automake-1.8.2.tar.bz2</li> |
| </ul> |
| </li> |
| |
| <li> |
| Install MinGW-3.1.0-1.exe (C:\MinGW is default location.) |
| </li> |
| |
| <li> |
| Install MSYS-1.0.11-2004.04.30-1.exe. Make sure you install it on the same |
| windows drive letter as MinGW (C:\msys\1.0 is default). |
| In the post install script, |
| <ul> |
| <li>Answer y to the "do you wish to continue with the post install?"</li> |
| <li>Answer y to the "do you have MinGW installed?"</li> |
| <li>Type in the folder in which you installed MinGW (C:/MinGW is default)</li> |
| </ul> |
| </li> |
| |
| <li> |
| Install msysDTK-1.0.1.exe to the same folder that you installed MSYS (C:\msys\1.0 is default). |
| </li> |
| |
| <li> |
| Copy the following to the MSYS install folder (C:\msys\1.0 is default): |
| <ul> |
| <li>msys-automake-1.8.2.tar.bz2</li> |
| <li>msys-autoconf-2.59.tar.bz2</li> |
| <li>bison-2.0-MSYS.tar.gz</li> |
| </ul> |
| </li> |
| |
| <li> |
| Start the MSYS command prompt and execute: |
| <div class="shell"><pre> |
| 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 |
| </pre></div> |
| </li> |
| |
| <li> |
| The very latest development version of SWIG is available from <a href="https://github.com/swig/swig">SWIG on Github</a> |
| and can be downloaded as a zip file or if you have Git installed, via Git. |
| Either download the latest <a href="https://github.com/swig/swig/archive/master.zip">Zip file</a> snapshot and unzip and rename the top level folder to /usr/src/swig. |
| |
| Otherwise if using Git, type in the following: |
| <div class="shell"><pre> |
| mkdir /usr/src |
| cd /usr/src |
| git clone https://github.com/swig/swig.git |
| </pre></div> |
| |
| <b>Pitfall note:</b> |
| If you want to place SWIG in a different folder to the proposed |
| /usr/src/swig, do not use MSYS emulated windows drive letters, because |
| the autotools will fail miserably on those. |
| </li> |
| |
| <li> |
| The PCRE third party library needs to be built next. |
| Download the latest PCRE source tarball, such as <tt>pcre-8.10.tar.bz2</tt>, from |
| <a href=http://www.pcre.org>PCRE</a> and place in the <tt>/usr/src/swig</tt> directory. |
| Build PCRE as a static library using the Tools/pcre-build.sh script as follows: |
| |
| <div class="shell"><pre> |
| cd /usr/src/swig |
| Tools/pcre-build.sh |
| </pre></div> |
| </li> |
| |
| <li> |
| You are now ready to build SWIG. Execute the following commands to build swig.exe: |
| <div class="shell"><pre> |
| cd /usr/src/swig |
| ./autogen.sh |
| ./configure |
| make |
| </pre></div> |
| </li> |
| </ol> |
| |
| |
| <H4><a name="Windows_cygwin">3.3.1.4 Building swig.exe using Cygwin</a></H4> |
| |
| |
| <p> |
| 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 <tt>autogen.sh</tt> script and will only need regenerating in circumstances such as changing the build system. |
| </p> |
| |
| |
| <H3><a name="Windows_examples_cygwin">3.3.2 Running the examples on Windows using Cygwin</a></H3> |
| |
| |
| <p> |
| 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. |
| </p> |
| |
| <H2><a name="Windows_interface_file">3.4 Microsoft extensions and other Windows quirks</a></H2> |
| |
| |
| <p> |
| 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 <tt>__declspec(dllimport)</tt>, <tt>__stdcall</tt> etc. |
| There is a Windows interface file, <tt>windows.i</tt>, to deal with these calling conventions though. |
| The file also contains typemaps for handling commonly used Windows specific types such as <tt>__int64</tt>, <tt>BOOL</tt>, <tt>DWORD</tt> etc. |
| Include it like you would any other interface file, for example: |
| </p> |
| |
| <div class="code"><pre> |
| %include <windows.i> |
| |
| __declspec(dllexport) ULONG __stdcall foo(DWORD, __int32); |
| </pre></div> |
| |
| <p>Note that if you follow Microsoft's recommendation of wrapping the |
| <tt>__declspec</tt> 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 <tt>export_lib.h</tt> and include |
| other headers which depend on it, you should use the <tt>%include</tt> directive |
| to include the definition explicitly. For example, if you had a header file, |
| <tt>bar.h</tt>, which depended on <tt>export_lib.h</tt>, your SWIG definition |
| file might look like:</p> |
| |
| <div class="code"><pre> |
| // bar.i |
| %module bar |
| %include <windows.i> |
| %include "export_lib.h" |
| %include "bar.h" |
| </pre></div> |
| |
| <p> |
| where export_lib.h may contain: |
| </p> |
| |
| <div class="code"><pre> |
| // export_lib.h |
| #define BAR_API __declspec(dllexport) |
| </pre></div> |
| |
| <p> |
| and bar.h may look like: |
| </p> |
| |
| <div class="code"><pre> |
| // bar.h |
| #include "export_lib.h" |
| BAR_API void bar_function(int, double); |
| </pre></div> |
| |
| <p> |
| Using the preprocessor to remove BAR_API is a popular simpler solution: |
| </p> |
| |
| <div class="code"><pre> |
| // bar.i |
| %module bar |
| #define BAR_API |
| %include "bar.h" |
| </pre></div> |
| |
| </body> |
| </html> |