2 Installing wxWindows 2.1
3 ------------------------
5 This is a beta release of wxWindows 2.1 for Microsoft
6 Windows 95, 98 and NT. This is not a production release,
7 although a huge number of bugs found in earlier versions
8 of wxWindows have been fixed.
10 IMPORTANT NOTE: If you experience problems installing, please
11 re-read this instructions and other related files (changes.txt,
12 readme.txt, notes on the Web site) carefully before mailing
13 wx-users or the author. Preferably, try to fix the problem first and
14 then send a patch to the author. Please report bugs using the
15 bug report form on the wxWindows web site.
20 A setup program is provided (setup.exe) to automatically copy files to a
21 directory on your hard disk. Do not install into a path that contains spaces.
22 The installation program should set the WXWIN environment variable, which
23 will be activated when your machine is rebooted. The setup
24 program contains the following:
26 - All common, generic and MSW-specific wxWindows source;
28 - documentation in Windows Help format;
29 - makefiles for most Windows compilers, plus BC++ and
31 - JPEG library source;
32 - TIFF library source;
33 - Object Graphics Library;
35 - Dialog Editor binary.
37 Alternatively, you may unarchive the set of .zip files by hand,
38 where x is the minor version number and y is the release number:
40 wx2_x_y_gen.zip Generic source code and samples (required)
41 wx2_x_y_msw.zip Windows-specific source code and samples (required)
42 wx2_x_y_doc.zip Documentation source code (not required)
43 wx2_x_y_hlp.zip WinHelp documentation
44 wx2_x_y_pdf.zip Acrobat PDF documentation
45 wx2_x_y_htm.zip HTML documentation
46 wx2_x_y_vc.zip MS VC++ 5.0 project files
47 wx2_x_y_cw.zip Metrowerks CodeWarrior project files
48 wx2_x_y_bc.zip BC++ 5 project files
49 jpeg.zip Use this to allow wxImage to read and write JPEG files
50 tiff.zip Use this to allow wxImage to read and write TIFF files
52 Unarchive the required files plus any optional documentation
53 files into a suitable directory such as c:\wx.
55 Other add-on packages are available from the wxWindows Web site, such as:
57 - mmedia.zip. Audio, CD, video access for Windows and Linux.
58 - ogl3.zip. Object Graphics Library: build network diagrams, CASE tools etc.
59 - tex2rtf3.zip. Tex2RTF: create Windows Help, HTML, and Word RTF files from
60 the same document source.
62 General installation notes
63 --------------------------
65 Alter your WXWIN environment variable to point to this directory.
66 For Cygwin or Mingw32 compilation, make sure WXWIN contains only
69 If installing from the CVS server, copy include/wx/msw/setup0.h to
70 include/wx/msw/setup.h and edit the resulting file to choose the featrues you
71 would like to compile wxWindows with[out].
76 The following sections explain how to compile wxWindows with each supported
79 Visual C++ 4.0/5.0/6.0 compilation
80 ----------------------------------
82 Using project files (VC++ 5 and 6 only):
84 1. Unarchive wx2_x_y_vc.zip, the VC++ 5/6 project makefiles.
85 2. Open src/wxvc.dsp, set Debug or Release configuration for
86 the wxvc project, and compile. Alternatively, use Batch Build
87 to build both Debug and Release configurations.
88 This will produce lib/wx.lib (release) and lib/wxd.lib (debug),
89 plus various subordinate libraries. It assumes you have
90 the TIFF and JPEG source, which is already in the setup
91 version of the distribution.
92 The project file src/wxvc_dll.dsp will make a DLL version of wxWindow,
93 which will go in lib/wxdll.[lib,dll] and lib/wxdlld.[lib,dll].
94 3. Open a sample project file, choose a configuration such as
95 Debug using Build | Set Active Configuration..., and compile.
96 The project files don't use precompiled headers, to save disk
97 space, but you can switch PCH compiling on for greater speed.
98 NOTE: you may also use samples/SamplesVC.dsw to access all
99 sample projects without opening each workspace individually.
100 You can use the Batch Build facility to make several samples
105 1. Make sure your WXWIN variable is set.
106 2. If you do NOT have the TIFF or JPEG source code, please remove
107 the tiff and jpeg targets from the 'all' target in
108 src\msw\makefile.vc. Also ensure the settings in
109 include\wx\msw\setup.h specify not to use JPEG or TIFF.
110 3. Change directory to wx\src\msw. Type:
112 'nmake -f makefile.vc'
114 to make the wxWindows core library with debug information
115 (wx\lib\wxd.lib), then
117 'nmake -f makefile.vc cleanall FINAL=1'
118 'nmake -f makefile.vc FINAL=1'
120 to make the wxWindows core library without debug information
122 4. Change directory to wx\samples and type 'nmake -f makefile.vc'
123 to make all the samples. You can also make them individually.
127 Use the 'cleanall' target to clean all objects, libraries and
130 To build the release version using makefiles, add FINAL=1 to your
131 nmake invocation, both when building the library and for samples.
132 You MUST use the 'cleanall' target (with FINAL=1 or FINAL=0)
133 before making a different configuration, because otherwise
134 object files used to build the previous configuration may be
135 used accidentally for the current configuation. You might see
136 this manifested in unexpected link errors or warnings. This problem
137 doesn't occur when using project files to build wxWindows.
139 Note that the wxWindows core library allows you to have debug
140 and release libraries available simultaneously, by compiling the
141 objects in different subdirectories, whereas samples must be
142 cleaned and re-made to build a different configuration.
144 To build the DLL version using makefiles:
146 1. Change directory to wx\src\msw. Type 'nmake -f makefile.vc dll pch'
147 to make both a suitable DLL and import library, and to build a
148 suitable precompiled header file for compiling applications.
149 The resulting libraries are called:
151 wx\lib\wx[version].lib(dll) (debug version)
152 wx\lib\wx[version].lib(dll) (release version, using FINAL=1)
154 2. Invoke a sample makefile with 'nmake -f makefile.vc WXUSINGDLL=1'
155 (or edit src\makeprog.vc to set WXUSINGDLL to 1 for all
158 Note (1): if you wish to use templates, please edit
159 include\wx\msw\setup.h and set wxUSE_DEBUG_NEW_ALWAYS to 0.
160 Without this, the redefinition of 'new' will cause problems in
161 the headers. Alternatively, #undef new before including template headers.
162 You will also need to set wxUSE_IOSTREAMH to 0 if you will be
163 using templates, to avoid the non-template stream files being included
166 Note (2): libraries and applications generated with makefiles and
167 project files are now (hopefully) compatible where static libraries
168 are concerned, but please exercise caution nevertheless and if
169 possible, use one method or the other.
171 Note (3): VC++ 5's optimization code seems to be broken and can
172 cause both compile and run-time problems: this can be seen when
173 deleting an object Dialog Editor, in Release mode with optimizations
174 on. If in doubt, switch off optimisations, although this will result in much
175 larger executables. It seems possible that the library can be created with
176 strong optimization, so long as the application is not strongly
177 optimized. For example, in wxWindows project, set to 'Minimum
178 Size'. In Dialog Editor project, set to 'Customize: Favor Small
179 Code' (and no others). This will then work.
181 Similarly, in VC++ 4, optimization can cause internal compiler
182 errors, so edit src\makevc.env and change /O1 to /Od before
183 trying build a release version of the library. Or, type:
185 nmake -f makefile.vc noopt FINAL=1
187 and then resume compilation in the normal way. This will build
188 troublesome files with no optimization. However, there now seems to be
189 an internal linker error using VC++ 4, in addition to internal
190 compiler errors for most of the samples, so this version of the compiler
191 cannot be recommended!
193 Note (4): some crash problems can be due to inconsistent compiler
194 options. If strange/weird/impossible things start to happen please
195 check (dumping IDE project file as makefile and doing text comparison
196 if necessary) that the project settings, especially the list of defined
197 symbols, struct packing, etc. are exactly the same for all items in
198 the project. After this, delete everything (including PCH) and recompile.
200 Note (5): for some further notes about upgrading your project
201 files to be compatible with wxWindows 2.1.14, please see
202 "Highlights of wxWindows 2.1.14" from the Download page of the
205 Note (6): to create your own IDE files, see the technical note on the
206 wxWindows web site or CD-ROM, entitled "Compiling wxWindows
207 applications in the VC++ IDE". You can also copy .dsp and .dsw
208 files from an existing wxWindows sample and adapt them.
210 Visual C++ 1.5 compilation (16-bit)
211 -----------------------------------
213 1. Make sure your WXWIN variable is set, and uses the FAT (short
215 2. Change directory to wx\src\msw. Type 'nmake -f makefile.dos' to
216 make the wxWindows core library.
217 3. Change directory to a sample, such as wx\samples\minimal, and
218 type 'nmake -f makefile.dos'.
220 Add FINAL=1 to your makefile invocation to build the release
221 versions of the library and samples.
223 Use the 'clean' target to clean all objects, libraries and
226 Borland C++ 4.5/5.0 compilation
227 -------------------------------
229 Compiling using the makefiles:
231 1. Make sure your WXWIN variable is set, and uses the FAT (short
232 name) form if doing a 16-bit compile.
233 2. Change directory to wx\src\msw. Type 'make -f makefile.b32' to
234 make the wxWindows core library. Ignore the warnings about
235 'XXX' not found in library.
236 3. Change directory to a sample or demo such as samples\minimal, and type
237 'make -f makefile.b32'.
238 4. For release versions, recompile wxWindows and samples using
239 'make -f makefile.b32 clean'
240 'make -f makefile.b32 FINAL=1'
241 for the library and samples.
243 Note (1): the wxWindows library and (some) samples compile in 16-bit mode
244 using makefile.bcc, but at present the wxWindows resource system is switched
245 off in this mode. See issues.txt for details.
247 Note (2): unfortunately most samples won't link in 16-bit mode,
248 because the automatic data segment exceeds 64K. The minimal
249 sample links and runs, however.
251 Note (3): the wxWindows makefiles assume byte structure alignment. Please
252 make sure that your own project or makefile settings use the
253 same alignment, or you could experience mysterious crashes. To
254 change the alignment, add a suitable option to the $(CFG) target code
255 in src/msw/makefile.b32.
257 Note (4): if you get undefined _SQL... symbols at link time,
258 either install odbc32.lib from the BC++ CD-ROM into your BC++ lib
259 directory, or set wxUSE_ODBC to 0 in include\wx\msw\setup.h and
260 recompile wxWindows. The same applies if compiling using the IDE.
262 Note (5): BC++ 4.5 (not 5.0) trips up over jdmerge.c in the JPEG folder;
263 you will therefore need to set wxUSE_LIBJPEG to 0 in setup.h and remove
264 the jpeg target from src\msw\makefile.b32, and remove jpeg from
267 Note (6): If using C++Builder 4 and above (BC++ 5.4 and above), change LINK=tlink32 to
268 LINK=ilink32 in src\makeb32.env. You may also need to disable
269 wxUSE_LIBJPEG because there is a conflict in the BC++ headers
270 (actually this problem seems to have gone away with 5.5 and SP1).
272 Note (7): If you wish debug messages to be sent to the console in
273 debug mode, edit src\makeb32.env and change /aa to /Tpe in
276 Compiling using the IDE files:
278 1. Load src\bc32.ide (Release settings)
279 2. Go to Options|Project... and specify the correct BC++ include and lib path for
281 3. Press F9 to compile the wxWindows library.
282 4. Load samples\bc32.ide.
283 5. Go to Options|Project... and specify the correct BC++ include and lib path for
285 6. Press F9 to compile the samples (build each node separately if
286 you prefer, by right clicking and choose Build Node).
287 7. Run each sample: you may need to run from each sample's directory
288 since some (notably the wxHTML samples) look for files
289 relative to the working directory.
291 Note (1): the samples project file contains a selection of
292 samples, and not all samples. The remaining samples can be made
293 with the makefiles. See also the demos hierarchy which doesn't
294 have any BC++ project files yet.
296 Note (2): to make the png, xpm, zlib, jpeg and tiff libraries (needed for
297 some samples) you need to compile them with bc32.ide.
299 Note (3): the debug version of the wxWindows library is about 40 MB, and the
300 release version is around 5 MB.
302 See also the file bc_ide.txt for further instructions and details
303 of how to create your own project files.
305 Borland C++Builder compilation
306 ------------------------------
308 C++Builder compilation is the same as for Borland C++ above.
310 Tested with C++Builder 1.0 and 3.0. Only makefiles are currently
313 Watcom C++ 10.6/11 compilation
314 ---------------------------
316 1. Make sure your WXWIN variable is set, and uses the DOS short
318 2. Change directory to wx\src\msw. Type 'wmake -f makefile.wat' to
319 make the wxWindows core library.
320 3. Change directory to wx\samples\minimal and type 'wmake -f makefile.wat'
321 to make this sample. Repeat for other samples of interest.
323 Note (1): setup.h overrides wxUSE_LIBJPEG and sets it to 0, since
324 imagjpeg.cpp doesn't compile.
325 Note (2): makewat.env uses the odbc32.lib supplied in wxWindows' lib\watcom
326 directory. See the notes in that directory.
327 Note (3): if variant.cpp is compiled with date/time class
328 options, the linker gives up. So the date/time option is switched
329 off for Watcom C++. Also, wxAutomationObject is not compiled with
331 Note (4): if Watcom can't read the precompiled header when
332 building a sample, try deleting src\msw\watcom.pch and
333 compiling the sample again.
334 Note (5): if you get _popen_ and _pclose_ link errors, try
335 recompiling wxWindows with XPM support disabled in setup.h.
336 Alternatively, make sure these lines exist at the top of
339 // Added by JACS for Watcom C++/wxWindows compilation (no popen/pclose functions)
344 Metrowerks CodeWarrior compilation
345 ----------------------------------
347 1. Downloaded and unzip wx2_x_y_cw.zip.
348 2. Load the make_cw.mcp project in wx\src, and compile.
349 3. Load the make_cw.mcp project in wx\samples\minimal, and compile.
350 Further project files for samples will be available in due
353 Note (1): you need CodeWarrior Pro 4 plus the patches to 4.1 from the
356 Note (2): unfortunately these files are not yet up-to-date for the
359 Symantec C++ compilation
360 ------------------------
362 1. Make sure your WXWIN variable is set, and uses the FAT (short
364 2. Edit setup.h and set wxUSE_DRAG_AND_DROP to 0.
365 3. Change directory to wx\src\msw. Type 'make -f makefile.sc' to
366 make the wxWindows core library.
367 4. Change directory to wx\samples\minimal and type 'make -f makefile.sc'
370 Note: the minimal sample doesn't link properly ('Error: no
372 32-bit compilation only (partially) supported at present, using SC++ 6.1.
373 Some functionality is missing using this compiler (see makefile).
374 Add -D__WIN95__ if your SC++ has Windows 95 support, and ignore
375 Step (2). 16-bit compilation is left as an excercise for the user!
377 Salford C++ compilation
378 -----------------------
380 1. Make sure your WXWIN variable is set, and uses the FAT (short
382 2. Edit SALFORDDIR and RESOURCEDIR in src/makesl.env as per
384 3. Change directory to wx\src\msw. Type 'mk32 -f makefile.sl all' to
385 make the wxWindows core library.
386 4. Change directory to wx\samples\minimal and type 'mk32 -f makefile.sl'
389 Unfortunately, Salford C++ seems to have problems with its code generation for
390 operations on objects, as seen in wxFrame::OnMenuHighlight
391 (minimal sample) or wxWindow::SetValidator (mdi sample). Also the
392 the debugging version of the library is 90MB, with samples coming in
393 at 40MB :-) However, wxWindows at least makes a good test suite for
394 improving the compiler.
396 Cygwin b19/b20/Mingw32 compilation
397 ----------------------------------
399 wxWindows 2 supports Cygwin (formerly GnuWin32) b19, b20, Mingw32,
402 Thanks are due to Keith Garry Boyce (garp@opustel.com) and Cygnus for making
405 From wxWindows 2.0 beta 9, both Cygwin and Mingw32 (the minimal
406 distribution of Cygwin) can be used with the same makefiles.
408 Here are the steps required:
410 - Retrieve and install the latest beta of Cygwin, or Mingw32, as per the
411 instructions with either of these packages.
413 - If using Mingw32 (including the EGCS variant), you need some
414 extra files to use the wxWindows makefiles. You can find these
415 files in ports/mingw32 on the ftp site or CD-ROM, as extra.zip.
416 These should be extracted to the Mingw32 directory.
417 If you have already have downloaded bison, flex, make, rm, cp, mv
418 from elsewhere, you won't need this.
420 If using Mingw32 2.8.1, see also see mingw32.txt in this directory
421 (docs/msw) about a fix that has to be applied to a Mingw32 header file.
423 If using Mingw32 2.95 and below with wxWindows 2.1 or above, you
424 must hand-patch in Mingw32-gcc295.patches (located in the top-level of the
425 wxWindows 2 installation). Mingw32 2.95.2 and above contain the
428 - Modify the file wx/src/cygnus.bat (or mingw32.bat or mingegcs.bat)
429 to set up appropriate variables, if necessary mounting drives.
430 Run it before compiling.
432 - For Cygwin, make sure there's a \tmp directory on your
433 Windows drive or bison will crash (actually you don't need this
434 for ordinary wxWindows compilation: a pre-generated .c file is
437 - Edit wx/src/makeg95.env and set the MINGW32 variable at the top of
438 the file to either 1 (you have Mingw32) or 0 (you have Cygwin32).
439 If using MINGW32, also set the MINGW32VERSION variable
442 - Mingw32 may not support winsock.h, so if you have a problem
443 here, comment out socket-related files in src/msw/makefile.g95.
445 - Set your WXWIN variable to where wxWindows is installed.
446 *** IMPORTANT: For Cygwin/Mingw32, use forward slashes in the path, not
449 - Use the makefile.g95 files for compiling wxWindows and samples,
452 > make -f makefile.g95
453 > cd c:\wx\samples\minimal
454 > make -f makefile.g95
456 Ignore the warning about the default entry point.
458 - Use the 'strip' command to reduce executable size.
460 - With Cygnus Cygwin, you can invoke gdb --nw myfile.exe to
461 debug an executable. If there are memory leaks, they will be
462 flagged when the program quits.
464 - If using GnuWin32 b18, you will need to copy windres.exe
465 from e.g. the Mingw32 distribution, to a directory in your path.
467 All targets have 'clean' targets to allow removal of object files
468 and other intermediate compiler files.
472 1. See also the Cygwin/Mingw32 on the web site or CD-ROM for
473 further information about using wxWindows with these compilers.
475 2. libwx.a is 48 MB or more - but much less if compiled with no
476 debug info (-g0) and level 4 optimization (-O4).
478 3. There's a bug in Mingw32 headers for some early distributions.
480 in include/windows32/defines.h, where it says:
482 #define LPSTR_TEXTCALLBACKA (LPSTR)-1L)
486 #define LPSTR_TEXTCALLBACKA ((LPSTR)-1L)
490 4. If there's a problem with the copy command in
491 src/msw/makefile.g95, you may need to change the COPY and
492 COPYSEP variables in makeg95.env.
494 5. If there's a problem executing the windres program, try
495 commenting out RCPREPROCESSOR in makeg95.env.
497 6. OpenGL support should work with Mingw32 as-is. However,
498 if you wish to generate import libraries appropriate either for
499 the MS OpenGL libraries or the SGI OpenGL libraries, go to
500 include/wx/msw/gl and use:
502 dlltool -k -d opengl.def -llibopengl.a
506 dlltool -k -d opengl32.def -llibopengl32.a
508 and similarly for glu[32].def.
512 - The GNU-WIN32 site is at
513 http://www.cygnus.com/gnu-win32/
514 - Mingw32 is available at:
515 ftp://ftp.xraylith.wisc.edu/pub/khan/gnu-win32/mingw32/gcc-2.95/
516 - See also http://web.ukonline.co.uk/julian.smart/wxwin/gnuwin32.htm
518 TWIN32 and gcc on Linux
519 -----------------------
521 The wxWindows 2 for Windows port may be compiled using
522 the TWIN32 emulator package from www.willows.com. However,
523 TWIN32 is by no means finished so this should be taken as
524 something to think about for the future, rather than
525 a tool for writing products with.
527 Use makefile.twn in much the same way as makefile.g95, as
528 described above. Not all sample makefiles are supplied yet.
530 For some reason, I found I had to copy TWIN32's Windows resource
531 compiler (rc) to the current working directory for it to be found.
536 - Debugging: under Windows 95, debugging output isn't output in
537 the same way that it is under NT or Windows 3.1.
538 Please see DebugView (bin/dbgview.exe in the distribution), also
539 available from http://www.sysinternals.com and on the wxWindows CD-ROM
542 - If you are installing wxWindows 2 from CVS, you may find that
543 include/wx/msw/setup.h is missing. This is deliberate, to avoid
544 developers' different setup.h configurations getting confused.
545 Please copy setup0.h to setup.h before compiling.