Doc/Manual/Windows.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <title>Getting started on Windows</title>
   5 <link rel="stylesheet" type="text/css" href="style.css">
   6 </head>
   7
   8 <body bgcolor="#ffffff">
   9 <H1><a name="Windows"></a>3 Getting started on Windows </H1>
  10 <!-- INDEX -->
  11 <div class="sectiontoc">
  12 <ul>
  13 <li><a href="#Windows_installation">Installation on Windows</a>
  14 <ul>
  15 <li><a href="#Windows_executable">Windows Executable</a>
  16 </ul>
  17 <li><a href="#Windows_examples">SWIG Windows Examples</a>
  18 <ul>
  19 <li><a href="#Windows_visual_studio">Instructions for using the Examples with Visual Studio</a>
  20 <ul>
  21 <li><a href="#Windows_csharp">C#</a>
  22 <li><a href="#Windows_java">Java</a>
  23 <li><a href="#Windows_perl">Perl</a>
  24 <li><a href="#Windows_python">Python</a>
  25 <li><a href="#Windows_tcl">TCL</a>
  26 <li><a href="#Windows_r">R</a>
  27 <li><a href="#Windows_ruby">Ruby</a>
  28 </ul>
  29 <li><a href="#Windows_other_compilers">Instructions for using the Examples with other compilers</a>
  30 </ul>
  31 <li><a href="#Windows_cygwin_mingw">SWIG on Cygwin and MinGW</a>
  32 <ul>
  33 <li><a href="#Windows_swig_exe">Building swig.exe on Windows</a>
  34 <ul>
  35 <li><a href="#Windows_mingw_msys">Building swig.exe using MinGW and MSYS</a>
  36 <li><a href="#Windows_cygwin">Building swig.exe using Cygwin</a>
  37 <li><a href="#Windows_building_alternatives">Building swig.exe alternatives</a>
  38 </ul>
  39 <li><a href="#Windows_examples_cygwin">Running the examples on Windows using Cygwin</a>
  40 </ul>
  41 <li><a href="#Windows_interface_file">Microsoft extensions and other Windows quirks</a>
  42 </ul>
  43 </div>
  44 <!-- INDEX -->
  45
  46
  47
  48 <p>
  49 This chapter describes SWIG usage on Microsoft Windows.
  50 Installing SWIG and running the examples is covered as well as building the SWIG executable.
  51 Usage within the Unix like environments MinGW and Cygwin is also detailed.
  52 </p>
  53
  54
  55 <H2><a name="Windows_installation"></a>3.1 Installation on Windows</H2>
  56
  57
  58 <p>
  59 SWIG does not come with the usual Windows type installation program, however it is quite easy to get started. The main steps are:
  60 </p>
  61 <ul>
  62         <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.
  63         <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++.
  64 </ul>
  65
  66 <H3><a name="Windows_executable"></a>3.1.1 Windows Executable</H3>
  67
  68
  69 <p>
  70 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.
  71 If you want to build your own swig.exe have a look at <a href="#Windows_swig_exe">Building swig.exe on Windows</a>.
  72 </p>
  73
  74
  75 <H2><a name="Windows_examples"></a>3.2 SWIG Windows Examples</H2>
  76
  77
  78 <p>
  79 Using Microsoft Visual C++ is the most common approach to compiling and linking SWIG's output.
  80 The Examples directory has a few Visual C++ project files (.dsp files).
  81 These were produced by Visual C++ 6, although they should also work in Visual C++ 5.
  82 Later versions of Visual Studio should also be able to open and convert these project files.
  83 The C# examples come with .NET 2003 solution (.sln) and project files instead of Visual C++ 6 project files.
  84 The project files have been set up to execute SWIG in a custom build rule for the SWIG interface (.i) file.
  85 Alternatively run the <a href="#Windows_examples_cygwin">examples using Cygwin</a>.
  86
  87 <p>
  88 More information on each of the examples is available with the examples distributed with SWIG (Examples/index.html).
  89
  90 <H3><a name="Windows_visual_studio"></a>3.2.1 Instructions for using the Examples with Visual Studio</H3>
  91
  92
  93 <p>
  94 Ensure the SWIG executable is as supplied in the SWIG root directory in order for the examples to work.
  95 Most languages require some environment variables to be set <b>before</b> running Visual C++.
  96 Note that Visual C++ must be re-started to pick up any changes in environment variables.
  97 Open up an example .dsp file, Visual C++ will create a workspace for you (.dsw file).
  98 Ensure the Release build is selected then do a Rebuild All from the Build menu.
  99 The required environment variables are displayed with their current values.
 100 </p>
 101 <p>
 102 The list of required environment variables for each module language is also listed below.
 103 They are usually set from the Control Panel and System properties, but this depends on which flavour of Windows you are running.
 104 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.
 105 If you are interested in how the project files are set up there is explanatory information in some of the language module's documentation.
 106 </p>
 107
 108 <H4><a name="Windows_csharp"></a>3.2.1.1 C#</H4>
 109
 110
 111 <p>
 112 The C# examples do not require any environment variables to be set as a C# project file is included.
 113 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.
 114 The accompanying C# and C++ project files are automatically used by the solution file.
 115 </p>
 116
 117
 118 <H4><a name="Windows_java"></a>3.2.1.2 Java</H4>
 119
 120
 121 <p>
 122 <b><tt>JAVA_INCLUDE</tt></b> : Set this to the directory containing jni.h<br>
 123 <b><tt>JAVA_BIN</tt></b> : Set this to the bin directory containing javac.exe<p>
 124 Example using JDK1.3:<br>
 125 <tt>
 126 JAVA_INCLUDE: D:\jdk1.3\include<br>
 127 JAVA_BIN: D:\jdk1.3\bin<br>
 128 </tt>
 129 </p>
 130
 131
 132 <H4><a name="Windows_perl"></a>3.2.1.3 Perl</H4>
 133
 134
 135 <p>
 136 <b><tt>PERL5_INCLUDE</tt></b> : Set this to the directory containing perl.h<br>
 137 <b><tt>PERL5_LIB</tt></b> : Set this to the Perl library including path for linking<p>
 138 Example using nsPerl 5.004_04:<p>
 139 <tt>
 140 PERL5_INCLUDE: D:\nsPerl5.004_04\lib\CORE<br>
 141 PERL5_LIB: D:\nsPerl5.004_04\lib\CORE\perl.lib<br>
 142 </tt>
 143 </p>
 144
 145
 146 <H4><a name="Windows_python"></a>3.2.1.4 Python</H4>
 147
 148
 149 <p>
 150 <b><tt>PYTHON_INCLUDE</tt></b> : Set this to the directory that contains python.h<br>
 151 <b><tt>PYTHON_LIB</tt></b> : Set this to the python library including path for linking<p>
 152 Example using Python 2.1.1:<br>
 153 <tt>
 154 PYTHON_INCLUDE: D:\python21\include<br>
 155 PYTHON_LIB: D:\python21\libs\python21.lib<br>
 156 </tt>
 157 </p>
 158
 159
 160 <H4><a name="Windows_tcl"></a>3.2.1.5 TCL</H4>
 161
 162
 163 <p>
 164 <b><tt>TCL_INCLUDE</tt></b> : Set this to the directory containing tcl.h<br>
 165 <b><tt>TCL_LIB</tt></b> : Set this to the TCL library including path for linking<p>
 166 Example using ActiveTcl 8.3.3.3 <br>
 167 <tt>
 168 TCL_INCLUDE: D:\tcl\include<br>
 169 TCL_LIB: D:\tcl\lib\tcl83.lib<br>
 170 </tt>
 171 </p>
 172
 173
 174 <H4><a name="Windows_r"></a>3.2.1.6 R</H4>
 175
 176
 177 <p>
 178 <b><tt>R_INCLUDE</tt></b> : Set this to the directory containing R.h<br>
 179 <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>
 180 Example using R 2.5.1:<br>
 181 <tt>
 182 R_INCLUDE: C:\Program Files\R\R-2.5.1\include<br>
 183 R_LIB: C:\Program Files\R\R-2.5.1\bin\Rdll.lib<br>
 184 </tt>
 185 </p>
 186
 187
 188 <H4><a name="Windows_ruby"></a>3.2.1.7 Ruby</H4>
 189
 190
 191 <p>
 192 <b><tt>RUBY_INCLUDE</tt></b> : Set this to the directory containing ruby.h<br>
 193 <b><tt>RUBY_LIB</tt></b> : Set this to the ruby library including path for linking<p>
 194 Example using Ruby 1.6.4:<br>
 195 <tt>
 196 RUBY_INCLUDE: D:\ruby\lib\ruby\1.6\i586-mswin32<br>
 197 RUBY_LIB: D:\ruby\lib\mswin32-ruby16.lib<br>
 198 </tt>
 199 </p>
 200
 201
 202 <H3><a name="Windows_other_compilers"></a>3.2.2 Instructions for using the Examples with other compilers</H3>
 203
 204
 205 <p>
 206 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.
 207 </p>
 208
 209 <H2><a name="Windows_cygwin_mingw"></a>3.3 SWIG on Cygwin and MinGW</H2>
 210
 211
 212 <p>
 213 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.
 214 </p>
 215
 216 <H3><a name="Windows_swig_exe"></a>3.3.1 Building swig.exe on Windows</H3>
 217
 218
 219 <p>
 220 If you want to replicate the build of swig.exe that comes with the download, follow the MinGW instructions below.
 221 This is not necessary to use the supplied swig.exe.
 222 This information is provided for those that want to modify the SWIG source code in a Windows environment.
 223 Normally this is not needed, so most people will want to ignore this section.
 224 </p>
 225
 226 <H4><a name="Windows_mingw_msys"></a>3.3.1.1 Building swig.exe using MinGW and MSYS</H4>
 227
 228
 229 <p>
 230 The short abbreviated instructions follow...
 231 </p>
 232
 233 <ul>
 234     <li>Install MinGW and MSYS from the <a href="http://www.mingw.org">MinGW</a> site. This provides a Unix environment on Windows.
 235     <li>Follow the usual Unix instructions in the README file in the SWIG root directory to build swig.exe from the MinGW command prompt.
 236 </ul>
 237
 238 <p>
 239 The step by step instructions to download and install MinGW and MSYS, then download and build the latest version of SWIG from SVN follow...
 240 Note that the instructions for obtaining SWIG from SVN are also online at <a href="http://www.swig.org/svn.html">SWIG SVN</a>.
 241 </p>
 242
 243 <p>
 244 <b>Pitfall note:</b>
 245 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.
 246 </p>
 247
 248 <ol>
 249   <li>
 250   Download the following packages from the <a href="http://www.mingw.org/download.shtml">MinGW download page</a>
 251   or <a href="http://sourceforge.net/projects/mingw/files/">MinGW SourceForge download page</a>.
 252   Note that at the time of writing, the majority of these are in the Current
 253   release list and some are in the Snapshot or Previous release list.
 254   <ul>
 255     <li>MinGW-3.1.0-1.exe</li>
 256     <li>MSYS-1.0.11-2004.04.30-1.exe</li>
 257     <li>msysDTK-1.0.1.exe</li>
 258     <li>bison-2.0-MSYS.tar.gz</li>
 259     <li>msys-autoconf-2.59.tar.bz2</li>
 260     <li>msys-automake-1.8.2.tar.bz2</li>
 261   </ul>
 262   </li>
 263
 264   <li>
 265   Install MinGW-3.1.0-1.exe (C:\MinGW is default location.)
 266   </li>
 267
 268   <li>
 269   Install MSYS-1.0.11-2004.04.30-1.exe. Make sure you install it on the same
 270   windows drive letter as MinGW (C:\msys\1.0 is default).
 271   In the post install script,
 272   <ul>
 273     <li>Answer y to the "do you wish to continue with the post install?"</li>
 274     <li>Answer y to the "do you have MinGW installed?"</li>
 275     <li>Type in the the folder in which you installed MinGW (C:/MinGW is default)</li>
 276   </ul>
 277   </li>
 278
 279   <li>
 280   Install msysDTK-1.0.1.exe to the same folder that you installed MSYS (C:\msys\1.0 is default).
 281   </li>
 282
 283   <li>
 284   Copy the following to the MSYS install folder (C:\msys\1.0 is default):
 285   <ul>
 286     <li>msys-automake-1.8.2.tar.bz2</li>
 287     <li>msys-autoconf-2.59.tar.bz2</li>
 288     <li>bison-2.0-MSYS.tar.gz</li>
 289   </ul>
 290   </li>
 291
 292   <li>
 293   Start the MSYS command prompt and execute:
 294 <div class="shell"><pre>
 295 cd /
 296 tar -jxf msys-automake-1.8.2.tar.bz2
 297 tar -jxf msys-autoconf-2.59.tar.bz2
 298 tar -zxf bison-2.0-MSYS.tar.gz
 299 </pre></div>
 300   </li>
 301
 302   <li>
 303   To get the latest SWIG SVN (version from Subversion source control), type in the following:
 304 <div class="shell"><pre>
 305 mkdir /usr/src
 306 cd /usr/src
 307 svn co https://swig.svn.sourceforge.net/svnroot/swig/trunk swig
 308 </pre></div>
 309
 310   <b>Pitfall note:</b>
 311 If you want to check out SWIG to a different folder to the proposed
 312 /usr/src/swig, do not use MSYS emulated windows drive letters, because
 313 the autotools will fail miserably on those.
 314   </li>
 315
 316   <li>
 317   You are now ready to build SWIG. Execute the following commands to build swig.exe:
 318 <div class="shell"><pre>
 319 cd /usr/src/swig
 320 ./autogen.sh
 321 ./configure
 322 make
 323 </pre></div>
 324   </li>
 325 </ol>
 326
 327
 328 <H4><a name="Windows_cygwin"></a>3.3.1.2 Building swig.exe using Cygwin</H4>
 329
 330
 331 <p>
 332 Note that SWIG can also be built using Cygwin.
 333 However, SWIG will then require the Cygwin DLL when executing.
 334 Follow the Unix instructions in the README file in the SWIG root directory.
 335 Note that the Cygwin environment will also allow one to regenerate the autotool generated files which are supplied with the release distribution.
 336 These files are generated using the <tt>autogen.sh</tt> script and will only need regenerating in circumstances such as changing the build system.
 337 </p>
 338
 339 <H4><a name="Windows_building_alternatives"></a>3.3.1.3 Building swig.exe alternatives</H4>
 340
 341
 342 <p>
 343 If you don't want to install Cygwin or MinGW, use a different compiler to build
 344 SWIG. For example, all the source code files can be added to a Visual C++ project
 345 file in order to build swig.exe from the Visual C++ IDE.
 346 </p>
 347
 348
 349 <H3><a name="Windows_examples_cygwin"></a>3.3.2 Running the examples on Windows using Cygwin</H3>
 350
 351
 352 <p>
 353 The examples and test-suite work as successfully on Cygwin as on any other Unix operating system.
 354 The modules which are known to work are Python, Tcl, Perl, Ruby, Java and C#.
 355 Follow the Unix instructions in the README file in the SWIG root directory to build the examples.
 356 </p>
 357
 358 <H2><a name="Windows_interface_file"></a>3.4 Microsoft extensions and other Windows quirks</H2>
 359
 360
 361 <p>
 362 A common problem when using SWIG on Windows are the Microsoft function calling conventions which are not in the C++ standard.
 363 SWIG parses ISO C/C++ so cannot deal with proprietary conventions such as <tt>__declspec(dllimport)</tt>, <tt>__stdcall</tt> etc.
 364 There is a Windows interface file, <tt>windows.i</tt>, to deal with these calling conventions though.
 365 The file also contains typemaps for handling commonly used Windows specific types such as <tt>__int64</tt>, <tt>BOOL</tt>, <tt>DWORD</tt> etc.
 366 Include it like you would any other interface file, for example:
 367 </p>
 368
 369 <div class="code"><pre>
 370 %include &lt;windows.i&gt;
 371
 372 __declspec(dllexport) ULONG __stdcall foo(DWORD, __int32);
 373 </pre></div>
 374
 375
 376 </body>
 377 </html>