diff options
Diffstat (limited to 'Doc/Manual/Windows.html')
| -rw-r--r-- | Doc/Manual/Windows.html | 377 |
1 files changed, 377 insertions, 0 deletions
diff --git a/Doc/Manual/Windows.html b/Doc/Manual/Windows.html new file mode 100644 index 0000000..5d16a8b --- /dev/null +++ b/Doc/Manual/Windows.html @@ -0,0 +1,377 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<title>Getting started on Windows</title> +<link rel="stylesheet" type="text/css" href="style.css"> +</head> + +<body bgcolor="#ffffff"> +<H1><a name="Windows"></a>3 Getting started on Windows </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_mingw_msys">Building swig.exe using MinGW and MSYS</a> +<li><a href="#Windows_cygwin">Building swig.exe using Cygwin</a> +<li><a href="#Windows_building_alternatives">Building swig.exe alternatives</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"></a>3.1 Installation on Windows</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"></a>3.1.1 Windows Executable</H3> + + +<p> +The swigwin distribution contains the SWIG Windows executable, swig.exe, which will run on 32 bit versions of Windows, ie Windows 95/98/ME/NT/2000/XP. +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"></a>3.2 SWIG Windows Examples</H2> + + +<p> +Using Microsoft Visual C++ is the most common approach to compiling and linking SWIG's output. +The Examples directory has a few Visual C++ project files (.dsp files). +These were produced by Visual C++ 6, although they should also work in Visual C++ 5. +Later versions of Visual Studio should also be able to open and convert these project files. +The C# examples come with .NET 2003 solution (.sln) and 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"></a>3.2.1 Instructions for using the Examples with Visual Studio</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 create a workspace for you (.dsw file). +Ensure the Release build is selected then do a Rebuild All from the Build menu. +The required environment variables are displayed with their current values. +</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"></a>3.2.1.1 C#</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 .NET 2003 or later, select Release Build, and do a Rebuild All from the Build menu. +The accompanying C# and C++ project files are automatically used by the solution file. +</p> + + +<H4><a name="Windows_java"></a>3.2.1.2 Java</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"></a>3.2.1.3 Perl</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"></a>3.2.1.4 Python</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"></a>3.2.1.5 TCL</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"></a>3.2.1.6 R</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"></a>3.2.1.7 Ruby</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"></a>3.2.2 Instructions for using the Examples with other compilers</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"></a>3.3 SWIG on Cygwin and MinGW</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 ANSI C/C++ compiler. However, this is not a recommended approach as the prebuilt executable is supplied. +</p> + +<H3><a name="Windows_swig_exe"></a>3.3.1 Building swig.exe on Windows</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_mingw_msys"></a>3.3.1.1 Building swig.exe using MinGW and MSYS</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 SVN follow... +Note that the instructions for obtaining SWIG from SVN are also online at <a href="http://www.swig.org/svn.html">SWIG SVN</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="http://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 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> + To get the latest SWIG SVN (version from Subversion source control), type in the following: +<div class="shell"><pre> +mkdir /usr/src +cd /usr/src +svn co https://swig.svn.sourceforge.net/svnroot/swig/trunk swig +</pre></div> + + <b>Pitfall note:</b> +If you want to check out SWIG to 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> + 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"></a>3.3.1.2 Building swig.exe using Cygwin</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> + +<H4><a name="Windows_building_alternatives"></a>3.3.1.3 Building swig.exe alternatives</H4> + + +<p> +If you don't want to install Cygwin or MinGW, use a different compiler to build +SWIG. For example, all the source code files can be added to a Visual C++ project +file in order to build swig.exe from the Visual C++ IDE. +</p> + + +<H3><a name="Windows_examples_cygwin"></a>3.3.2 Running the examples on Windows using Cygwin</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"></a>3.4 Microsoft extensions and other Windows quirks</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> + + +</body> +</html> |