docs/msw/install.txt

   1
   2 Installing wxWindows 2.0
   3 ------------------------
   4
   5 IMPORTANT NOTE: If you experience problems installing, please
   6 re-read this instructions and other related files (todo.txt,
   7 bugs.txt etc.) carefully before mailing wxwin-users or
   8 the author. Preferably, try to fix the problem first and
   9 then send a patch to the author.
  10
  11 Unarchiving
  12 -----------
  13
  14 If there is a setup program, run the setup program that comes with the Windows version.
  15 Do not install into a path that contains spaces. The installation program should set the
  16 WXWIN environment variable, which will be activated when your machine is rebooted.
  17
  18 If there is no setup program, it will come as a series of .zip
  19 files:
  20
  21 wx200gen.zip            Generic source code and samples (required)
  22 wx200msw.zip            Windows-specific source code and samples (required)
  23 wx200doc.zip            Documentation source code (not required)
  24 wx200hlp.zip            WinHelp documentation
  25 wx200pdf.zip            Acrobat PDF documentation
  26 wx200htm.zip            HTML documentation
  27 wx200vc.zip             MS VC++ 5.0 project files
  28 wx200cw.zip             Metrowerks CodeWarrior project files
  29
  30 Unarchive the required files plus any optional documentation
  31 files into a suitable directory such as c:\wx.
  32
  33 Other add-on packages are available from the wxWindows Web site, such as:
  34
  35 - glcanvas.zip. Use OpenGL in a wxWindows window.
  36 - ogl3.zip. Object Graphics Library: build network diagrams, CASE tools etc.
  37 - tex2rtf3.zip. Tex2RTF: create Windows Help, HTML, and Word RTF files from
  38   the same document source.
  39
  40 General installation notes
  41 --------------------------
  42
  43 Alter your WXWIN environment variable to point to this directory.
  44 For Cygwin or Mingw32 compilation, make sure WXWIN contains only
  45 forward slashes.
  46
  47 If installing from the CVS server, copy include/wx/msw/setup0.h to
  48 include/wx/msw/setup.h.
  49
  50 Compilation
  51 -----------
  52
  53 The following sections explain how to compile wxWindows with each supported
  54 compiler.
  55
  56 Visual C++ 4.0/5.0/6.0 compilation
  57 ----------------------------------
  58
  59 Using project files:
  60
  61 1. Unarchive wx200vc.zip, the VC++ 5 project makefiles.
  62 2. Open src/wxvc.dsp, set Debug or Release configuration, and
  63    compile. This will produce lib/wxvc.lib or lib/wxvc_debug.lib.
  64 3. Open a sample project file, choose a configuration, and compile.
  65    The project files don't use precompiled headers, to save
  66    space, but you can switch PCH compiling on for greater speed.
  67
  68 Using makefiles:
  69
  70 1. Make sure your WXWIN variable is set.
  71 2. Change directory to wx\src\msw. Type 'nmake -f makefile.vc' to
  72    make the wxWindows core library.
  73 3. Change directory to wx\samples and type 'nmake -f makefile.vc'
  74    to make all the samples. You can also make them individually.
  75
  76 To build the release version using makefiles, add FINAL=1 to your
  77 nmake invocation, both when building the library and for samples.
  78
  79 Use the 'clean' target to clean all objects, libraries and
  80 executables.
  81
  82 To build the DLL version using makefiles:
  83
  84 1. Change directory to wx\src\msw. Type 'nmake -f makefile.vc dll pch'
  85    to make both a suitable DLL and import library, and to build a
  86    suitable precompiled header file for compiling applications.
  87 2. Invoke a sample makefile with 'nmake -f makefile.vc WXUSINGDLL=1'.
  88
  89 Note (1): if you wish to use templates, please edit
  90 include\wx\msw\setup.h and set wxUSE_DEBUG_NEW_ALWAYS to 0.
  91 Without this, the redefinition of 'new' will cause problems in
  92 the headers. Alternatively, #undef new before including template headers.
  93 You will also need to set wxUSE_IOSTREAMH to 0 if you will be
  94 using templates, to avoid the non-template stream files being included
  95 within wxWindows.
  96
  97 Note (2): libraries and applications generated with makefiles and
  98 project files are unlikely to be compatible, so use one method or
  99 the other.
 100
 101 Note (3): VC++ 5's optimization code seems to be broken and can
 102 cause problems: this can be seen when deleting an object Dialog
 103 Editor, in Release mode with optimizations on. If in doubt,
 104 switch off optimisations, although this will result in much
 105 larger executables. It seems possible that the library can be created with
 106 strong optimization, so long as the application is not strongly
 107 optimized. For example, in wxWindows project, set to 'Minimum
 108 Size'. In Dialog Editor project, set to 'Customize: Favor Small
 109 Code' (and no others). This will then work.
 110
 111 Visual C++ 1.5 compilation
 112 --------------------------
 113
 114 1. Make sure your WXWIN variable is set, and uses the FAT (short
 115    name) form.
 116 2. Change directory to wx\src\msw. Type 'nmake -f makefile.dos' to
 117    make the wxWindows core library.
 118 3. Change directory to a sample, such as wx\samples\minimal, and
 119    type 'nmake -f makefile.dos'.
 120
 121 Add FINAL=1 to your makefile invocation to build the release
 122 versions of the library and samples.
 123
 124 Use the 'clean' target to clean all objects, libraries and
 125 executables.
 126
 127 Borland C++ 4.5/5.0 compilation
 128 -------------------------------
 129
 130 1. Make sure your WXWIN variable is set, and uses the FAT (short
 131    name) form if doing a 16-bit compile.
 132 2. Change directory to wx\src\msw. Type 'make -f makefile.b32' to
 133    make the wxWindows core library. Ignore the warnings about
 134    'XXX' not found in library.
 135 3. Change directory to a sample such as minimal, and type
 136   'make -f makefile.b32'.
 137 4. For release versions, recompile wxWindows and samples using
 138    'make -f makefile.b32 clean'
 139    'make -f makefile.b32 FINAL=1'
 140    for the library and samples.
 141
 142 Note: the wxWindows library and (some) samples compile in 16-bit mode
 143 using makefile.bcc, but at present the wxWindows resource system is switched
 144 off in this mode. See issues.txt for details.
 145
 146 Borland C++Builder compilation
 147 ------------------------------
 148
 149 C++Builder compilation is the same as for Borland C++ above.
 150
 151 Tested with C++Builder 1.0 and 3.0. Only makefiles are currently
 152 supplied.
 153
 154 Watcom C++ 10.6 compilation
 155 ---------------------------
 156
 157 1. Make sure your WXWIN variable is set, and uses the FAT (short
 158    name) form.
 159 2. Change directory to wx\src\msw. Type 'wmake -f makefile.wat' to
 160    make the wxWindows core library.
 161 3. Change directory to wx\samples\minimal and type 'wmake -f makefile.wat'
 162    to make this sample.
 163
 164 Metrowerks CodeWarrior compilation
 165 ----------------------------------
 166
 167 1. Downloaded and unzip wx200cw.zip.
 168 2. Load the make_cw.mcp project in wx\src, and compile.
 169 3. Load the make_cw.mcp project in wx\samples\minimal, and compile.
 170    Further project files for samples will be available in due
 171    course.
 172
 173 NOTES:
 174
 175 (a) Unfortunately CodeWarrior support is broken in this
 176 release. Stefan Csomor (csomor@advancedconcepts.ch) will rectify this shortly.
 177 (b) You need CodeWarrior Pro 4 plus the patches to 4.1 from the
 178 Metrowerks Web site.
 179
 180 Symantec C++ compilation
 181 ------------------------
 182
 183 1. Make sure your WXWIN variable is set, and uses the FAT (short
 184    name) form.
 185 2. Edit setup.h and set wxUSE_DRAG_AND_DROP to 0.
 186 3. Change directory to wx\src\msw. Type 'make -f makefile.sc' to
 187    make the wxWindows core library.
 188 4. Change directory to wx\samples\minimal and type 'make -f makefile.sc'
 189    to make this sample.
 190
 191 Note: the minimal sample doesn't link properly ('Error: no
 192 start address').
 193 32-bit compilation only (partially) supported at present, using SC++ 6.1.
 194 Some functionality is missing using this compiler (see makefile).
 195 Add -D__WIN95__ if your SC++ has Windows 95 support, and ignore
 196 Step (2). 16-bit compilation is left as an excercise for the user!
 197
 198 Salford C++ compilation
 199 -----------------------
 200
 201 1. Make sure your WXWIN variable is set, and uses the FAT (short
 202    name) form.
 203 2. Edit SALFORDDIR and RESOURCEDIR in src/makesl.env as per
 204    notes.
 205 3. Change directory to wx\src\msw. Type 'mk32 -f makefile.sl all' to
 206    make the wxWindows core library.
 207 4. Change directory to wx\samples\minimal and type 'mk32 -f makefile.sl'
 208    to make this sample.
 209
 210 Unfortunately, Salford C++ seems to have problems with its code generation for
 211 operations on objects, as seen in wxFrame::OnMenuHighlight
 212 (minimal sample) or wxWindow::SetValidator (mdi sample). Also the
 213 the debugging version of the library is 90MB, with samples coming in
 214 at 40MB :-) However, wxWindows at least makes a good test suite for
 215 improving the compiler.
 216
 217 Cygwin b19/b20/Mingw32 compilation
 218 ----------------------------------
 219
 220 wxWindows 2.0 supports Cygwin (formerly GnuWin32) b19, b20, Mingw32, and Mingw32/EGCS.
 221
 222 Thanks are due to Keith Garry Boyce (garp@opustel.com) and Cygnus for making
 223 it all possible.
 224
 225 From wxWindows 2.0 beta 9, both Cygwin and Mingw32 (the minimal
 226 distribution of Cygwin) can be used with the same makefiles.
 227
 228 Here are the steps required:
 229
 230 - Retrieve and install the latest beta of Cygwin, or Mingw32, as per the
 231   instructions with either of these packages.
 232
 233 - If using Mingw32 (including the EGCS variant), you need some
 234   extra files to use the wxWindows makefiles. You can find these
 235   files in ports/mingw32 on the ftp site or CD-ROM, as extra.zip.
 236   These should be extracted to the Mingw32 directory.
 237   If you have already have downloaded bison, flex, make, rm, mv
 238   from elsewhere, you won't need this.
 239
 240   IMPORTANT: also see mingw32.txt in this directory (docs/msw)
 241   about a fix that has to be applied to a Mingw32 header file.
 242
 243 - Modify the file wx/src/cygnus.bat (or mingw32.bat or mingegcs.bat)
 244   to set up appropriate variables, if necessary mounting drives.
 245   Run it before compiling.
 246
 247 - For Cygwin, make sure there's a \tmp directory on your
 248   Windows drive or bison will crash.
 249
 250 - Edit wx/src/makeg95.env and search for MINGW32. Take note of
 251   the comments for adjusting settings to suit Cygwin or
 252   Mingw32. Basically, this is just a case of adding the __MINGW32__ symbol
 253   to OPTIONS for Mingw32, or removing it for Cygnus Cygwin.
 254   For Mingw32/EGCS, add both __MINGW32__ and __EGCS__.
 255   You may need to remove -loldnames from WINLIBS for Mingw32, or add it for
 256   Cygwin.
 257
 258 - Mingw32 may not support winsock.h, so comment out
 259   socket-related files in src/msw/makefile.g95.
 260
 261 - Set your WXWIN variable to where wxWindows is installed.
 262   For Cygwin/Mingw32, use forward slashes in the path, not backslashes.
 263
 264 - Use the makefile.g95 files for compiling wxWindows and samples,
 265   e.g.:
 266   > cd c:\wx\src\msw
 267   > make -f makefile.g95
 268   > cd c:\wx\samples\minimal
 269   > make -f makefile.g95
 270
 271 - Use the 'strip' command to reduce executable size.
 272
 273 - With Cygnus Cygwin, you can invoke gdb --nw myfile.exe to
 274   debug an executable. If there are memory leaks, they will be
 275   flagged when the program quits.
 276
 277 - If using GnuWin32 b18, you will need to copy windres.exe
 278   from e.g. the Mingw32 distribution, to a directory in your path.
 279
 280 All targets have 'clean' targets to allow removal of object files
 281 and other intermediate compiler files.
 282
 283 Gotchas:
 284
 285 - libwx.a is 48 MB or more - but much less if compiled with no
 286   debug info (-g0) and level 4 optimization (-O4).
 287 - install.exe doesn't have built-in decompression because lzexpand.lib
 288   isn't available with Cygwin. However, you can use it with external
 289   decompression utilities.
 290 - Doesn't compile src/msw/ole files, so no drag and drop.
 291
 292 References:
 293
 294  - The GNU-WIN32 site is at
 295      http://www.cygnus.com/gnu-win32/
 296  - Mingw32 is available at:
 297      http://agnes.dida.physik.uni-essen.de/~janjaap/mingw32/index.html
 298  - See also http://web.ukonline.co.uk/julian.smart/wxwin/gnuwin32.htm
 299
 300 TWIN32 and gcc on Linux
 301 -----------------------
 302
 303 The wxWindows 2 for Windows port may be compiled using
 304 the TWIN32 emulator package from www.willows.com. However,
 305 TWIN32 is by no means finished so this should be taken as
 306 something to think about for the future, rather than
 307 a tool for writing products with.
 308
 309 Use makefile.twn in much the same way as makefile.g95, as
 310 described above. Not all sample makefiles are supplied yet.
 311
 312 For some reason, I found I had to copy TWIN32's Windows resource
 313 compiler (rc) to the current working directory for it to be found.
 314
 315 General Notes
 316 -------------
 317
 318 - Debugging: under Windows 95, debugging output isn't output in
 319   the same way that it is under NT or Windows 3.1. Set
 320   wxUSE_DBWIN32 to 1 if you wish to enable code to output debugging
 321   info to an external debug monitor, such as Andrew Tucker's DBWIN32.
 322   You can download DBWIN32 from:
 323
 324         http://ftp.digital.com/pub/micro/NT/WinSite/programr/dbwin32.zip
 325
 326   and it's also on the wxWindows CD-ROM under Packages.
 327
 328 - If you are installing wxWindows 2 from CVS, you may find that
 329   include/wx/msw/setup.h is missing. This is deliberate, to avoid
 330   developers' different setup.h configurations getting confused.
 331   Please copy setup0.h to setup.h before compiling.