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