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