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