]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/msw/install.txt
Put ~/.mailcap to head of search list so local settings override
[wxWidgets.git] / docs / msw / install.txt
... / ...
CommitLineData
1
2Installing wxWindows 2.3
3------------------------
4
5This is wxWindows 2.3 for Microsoft Windows 9x/ME, Windows NT,
6Windows 2000 and Windows XP. This is an unstable development release.
7
8Please note that the library naming conventions for VC++
9compilation have changed between 2.3.1 and 2.3.2. This means that
10you will need to change your application project files. See the
11relevant section below for details.
12
13IMPORTANT NOTE: If you experience problems installing, please
14re-read this instructions and other related files (changes.txt,
15readme.txt, notes on the Web site) carefully before mailing
16wx-users or the author. Preferably, try to fix the problem first and
17then send a patch to the author. Please report bugs using the
18bug report form on the wxWindows web site.
19
20Unarchiving
21-----------
22
23A setup program is provided (setup.exe) to automatically copy files to a
24directory on your hard disk. Do not install into a path that contains spaces.
25The installation program should set the WXWIN environment variable, which
26will be activated when your machine is rebooted. The setup
27program contains the following:
28
29- All common, generic and MSW-specific wxWindows source;
30- samples;
31- documentation in Windows Help format;
32- makefiles for most Windows compilers, plus BC++ and
33 VC++ IDE files;
34- JPEG library source;
35- TIFF library source;
36- Object Graphics Library;
37- Tex2RTF source;
38- Dialog Editor binary.
39
40Alternatively, you may unarchive the .zip form by hand:
41wxMSW-x.y.z.zip where x.y.z is the version number.
42
43Unarchive the required files plus any optional documentation
44files into a suitable directory such as c:\wx.
45
46Other add-on packages are available from the wxWindows Web site, such as:
47
48- mmedia.zip. Audio, CD, video access for Windows and Linux.
49- ogl3.zip. Object Graphics Library: build network diagrams, CASE tools etc.
50- tex2rtf3.zip. Tex2RTF: create Windows Help, HTML, and Word RTF files from
51 the same document source.
52
53General installation notes
54--------------------------
55
56Alter your WXWIN environment variable to point to this directory.
57For Cygwin or Mingw32 compilation, make sure WXWIN contains only
58forward slashes.
59
60If installing from the CVS server, copy include/wx/msw/setup0.h to
61include/wx/msw/setup.h and edit the resulting file to choose
62the features you would like to compile wxWindows with[out].
63
64Compilation
65-----------
66
67The following sections explain how to compile wxWindows with each supported
68compiler.
69
70Visual C++ 6.0 compilation
71---------------------------
72
73Using project files (VC++ 6 only):
74
751. Unarchive wxWindows-x.y.z-vc.zip, the VC++ 6 project
76 makefiles (already included in wxMSW-x.y.z.zip and the setup version).
772. Open src/wxWindows.dsp, which has configurations for static
78 compilation or DLL compilation, and each of these available in
79 Unicode/ANSI and Debug/Release variations. Normally you'll use
80 a static linking ANSI configuration. Choose the Win32 Debug or
81 Win32 Release configuration for the wxWindows project, and compile.
82 Alternatively, use Batch Build to build more than one
83 configuration.
84 The following libraries will be produced depending on chosen
85 configuration:
86
87 wxmsw.lib wxmswd.lib ; ANSI Release/Debug
88 wxmswu.lib wxmswud.lib ; UNICODE Release/Debug
89 wxmsw23x.lib wxmsw23xd.lib ; ANSI DLL Release/Debug
90 wxmsw23xu.lib wxmsw23xud.lib ; UNICODE DLL Release/Debug
91
92 It will also produce similar variations on jpeg.lib, png.lib,
93 tiff.lib, zlib.lib, and regex.lib.
943. Open a sample project file, choose a configuration such as
95 Win32 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/samples.dsw to access all
99 sample projects without opening each workspace individually.
100 You can use the Batch Build facility to make several samples
101 at a time.
102
103Using makefiles:
104
1051. Make sure your WXWIN variable is set.
1062. 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.
1103. Change directory to wx\src\msw. Type:
111
112 'nmake -f makefile.vc'
113
114 to make the wxWindows core library with debug information
115 (wx\lib\wxd.lib), then
116
117 'nmake -f makefile.vc cleanall FINAL=1'
118 'nmake -f makefile.vc FINAL=1'
119
120 to make the wxWindows core library without debug information.
1214. Change directory to wx\samples and type 'nmake -f makefile.vc'
122 to make all the samples. You can also make them individually.
123
124Makefile notes:
125
126 Use the 'cleanall' target to clean all objects, libraries and
127 executables.
128
129 To build the release version using makefiles, add FINAL=1 to your
130 nmake invocation, both when building the library and for samples.
131 You MUST use the 'cleanall' target (with FINAL=1 or FINAL=0)
132 before making a different configuration, because otherwise
133 object files used to build the previous configuration may be
134 used accidentally for the current configuation. You might see
135 this manifested in unexpected link errors or warnings. This problem
136 doesn't occur when using project files to build wxWindows.
137
138 Note that the wxWindows core library allows you to have debug
139 and release libraries available simultaneously, by compiling the
140 objects in different subdirectories, whereas samples must be
141 cleaned and re-made to build a different configuration.
142
143To build the DLL version using makefiles:
144
1451. Change directory to wx\src\msw. Type 'nmake -f makefile.vc dll pch'
146 to make both a suitable DLL and import library, and to build a
147 suitable precompiled header file for compiling applications.
148 See the previous section for library names.
1492. Invoke a sample makefile with 'nmake -f makefile.vc WXUSINGDLL=1'
150 (or edit src\makeprog.vc to set WXUSINGDLL to 1 for all
151 applications).
152
153Note (1): if you wish to use templates, please edit
154include\wx\msw\setup.h and set wxUSE_DEBUG_NEW_ALWAYS to 0.
155Without this, the redefinition of 'new' will cause problems in
156the headers. Alternatively, #undef new before including template headers.
157You will also need to set wxUSE_IOSTREAMH to 0 if you will be
158using templates, to avoid the non-template stream files being included
159within wxWindows.
160
161Note (2): libraries and applications generated with makefiles and
162project files are now (hopefully) compatible where static libraries
163are concerned, but please exercise caution nevertheless and if
164possible, use one method or the other.
165
166Note (3): VC++ 5's optimization code seems to be broken and can
167cause both compile and run-time problems: this can be seen when
168deleting an object Dialog Editor, in Release mode with optimizations
169on. If in doubt, switch off optimisations, although this will result in much
170larger executables. It seems possible that the library can be created with
171strong optimization, so long as the application is not strongly
172optimized. For example, in wxWindows project, set to 'Minimum
173Size'. In Dialog Editor project, set to 'Customize: Favor Small
174Code' (and no others). This will then work.
175
176Note (4): some crash problems can be due to inconsistent compiler
177options. If strange/weird/impossible things start to happen please
178check (dumping IDE project file as makefile and doing text comparison
179if necessary) that the project settings, especially the list of defined
180symbols, struct packing, etc. are exactly the same for all items in
181the project. After this, delete everything (including PCH) and recompile.
182
183Note (5): to create your own IDE files, see the technical note on the
184wxWindows web site or CD-ROM, entitled "Compiling wxWindows
185applications in the VC++ IDE" (technical note docs/tech/tn0010.htm in the
186wxWindows distribution). You can also copy .dsp and .dsw
187files from an existing wxWindows sample and adapt them.
188
189Visual C++ 1.5 compilation (16-bit)
190-----------------------------------
191
192NOTE: this has not been tested recently and probably doesn't
193work.
194
1951. Make sure your WXWIN variable is set, and uses the FAT (short
196 name) form.
1972. Change directory to wx\src\msw. Type 'nmake -f makefile.dos' to
198 make the wxWindows core library.
1993. Change directory to a sample, such as wx\samples\minimal, and
200 type 'nmake -f makefile.dos'.
201
202Add FINAL=1 to your makefile invocation to build the release
203versions of the library and samples.
204
205Use the 'clean' target to clean all objects, libraries and
206executables.
207
208Borland C++ 4.5/5.0/5.5 compilation
209-------------------------------
210
211Compiling using the makefiles:
212
2130. If downloading from CVS, copy include\wx\msw\setup0.h to
214 include\wx\setup.h.
2151. Make sure your WXWIN variable is set [e.g add
216 set WXWIN=c:\wxwindows
217 to your autoexec.bat file], and that it uses the FAT (short
218 name) form with no spaces.
219 Make sure your BCCDIR variable is set [e.g add
220 set BCCDIR=c:\progra~1\borland\bcc
221 to your autoexec.bat file], and that it points to the root directory of
222 your Borland C++ installation, and it uses the FAT (short
223 name) form with no spaces.
224 Reboot if needed for the changes to autoexec.bat to take effect.
2252. Change directory to wx\src\msw. Type 'make -f makefile.b32' to
226 make the wxWindows core library. Ignore the warnings about
227 'XXX' not found in library.
2283. Change directory to a sample or demo such as samples\minimal, and type
229 'make -f makefile.b32'.
2304. For release versions, recompile wxWindows and samples using
231 'make -f makefile.b32 clean'
232 'make -f makefile.b32 FINAL=1'
233 for the library and samples.
2345. To make and use wxWindows as a DLL, type
235 'make -f makefile.b32 clean'
236 'make -f makefile.b32 DLL=1'
237 and then for each sample,
238 'make -f makefile.b32 WXUSINGDLL=1'
239 Please note that the samples have not been exhaustively tested
240 with this configuration.
241
242Note (1): the wxWindows library and (some) samples compile in 16-bit mode
243using makefile.bcc, but at present the wxWindows resource system is switched
244off in this mode. See issues.txt for details.
245
246Note (2): unfortunately most samples won't link in 16-bit mode,
247because the automatic data segment exceeds 64K. The minimal
248sample links and runs, however.
249
250Note (3): the wxWindows makefiles assume byte structure alignment. Please
251make sure that your own project or makefile settings use the
252same alignment, or you could experience mysterious crashes. To
253change the alignment, add a suitable option to the $(CFG) target code
254in src/msw/makefile.b32.
255
256Note (4): if you get undefined _SQL... symbols at link time,
257either install odbc32.lib from the BC++ CD-ROM into your BC++ lib
258directory, or set wxUSE_ODBC to 0 in include\wx\msw\setup.h and
259recompile wxWindows. The same applies if compiling using the IDE.
260
261Note (5): BC++ 4.5 (not 5.0) trips up over jdmerge.c in the JPEG folder;
262you will therefore need to set wxUSE_LIBJPEG to 0 in setup.h and remove
263the jpeg target from src\msw\makefile.b32, and remove jpeg from
264src\makeprog.b32.
265
266Note (6): [obsolete]
267
268Note (7): If you wish debug messages to be sent to the console in
269debug mode, edit src\makeb32.env and change /aa to /Tpe in
270LINK_FLAGS.
271
272Compiling using the IDE files: [Borland C++ 5.0, not Cbuilder]
273
2741. Load src\bc32.ide (Release settings)
2752. Go to Options|Project... and specify the correct BC++ include and lib path for
276 your file structure.
2773. Press F9 to compile the wxWindows library.
2784. Load samples\bc32.ide.
2795. Go to Options|Project... and specify the correct BC++ include and lib path for
280 your file structure.
2816. Press F9 to compile the samples (build each node separately if
282 you prefer, by right clicking and choose Build Node).
2837. Run each sample: you may need to run from each sample's directory
284 since some (notably the wxHTML samples) look for files
285 relative to the working directory.
286
287Note (1): the samples project file contains a selection of
288samples, and not all samples. The remaining samples can be made
289with the makefiles. See also the demos hierarchy which doesn't
290have any BC++ project files yet.
291
292Note (2): to make the png, zlib, jpeg and tiff libraries (needed for
293some samples) you need to compile them with bc32.ide.
294
295Note (3): the debug version of the wxWindows library is about 40 MB, and the
296release version is around 5 MB.
297
298See also the file docs/tech/tn0007.txt for further instructions and details
299of how to create your own project files.
300
301** REMEMBER **
302
303In all of your wxWindows applications, your source code should include
304the following preprocessor directive:
305
306#ifdef __BORLANDC__
307#pragma hdrstop
308#endif
309
310(check the samples -- e.g., \wx2\samples\minimal\minimal.cpp -- for
311more details)
312
313Borland C++Builder IDE compilation
314------------------------------
315
3161. Build the wxWindows libraries using the Borland make utility as
317 specified in the section called "Borland C++ 4.5/5.0 compilation"
318 above. (C++ Builder includes a stand-alone C++ compiler. For example,
319 C++ Builder 4.0 comes with C++ 5.4.)
320
3212. You can build samples using the makefiles as per the
322 instructions for BC++ above, or you can follow the instructions
323 in docs/tech/tn0004.htm or http://biolpc22.york.ac.uk/wx/bc/ide.html.
324 You can use the process_sample_bcb.bat command which is in
325 wxwindows\distrib\msw to generate a .mak or .bpr file for most of the
326 samples [mak for Cbuilder 1-3; bpr for v4]. Execute this in the sample
327 directory, passing the name of the cpp files on the command line.
328
329Watcom C++ 10.6/11 compilation
330---------------------------
331
3321. Make sure your WXWIN variable is set, and uses the DOS short
333 name form.
3342. Change directory to wx\src\msw. Type 'wmake -f makefile.wat all' to
335 make the wxWindows core library.
3363. Change directory to wx\samples\minimal and type 'wmake -f makefile.wat all'
337 to make this sample. Repeat for other samples of interest.
338
339Note (1): makewat.env uses the odbc32.lib supplied in wxWindows' lib\watcom
340directory. See the notes in that directory.
341Note (2): if variant.cpp is compiled with date/time class
342options, the linker gives up. So the date/time option is switched
343off for Watcom C++. Also, wxAutomationObject is not compiled with
344Watcom C++.
345Note (3): if Watcom can't read the precompiled header when
346building a sample, try deleting src\msw\watcom.pch and
347compiling the sample again.
348
349Metrowerks CodeWarrior compilation
350----------------------------------
351
3521. Downloaded and unzip wxWindows-x.y.z-cw.zip.
3532. Load the make_cw.mcp project in wx\src, and compile.
3543. Load the make_cw.mcp project in wx\samples\minimal, and compile.
355 Further project files for samples will be available in due
356 course.
357
358Note (1): you need CodeWarrior Pro 4 plus the patches to 4.1 from the
359Metrowerks Web site.
360
361Note (2): unfortunately these files are not yet up-to-date for the
362current release.
363
364Symantec C++ compilation
365------------------------
366
3671. Make sure your WXWIN variable is set, and uses the FAT (short
368 name) form.
3692. Edit setup.h and set wxUSE_DRAG_AND_DROP to 0.
3703. Change directory to wx\src\msw. Type 'make -f makefile.sc' to
371 make the wxWindows core library.
3724. Change directory to wx\samples\minimal and type 'make -f makefile.sc'
373 to make this sample.
374
375Note: the minimal sample doesn't link properly ('Error: no
376start address').
37732-bit compilation only (partially) supported at present, using SC++ 6.1.
378Some functionality is missing using this compiler (see makefile).
379Add -D__WIN95__ if your SC++ has Windows 95 support, and ignore
380Step (2). 16-bit compilation is left as an excercise for the user!
381
382Salford C++ compilation
383-----------------------
384
3851. Make sure your WXWIN variable is set, and uses the FAT (short
386 name) form.
3872. Edit SALFORDDIR and RESOURCEDIR in src/makesl.env as per
388 notes.
3893. Change directory to wx\src\msw. Type 'mk32 -f makefile.sl all' to
390 make the wxWindows core library.
3914. Change directory to wx\samples\minimal and type 'mk32 -f makefile.sl'
392 to make this sample.
393
394Unfortunately, Salford C++ seems to have problems with its code generation for
395operations on objects, as seen in wxFrame::OnMenuHighlight
396(minimal sample) or wxWindow::SetValidator (mdi sample). Also the
397the debugging version of the library is 90MB, with samples coming in
398at 40MB :-) However, wxWindows at least makes a good test suite for
399improving the compiler.
400
401Cygwin/Mingw32 compilation
402----------------------------------
403
404wxWindows 2 supports Cygwin (formerly GnuWin32) betas and
405releases, and Mingw32.
406
407Thanks are due to Keith Garry Boyce (garp@opustel.com), Cygnus
408and others for making it all possible.
409
410Both Cygwin and Mingw32 (the minimal distribution of Cygwin) can be used
411with the same makefiles.
412
413Here are the steps required:
414
415- Retrieve and install the latest beta of Cygwin, or Mingw32, as per the
416 instructions with either of these packages.
417
418- If using Mingw32, you need some extra files to use the wxWindows
419 makefiles. You can find these files in ports/mingw32 on the
420 wxWindows ftp site or CD-ROM, as extra.zip.
421
422 ftp://ftp.remstar.com/pub/wxwin/ports/mingw32/extra.zip
423
424 These should be extracted to the Mingw32 directory. If you have
425 already downloaded rm, cp, mv from elsewhere, you won't need this.
426
427 If using Mingw32 2.95 and below with wxWindows 2.1 or above, you
428 must hand-patch with Mingw32-gcc295.patches (located in the
429 top-level of the wxWindows 2 installation). Mingw32 2.95.2
430 and above contain the fixes already.
431
432- Modify the file wx/src/cygnus.bat (or mingw32.bat or mingegcs.bat)
433 to set up appropriate variables, if necessary mounting drives.
434 Run it before compiling.
435
436- For Cygwin, make sure there's a \tmp directory on your
437 Windows drive or bison will crash (actually you don't need
438 bison for ordinary wxWindows compilation: a pre-generated .c file is
439 supplied).
440
441- Edit wx/src/makeg95.env and set the MINGW32 variable at the top of
442 the file to either 1 (you have Mingw32 or Cygwin 1.x releases) or 0
443 (if you have Cygwin betas). If using Mingw32, also set the
444 MINGW32VERSION variable appropriately.
445
446- Set your WXWIN variable to where wxWindows is installed.
447 *** IMPORTANT: For Cygwin/Mingw32, use forward slashes in the path, not
448 backslashes.
449
450- Use the makefile.g95 files for compiling wxWindows and samples,
451 e.g.:
452 > cd c:\wx\src\msw
453 > make -f makefile.g95
454 > cd c:\wx\samples\minimal
455 > make -f makefile.g95
456
457 Ignore the warning about the default entry point.
458
459- Use the 'strip' command to reduce executable size.
460
461- With Cygwin, you can invoke gdb --nw myfile.exe to
462 debug an executable. If there are memory leaks, they will be
463 flagged when the program quits.
464
465- If using GnuWin32 b18, you will need to copy windres.exe
466 from e.g. the Mingw32 distribution, to a directory in your path.
467
468All targets have 'clean' targets to allow removal of object files
469and other intermediate compiler files.
470
471Notes:
472
4731. See also the Cygwin/Mingw32 on the web site or CD-ROM for
474 further information about using wxWindows with these compilers.
475
4762. libwx.a is 48 MB or more - but much less if compiled with no
477 debug info (-g0) and level 4 optimization (-O4).
478
4793. There's a bug in Mingw32 headers for some early distributions.
480
481 in include/windows32/defines.h, where it says:
482
483 #define LPSTR_TEXTCALLBACKA (LPSTR)-1L)
484
485 it should say:
486
487 #define LPSTR_TEXTCALLBACKA ((LPSTR)-1L)
488
489 (a missing bracket).
490
4914. If there's a problem with the copy or remove commands in
492 src/msw/makefile.g95, you may need to change the COPY and
493 RM variables in makeg95.env.
494
4955. If there's a problem executing the windres program, try
496 commenting out RCPREPROCESSOR in makeg95.env.
497
4986. OpenGL support should work with Mingw32 as-is. However,
499 if you wish to generate import libraries appropriate either for
500 the MS OpenGL libraries or the SGI OpenGL libraries, go to
501 include/wx/msw/gl and use:
502
503 dlltool -k -d opengl.def -llibopengl.a
504
505 for the SGI DLLs, or
506
507 dlltool -k -d opengl32.def -llibopengl32.a
508
509 and similarly for glu[32].def.
510
511References:
512
513 - The Cygwin site is at
514 http://sourceware.cygnus.com
515 - Mingw32 is available at:
516 ftp://www.mingw.org
517
518TWIN32 and gcc on Linux
519-----------------------
520
521The wxWindows 2 for Windows port may be compiled using
522the TWIN32 emulator package from www.willows.com. However,
523TWIN32 is by no means finished so this should be taken as
524something to think about for the future, rather than
525a tool for writing products with.
526
527Use makefile.twn in much the same way as makefile.g95, as
528described above. Not all sample makefiles are supplied yet.
529
530For some reason, I found I had to copy TWIN32's Windows resource
531compiler (rc) to the current working directory for it to be found.
532
533General Notes
534-------------
535
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
540 under Packages.
541
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. Also, read
546 the BuildCVS.txt for other hints.
547