]> git.saurik.com Git - wxWidgets.git/blob - docs/msw/install.txt
add Create to wxDocParentFrame
[wxWidgets.git] / docs / msw / install.txt
1 Installing wxWidgets 2.7.0
2 -----------------------------------------------------------
3
4 This is wxWidgets 2.7.0 for Microsoft Windows 9x/ME, Windows NT,
5 Windows 2000, Windows XP and Windows CE.
6
7 These installation notes can be found in docs/msw/install.txt
8 in your wxWidgets distribution.
9
10 IMPORTANT NOTE: If you experience problems installing, please
11 re-read this instructions and other related files (changes.txt,
12 readme.txt, FAQ) carefully before mailing wx-users. Preferably,
13 try to fix the problem first and then upload a patch to
14 SourceForge:
15
16 http://sourceforge.net/patch/?group_id=9863
17
18 Please report bugs using the SourceForge bug tracker:
19
20 http://sourceforge.net/bugs/?group_id=9863
21
22 Unarchiving
23 ============================================================
24
25 A setup program is provided (setup.exe) to automatically copy
26 files to a directory on your hard disk. Do not install into a
27 path that contains spaces.
28
29 The setup program contains the following:
30
31 - All common, generic and MSW-specific wxWidgets source;
32 - samples and demos;
33 - documentation in MS HTML Help format;
34 - makefiles for most Windows compilers, plus CodeWarrior,
35 BC++ and VC++ IDE files;
36 - JPEG library source;
37 - TIFF library source;
38 - Object Graphics Library, Tex2RTF, wxSTC, etc.
39
40 Alternatively, you may unarchive the .zip form by hand:
41 wxMSW-x.y.z.zip where x.y.z is the version number.
42
43 Unarchive the required files plus any optional documentation
44 files into a suitable directory such as c:\wx.
45
46 General installation notes
47 ==========================
48
49 If installing from the CVS server, copy include/wx/msw/setup0.h to
50 include/wx/msw/setup.h and edit the resulting file to choose
51 the features you would like to compile wxWidgets with[out].
52
53 Compilation
54 ===========
55
56 The following sections explain how to compile wxWidgets with each supported
57 compiler. Search for one of Microsoft/Borland/Watcom/Symantec/Metrowerks/
58 Cygwin/Mingw32 to quickly locate the instructions for your compiler.
59
60 All makefiles and project are located in build\msw directory.
61
62 Where compiled files are stored
63 -------------------------------
64
65 After successful compilation you'll find the libraries in a subdirectory
66 of lib directory named after the compiler and DLL/static settings.
67 A couple of examples:
68
69 lib\vc_lib VC++ compiled static libraries
70 lib\vc_dll VC++ DLLs
71 lib\bcc_lib Static libraries for Borland C++
72 lib\wat_dll Watcom C++ DLLs
73
74 Names of compiled wxWidgets libraries follow this scheme: libraries that don't
75 depend on GUI components begin with "wxbase" followed by version number and
76 letters indicating if the library is compiled as Unicode ('u') and/or debug
77 build ('d'). Last component of them name is name of wxWidgets component
78 (unless you built the library as single monolithic library; look for
79 "Configuring the build" below). This is a typical set of release ANSI build
80 libraries (release versions on left, debug on right side):
81
82 wxbase25.lib wxbase25d.lib
83 wxbase25_net.lib wxbase25d_net.lib
84 wxbase25_xml.lib wxbase25d_xml.lib
85 wxmsw25_core.lib wxmsw25d_core.lib
86 wxmsw25_html.lib wxmsw25d_html.lib
87 wxmsw25_adv.lib wxmsw25d_adv.lib
88
89 Their Unicode debug counterparts in wxUniversal build would be
90
91 wxbase25ud.lib
92 wxbase25ud_net.lib
93 wxbase25ud_xml.lib (notice these libs are same for wxUniv and wxMSW)
94 wxmswuniv25ud_core.lib
95 wxmswuniv25ud_html.lib
96 wxmswuniv25ud_adv.lib
97
98 These directories also contain subdirectory with wx/setup.h header. This
99 subdirectory is named after port, Unicode, wxUniv and debug settings and
100 you must add it to include paths when compiling your application. Some
101 examples:
102
103 lib\vc_lib\msw\wx\setup.h VC++ static, wxMSW
104 lib\vc_lib\mswud\wx\setup.h VC++ static, wxMSW, Unicode, debug
105 lib\vc_lib\mswunivd\wx\setup.h VC++ static, wxUniversal, debug
106
107 Below are compiler specific notes followed by customizing instructions that
108 apply to all compilers (search for "Configuring the build").
109
110 Microsoft Visual C++ compilation
111 ----------------------------------------------------------------
112
113 You may wish to visit http://wiki.wxwindows.org/wiki.pl?MSVC for a more
114 informal and more detailed description of the process summarized below.
115
116 Please note that the VC++ 6.0 project files will work for VC++ .NET also.
117
118 VC++ 5.0 can also be used, providing Service Pack 3 is applied. Without it
119 you will have trouble with internal compiler errors. It is available for
120 download at: ftp://ftp.microsoft.com/developr/visualstudio/sp3/full.
121
122 Using project files (VC++ 6 and later):
123
124 1. Unarchive wxWidgets-x.y.z-vc.zip, the VC++ 6 project
125 makefiles (already included in wxMSW-x.y.z.zip and the setup version).
126 2. Open build\msw\wx.dsw, which has configurations for static
127 compilation or DLL compilation, and each of these available in
128 Unicode/ANSI, Debug/Release and wxUniversal or native variations.
129 Normally you'll use a static linking ANSI configuration.
130 Choose the Win32 Debug or Win32 Release configuration (or any other that
131 suits your needs) and use Batch Build to compile _all_ projects. If you
132 know you won't need some of the libraries (i.e. html part), you don't have
133 to compile it. It will also produce similar variations on jpeg.lib,
134 png.lib, tiff.lib, zlib.lib, and regex.lib.
135 If you want to build DLLs, you have to either build them one by one in
136 proper order (jpeg, png, tiff, zlib, regex, expat, base, core, the rest
137 in any order) or to use wx_dll.dsw workspace which has correct dependencies.
138 3. Open a sample project file, choose a configuration such as
139 Win32 Debug using Build | Set Active Configuration..., and compile.
140 The project files don't use precompiled headers, to save disk
141 space, but you can switch PCH compiling on for greater speed.
142 NOTE: you may also use samples/samples.dsw to access all
143 sample projects without opening each workspace individually.
144 You can use the Batch Build facility to make several samples
145 at a time.
146
147 Using makefiles:
148
149 1. Change directory to build\msw. Type:
150
151 'nmake -f makefile.vc'
152
153 to make the wxWidgets core library as release DLL.
154 See "Configuring the build" for instruction how to build debug or static
155 libraries.
156
157 2. Change directory to samples and type 'nmake -f makefile.vc'
158 to make all the samples. You can also make them individually.
159
160 Makefile notes:
161
162 Use the 'clean' target to clean all objects, libraries and
163 executables.
164
165 Note (1): if you wish to use templates, please edit
166 include\wx\msw\setup.h and set wxUSE_DEBUG_NEW_ALWAYS to 0.
167 Without this, the redefinition of 'new' will cause problems in
168 the headers. Alternatively, #undef new before including template headers.
169 You will also need to set wxUSE_IOSTREAMH to 0 if you will be
170 using templates, to avoid the non-template stream files being included
171 within wxWidgets.
172
173 Note (2): libraries and applications generated with makefiles and
174 project files are now (hopefully) compatible where static libraries
175 are concerned, but please exercise caution nevertheless and if
176 possible, use one method or the other.
177
178 Note (3): some crash problems can be due to inconsistent compiler
179 options. If strange/weird/impossible things start to happen please
180 check (dumping IDE project file as makefile and doing text comparison
181 if necessary) that the project settings, especially the list of defined
182 symbols, struct packing, etc. are exactly the same for all items in
183 the project. After this, delete everything (including PCH) and recompile.
184
185 Note (4): to create your own IDE files, copy .dsp and .dsw
186 files from an existing wxWidgets sample and adapt them, or
187 visit http://wiki.wxwindows.org/wiki.pl?MSVC.
188
189 Microsoft Visual C++ compilation for 64-bit Windows
190 ----------------------------------------------------------------
191
192 Visual Studio 2005 includes 64-bit compilers, though they are not installed by
193 default; you need to select them during the installation. Both native 64-bit
194 compilers and 32-bit hosted cross compilers are included, so you do not need a
195 64-bit machine to use them (though you do to run the created executables).
196 Visual C++ Express Edition does not include 64-bit compilers.
197
198 64-bit compilers are also available in various SDKs, for example
199 the .NET Framework SDK:
200 http://msdn.microsoft.com/netframework/programming/64bit/devtools/
201
202 Using project files:
203
204 1. Open the VC++ 6 workspace file: build\msw\wx.dsw. Visual Studio will then
205 convert the projects to the current Visual C++ project format.
206
207 2. To add 64-bit targets, go to the 'Build' menu and choose 'Configuration
208 Manager...'. In the 'Active solution platform' drop down choose '<new>',
209 then you can choose either 'Itanium' or 'x64'.
210
211 For more detailed instructions see:
212 http://msdn2.microsoft.com/en-us/library/9yb4317s(en-us,vs.80).aspx
213
214 Note: 64-bit targets created this way will use the build directory of the
215 corresponding 32-bit target for some files. Therefore after building
216 for one CPU it is necessary to clean the build before building the
217 equivalent target for another CPU. We've reported the problem to MS
218 but they say it is not possible to fix it.
219
220 3. To build, go to the 'Build' menu and choose 'Batch Build...'. Tick all the
221 all the 'x64|Debug' or all the 'Itanium|Debug' projects, and click 'Build'.
222
223 This will build a debug version of the static libs. The section above on
224 Visual C++ in general has more information about adjusting the settings to
225 build other configurations.
226
227 4. To compile one of the samples open one of the sample projects, such as
228 samples\minimal\minimal.dsw. Visual Studio will convert the project as in
229 step 1, then add a 64-bit target as in step 2, and build.
230
231 Using makefiles:
232
233 1. Open a 64-bit build command prompt, for either x64 or Itanium. Change
234 directory to build\msw. Then for x64 type:
235
236 nmake -f makefile.vc TARGET_CPU=AMD64
237
238 or for Itanium:
239
240 nmake -f makefile.vc TARGET_CPU=IA64
241
242 This will build a debug version of wxWidgets DLLs. See "Configuring the
243 build" for instruction how to build other configurations such as a release
244 build or static libraries.
245
246 2. Change to the directory of one of the samples such as samples\minimal. Type
247 the same command used to build the main library, for example for x64:
248
249 nmake -f makefile.vc TARGET_CPU=AMD64
250
251 Notes:
252
253 The versions of the VC++ 8 compiler included with some SDKs requires an
254 additional library to be linked or the following error is received.
255
256 LNK2001 unresolved external symbol __security_check_cookie
257
258 If you receive this error add bufferoverflowu.lib to link, e.g.:
259
260 nmake -f makefile.vc TARGET_CPU=AMD64 LDFLAGS=bufferoverflowu.lib
261
262 See http://support.microsoft.com/?id=894573 for more information.
263
264 Borland C++ compilation
265 ----------------------------------------------------------------
266
267 The minimum version required is 5.5, which can be downloaded for free from:
268 http://www.borland.com/products/downloads/download_cbuilder.html#
269
270 Compiling using the makefiles:
271
272 1. Change directory to build\msw. Type 'make -f makefile.bcc' to
273 make the wxWidgets core library. Ignore the compiler warnings.
274 This produces a couple of libraries in the lib\bcc_lib directory.
275
276 2. Change directory to a sample or demo such as samples\minimal, and type
277 'make -f makefile.bcc'. This produces a windows exe file - by default
278 in the bcc_mswd subdirectory.
279
280 Note (1): the wxWidgets makefiles assume dword structure alignment. Please
281 make sure that your own project or makefile settings use the
282 same alignment, or you could experience mysterious crashes. To
283 change the alignment, change CPPFLAGS in build\msw\config.bcc.
284
285 Note (2): if you get undefined _SQL... symbols at link time,
286 either install odbc32.lib from the BC++ CD-ROM into your BC++ lib
287 directory, or set wxUSE_ODBC to 0 in include\wx\msw\setup.h and
288 recompile wxWidgets. The same applies if compiling using the IDE.
289
290 Note (3): If you wish debug messages to be sent to the console in
291 debug mode, edit makefile.bcc and change /aa to /Tpe in link commands.
292
293 Cmpilation succeeds with CBuilderX personal edition and CBuilder6, but
294 you may have to copy make.exe from the 5.5 download to the new bin directory.
295 Compiling using the IDE files for Borland C++ 5.0 and using CBuilder IDE
296 (v1-v6): not supported
297
298
299 ** REMEMBER **
300
301 In all of your wxWidgets applications, your source code should include
302 the following preprocessor directive:
303
304 #ifdef __BORLANDC__
305 #pragma hdrstop
306 #endif
307
308 (check the samples -- e.g., \wx2\samples\minimal\minimal.cpp -- for
309 more details)
310
311 Borland 16 Bit compilation for Windows 3.1
312 ----------------------------------------------------------------
313
314 The last version of wxWidgets to support 16-bit compilation with Borland was
315 2.2.7 - Please download and read the instructions in that release
316
317 Watcom C++ 10.6/11 and OpenWatcom compilation
318 ----------------------------------------------------------------
319
320 1. Change directory to build\msw. Type 'wmake -f makefile.wat' to
321 make the wxWidgets core library.
322
323 2. Change directory to samples\minimal and type 'wmake -f makefile.wat'
324 to make this sample. Repeat for other samples of interest.
325
326 Note (1): if your installation of Watcom doesn't have odbc32.lib file and
327 you need it (i.e. you have wxUSE_ODBC=1), you can use the file
328 from lib\watcom directory. See the notes in that directory.
329
330 Note (2): if variant.cpp is compiled with date/time class options, the linker
331 gives up. So the date/time option is switched off for Watcom C++.
332 Also, wxAutomationObject is not compiled with Watcom C++ 10.
333
334 Note (3): RawBitmaps won't work at present because they use unsupported template
335 classes
336
337 Note (4): if Watcom can't read the precompiled header when building a sample,
338 try deleting .pch files in build\msw\wat_* and compiling
339 the sample again.
340
341 Metrowerks CodeWarrior compilation
342 ----------------------------------------------------------------
343
344 1. CodeWarrior Pro 7 project files in XML format are already
345 included in wxMSW-2.7.0.zip and the setup version.
346
347 2. Review the file include\wx\msw\setup.h (or include\wx\msw\setup0.h if
348 you are working from the CVS version) to make sure the settings reflect
349 what you want. If you aren't sure, leave it alone and go with the
350 default settings. A few notes:
351 - Don't use wxUSE_DEBUG_NEW_ALWAYS: it doesn't mix well with MSL
352 - wxUSE_GLOBAL_MEMORY_OPERATORS works, but memory leak reports
353 will be rather confusing due to interactions with the MSL ANSI
354 and runtime libs.
355
356 3. The project file to build the Win32 wxWidgets libraries relies on the
357 Batch File Runner plug-in. This plug-in is not installed as part of
358 a normal CW7 installation. However, you can find this plug-in on the
359 CodeWarrior Reference CD, in the Thrill Seekers folder; it's call the
360 "Batch File Post Linker".
361
362 4. If you choose not to install the Batch File Runner plug-in, then you
363 need to do the following by hand:
364 (1) Create the directories lib\cw7msw\include\wx and copy the file
365 include\wx\msw\setup.h (or include\wx\msw\setup0.h if you are
366 working from the CVS version) to lib\cw7msw\include\wx\setup.h
367 (2) Create the directories lib\cw7mswd\include\wx and copy the file
368 include\wx\msw\setup.h (or include\wx\msw\setup0.h if you are
369 working from the CVS version) to lib\cw7mswd\include\wx\setup.h
370
371 5. Import src\wxWidgetsW7.xml to create the project file wxWidgetsW7.mcp.
372 Store this project file in directory src. You may get warnings about
373 not being able to find certain project paths; ignore these warnings, the
374 appropriate paths will be created during the build by the Batch File Runner.
375
376 6. Choose the wxlib Win32 debug or wxlib Win32 Release target and build. You
377 will get some warnings about hidden virtual functions, illegal conversions
378 from const pointers to pointers, etc., all of which you can safely ignore.
379 ***Note: if you get errors that the compiler can't find "wx/setup.h", just
380 stop the build and build again. These errors occur because sometimes the
381 compiler starts doing its thing before the copying of setup.h has completed.
382
383 7. The following libraries will be produced depending on chosen
384 target:
385 - wx_x86.lib ANSI Release (static)
386 - wx_x86_d.lib ANSI Debug (static)
387
388 8. Sorry, I haven't had time yet to create and test unicode or DLL versions.
389 Volunteers for this are welcome (as neither DLLs nor unicode builds are
390 big priorities for me ;).
391
392 9. CodeWarrior Pro7 project files (in XML format) are also provided for some
393 of the samples. In particular, there are project files for the minimal,
394 controls, dialogs, dnd, nd docview samples. You can use these project
395 files as templates for the other samples and for your own projects.
396 - For example, to make a project file for the "grid" sample,
397 just copy the project file for the "minimal" sample, minimalW7.mcp
398 (made by importing minimalW7.xml into CodeWarrior), into the
399 sample/grid directory, calling it gridW7.mcp. Open
400 newgridW7.mcp and revise the project by deleting the files
401 minimal.rc and minimal.cpp and adding the files griddemo.rc and
402 griddemo.cpp. Build and run....
403
404
405 Cygwin/MinGW compilation
406 ----------------------------------------------------------------
407
408 wxWidgets supports Cygwin (formerly GnuWin32) betas and
409 releases, and MinGW. Cygwin can be downloaded from:
410
411 http://sources.redhat.com/cygwin/
412
413 and MinGW from:
414
415 http://www.mingw.org/
416
417 Both Cygwin and MinGW can be used with configure (assuming you have MSYS
418 installed in case of MinGW). You will need new enough MinGW version, preferably
419 MinGW 2.0 (ships with gcc3) or at least 1.0 (gcc-2.95.3). GCC versions older
420 than 2.95.3 don't work; you can use wxWidgets 2.4 with them.
421
422 NOTE: some notes specific to old Cygwin (< 1.1.x) are at the end of this
423 section (see OLD VERSIONS)
424
425 There are two methods of compiling wxWidgets, by using the
426 makefiles provided or by using 'configure'.
427
428 Retrieve and install the latest version of Cygwin, or MinGW, as per
429 the instructions with either of these packages.
430
431 If using MinGW, you can download the add-on MSYS package to
432 provide Unix-like tools that you'll need to build wxWidgets using configure.
433
434 Using makefiles directly
435 ----------------------------------------------------------------
436
437 NOTE: The makefile.gcc makefiles are for compilation under MinGW using
438 native make and Windows command interpreter (command.com/cmd.exe), they
439 won't work in other environments (such as UNIX or Unix-like, e.g. MSYS;
440 you have to use configure instead)
441
442 Here are the steps required using the provided makefiles:
443
444 - If you are using gcc-2.95, edit build\msw\config.gcc and set the GCC_VERSION
445 variable to "2.95".
446
447 - Use the makefile.gcc files for compiling wxWidgets and samples,
448 e.g. to compile a debugging version of wxWidgets:
449 > cd c:\wx\build\msw
450 > make -f makefile.gcc BUILD=debug
451 > cd c:\wx\samples\minimal
452 > make -f makefile.gcc BUILD=debug
453 (See below for more options.)
454
455 Ignore the warning about the default entry point.
456
457 - Use the 'strip' command to reduce executable/dll size (note that
458 stripping an executable/dll will remove debug information!).
459
460 All targets have 'clean' targets to allow removal of object files
461 and other intermediate compiler files.
462
463 Using configure
464 ----------------------------------------------------------------
465
466 Instead of using the makefiles, you can use the configure
467 system to generate appropriate makefiles, as used on Unix
468 and Mac OS X systems.
469
470 Change directory to the root of the wxWidgets distribution,
471 make a build directory, and run configure and make in this directory.
472
473 For example:
474
475 cd $WXWIN
476 mkdir build-debug
477 cd build-debug
478 ../configure --with-msw --enable-debug --enable-debug_gdb --disable-shared
479 make
480 make install % This step is optional, see note (6) below.
481 cd samples/minimal
482 make
483 ./minimal.exe
484
485 Notes:
486
487 1. See also the Cygwin/MinGW on the web site or CD-ROM for
488 further information about using wxWidgets with these compilers.
489
490 2. libwx.a is 100 MB or more - but much less if compiled with no
491 debug info (-g0) and level 4 optimization (-O4).
492
493 3. If you get a link error under MinGW 2.95.2 referring to:
494
495 EnumDAdvise__11IDataObjectPP13IEnumSTATDATA@8
496
497 then you need to edit the file objidl.h at line 663 and add
498 a missing PURE keyword:
499
500 STDMETHOD(EnumDAdvise)(THIS_ IEnumSTATDATA**) PURE;
501
502 4. There's a bug in MinGW headers for some early distributions.
503
504 in include/windows32/defines.h, where it says:
505
506 #define LPSTR_TEXTCALLBACKA (LPSTR)-1L)
507
508 it should say:
509
510 #define LPSTR_TEXTCALLBACKA ((LPSTR)-1L)
511
512 (a missing bracket).
513
514 5. OpenGL support should work with MinGW as-is. However,
515 if you wish to generate import libraries appropriate either for
516 the MS OpenGL libraries or the SGI OpenGL libraries, go to
517 include/wx/msw/gl and use:
518
519 dlltool -k -d opengl.def -llibopengl.a
520
521 for the SGI DLLs, or
522
523 dlltool -k -d opengl32.def -llibopengl32.a
524
525 and similarly for glu[32].def.
526
527 6. The 'make install' step is optional, and copies files
528 as follows:
529
530 /usr/local/lib - wxmswXYZd.dll.a and wxmswXYZd.dll
531 /usr/local/include/wx - wxWidgets header files
532 /usr/local/bin - wx-config
533
534 You may need to do this if using wx-config with the
535 default root path.
536
537 7. With Cygwin, you can invoke gdb --nw myfile.exe to
538 debug an executable. If there are memory leaks, they will be
539 flagged when the program quits. You can use Cygwin gdb
540 to debug MinGW executables.
541
542 8. Note that gcc's precompiled headers do not work on current versions of
543 Cygwin. If your version of Cygwin is affected you will need to use the
544 --disable-precomp-headers configure option.
545
546 OLD VERSIONS:
547
548 - Modify the file wx/src/cygnus.bat (or mingw32.bat or mingegcs.bat)
549 to set up appropriate variables, if necessary mounting drives.
550 Run it before compiling.
551
552 - For Cygwin, make sure there's a \tmp directory on your
553 Windows drive or bison will crash (actually you don't need
554 bison for ordinary wxWidgets compilation: a pre-generated .c file is
555 supplied).
556
557 - If using GnuWin32 b18, you will need to copy windres.exe
558 from e.g. the MinGW distribution, to a directory in your path.
559
560
561 Symantec & DigitalMars C++ compilation
562 ----------------------------------------------------------------
563
564 The DigitalMars compiler is a free succssor to the Symantec compiler
565 and can be downloaded from http://www.digitalmars.com/
566
567 1. You need to download and unzip in turn (later packages will overwrite
568 older files)
569 Digital Mars C/C++ Compiler Version 8.40 or later
570 Basic utilities
571 from http://www.digitalmars.com/download/freecompiler.html
572
573 2. Change directory to build\msw and type 'make -f makefile.dmc' to
574 make the wxWidgets core library.
575
576 3. Change directory to samples\minimal and type 'make -f makefile.dmc'
577 to make this sample. Most of the other samples also work.
578
579
580 Note that if you don't have the files makefile.dmc you may create them yourself
581 using bakefile tool according to the instructions in build\bakefiles\README:
582
583 cd build\bakefiles
584 bakefile_gen -f dmars -b wx.bkl
585 bakefile_gen -f dmars -b ../../samples/minimal/minimal.bkl
586
587
588 16-bit compilation is no longer supported.
589
590 Configuring the build
591 ================================================================
592
593 So far the instructions only explained how to build release DLLs of wxWidgets
594 and did not cover any configuration. It is possible to change many aspects of
595 the build, including debug/release and ANSI/Unicode settings. All makefiles in
596 build\msw directory use same options (with a few exceptions documented below)
597 and the only difference between them is in object files and library directory
598 names and in make invocation command.
599
600 Changing the settings
601 ----------------------------------------------------------------
602
603 There are two ways to modify the settings: either by passing the values as
604 arguments when invoking make or by editing build\msw\config.$(compiler) file
605 where $(compiler) is same extension as the makefile you use has (see below).
606 The latter is good for setting options that never change in your development
607 process (e.g. GCC_VERSION or VENDOR). If you want to build several versions of
608 wxWidgets and use them side by side, the former method is better. Settings in
609 config.* files are shared by all makefiles (samples, contrib, main library),
610 but if you pass the options as arguments, you must use same arguments you used
611 for the library when building samples or contrib libraries!
612
613 Examples of invoking make in Unicode debug build (other options described
614 below are set analogically):
615
616 Visual C++:
617 > nmake -f makefile.vc BUILD=debug UNICODE=1
618
619 Borland C++:
620 > make -f makefile.bcc -DBUILD=debug -DUNICODE=1
621 (Note that you have to use -D to set the variable, unlike in other make
622 tools!)
623
624 Watcom C/C++:
625 > wmake -f makefile.wat BUILD=debug UNICODE=1
626
627 MinGW using native makefiles:
628 > mingw32-make -f makefile.gcc BUILD=debug UNICODE=1
629
630 MinGW using configure:
631 > ./configure --enable-debug --enable-unicode
632 (see ./configure --help on details; configure is not covered in this
633 section)
634
635 Cygwin using configure:
636 > ./configure --disable-precomp-headers --enable-debug --enable-unicode
637 (use --disable-precomp-headers if Cygwin doesn't support precompiled
638 headers)
639
640 Brief explanation of options and possible values is in every
641 build\msw\config.* file; more detailed description follows.
642
643 Basic options
644 ----------------------------------------------------------------
645
646 BUILD=release
647 Builds release version of the library. It differs from default 'debug'
648 in lack of appended 'd' in name of library, does not define __WXDEBUG__
649 and not include debug information compiled into object files and the
650 executable.
651
652 SHARED=1
653 Build shared libraries (DLLs). By default, DLLs are not built
654 (SHARED=0).
655
656 UNICODE=1
657 To build Unicode versions of the libraries, add UNICODE=1 to make invocation
658 (default is UNICODE=0). If you want to be able to use Unicode version on
659 Windows9x, you will need to set MSLU=1 as well.
660
661 This option affect name of the library ('u' is appended) and the directory
662 where the library and setup.h are store (ditto).
663
664 WXUNIV=1
665 Build wxUniversal instead of native wxMSW (see
666 http://www.wxwidgets.org/wxuniv.htm for more information).
667
668 Advanced options
669 ----------------------------------------------------------------
670
671 MONOLITHIC=1
672 Starting with version 2.5.1, wxWidgets has the ability to be built as
673 several smaller libraries instead of single big one as used to be the case
674 in 2.4 and older versions. This is called "multilib build" and is the
675 default behaviour of makefiles. You can still build single library
676 ("monolithic build") by setting MONOLITHIC variable to 1.
677
678 USE_GUI=0
679 Disable building GUI parts of the library, build only wxBase components used
680 by console applications. Note that if you leave USE_GUI=1 then both wxBase
681 and GUI libraries are built. If you are building monolithic library, then
682 you should set wxUSE_GUI to 1 in setup.h.
683
684 USE_OPENGL=1
685 Build wxmsw25_gl.lib library with OpenGL integration class wxGLCanvas.
686 You must also modify your setup.h to #define wxUSE_GLCANVAS 1. Note that
687 OpenGL library is always built as additional library, even in monolithic
688 build!
689
690 USE_ODBC=1
691 Build two additional libraries in multilib mode, one with database
692 classes and one with wxGrid database support. You must
693 #define wxUSE_ODBC 1 in setup.h
694
695 USE_HTML=0
696 Do not build wxHTML library. If MONOLITHIC=1, then you must also
697 #define wxUSE_HTML 1 in setup.h.
698
699 USE_XRC=0
700 Do not build XRC resources library. If MONOLITHIC=1, then you must also
701 #define wxUSE_HTML 1 in setup.h.
702
703 RUNTIME_LIBS=static
704 Links static version of C and C++ runtime libraries into the executable, so
705 that the program does not depend on DLLs provided with the compiler (e.g.
706 Visual C++'s msvcrt.dll or Borland's cc3250mt.dll).
707 Caution: Do not use static runtime libraries when building DLL (SHARED=1)!
708
709 MSLU=1
710 Enables MSLU (Microsoft Layer for Unicode). This setting makes sense only if
711 used together with UNICODE=1. If you want to be able to use Unicode version
712 on Windows9x, you will need MSLU (Microsoft Layer for Unicode) runtime DLL
713 and import lib. The former can be downloaded from Microsoft, the latter is
714 part of the latest Platform SDK from Microsoft (see msdn.microsoft.com for
715 details). An alternative implementation of import library can be downloaded
716 from http://libunicows.sourceforge.net - unlike the official one, this one
717 works with other compilers and does not require 300+ MB Platform SDK update.
718
719 DEBUG_FLAG=0
720 DEBUG_FLAG=1
721 If set to 1, define __WXDEBUG__ symbol, append 'd' to library name and do
722 sanity checks at runtime. If set to 0, don't do it. By default, this is
723 governed by BUILD option (if 'debug', DEBUG_FLAG=1, if 'release' it is 0),
724 but it is sometimes desirable to modify default behaviour and e.g. define
725 __WXDEBUG__ even in release builds.
726
727 DEBUG_INFO=0
728 DEBUG_INFO=1
729 Same as DEBUG_FLAG in behaviour, this option affects whether debugging
730 information is included in the executable or not.
731
732 VENDOR=<your company name>
733 Set this to a short string identifying your company if you are planning to
734 distribute wxWidgets DLLs with your application. Default value is 'custom'.
735 This string is included as part of DLL name. wxWidgets DLLs contain compiler
736 name, version information and vendor name in them. For example
737 wxmsw250_core_bcc_custom.dll is one of DLLs build using Borland C++ with
738 default settings. If you set VENDOR=mycorp, the name will change to
739 wxmsw250_core_bcc_mycorp.dll.
740
741 CFG=<configuration name>
742 Sets configuration name so that you can have multiple wxWidgets builds with
743 different setup.h settings coexisting in same tree. See "Object and library
744 directories" below for more information.
745
746 Compiler specific options
747 ----------------------------------------------------------------
748
749 * MinGW
750
751 If you are using gcc-2.95 instead of gcc3, you must set GCC_VERSION to
752 2.95. In build\msw\config.gcc, change
753 > GCC_VERSION = 3
754 to
755 > GCC_VERSION = 2.95
756
757 * Visual C++
758
759 DEBUG_RUNTIME_LIBS=0
760 DEBUG_RUNTIME_LIBS=1
761 If set to 1, msvcrtd.dll is used, if to 0, msvcrt.dll is used. By default
762 msvcrtd.dll is used only if the executable contains debug info and
763 msvcrt.dll if it doesn't. It is sometimes desirable to build with debug info
764 and still link against msvcrt.dll (e.g. when you want to ship the app to
765 customers and still have usable .pdb files with debug information) and this
766 setting makes it possible.
767
768 Fine-tuning the compiler
769 ----------------------------------------------------------------
770
771 All makefiles have variables that you can use to specify additional options
772 passed to the compiler or linker. You won't need this in most cases, but if you
773 do, simply add desired flags to CFLAGS (for C compiler), CXXFLAGS (for C++
774 compiler), CPPFLAGS (for both C and C++ compiler) and LDFLAGS (the linker).
775
776 Object and library directories
777 ----------------------------------------------------------------
778
779 All object files produced during library build are stored in a directory under
780 build\msw. It's name is derived from build settings and CFG variable and from
781 compiler name. Examples of directory names:
782
783 build\msw\bcc_msw SHARED=0
784 build\msw\bcc_mswdll SHARED=1
785 build\msw\bcc_mswunivd SHARED=0, WXUNIV=1, BUILD=debug
786 build\msw\vc_mswunivd ditto, with Visual C++
787
788 Libraries and DLLs are copied into subdirectory of lib directory with
789 name derived from compiler and static/DLL setting and setup.h into directory
790 with name that contains other settings:
791
792 lib\bcc_msw
793 lib\bcc_lib\msw\wx\setup.h
794 lib\bcc_dll
795 lib\bcc_dll\msw\wx\setup.h
796 lib\bcc_lib
797 lib\bcc_lib\mswunivd\wx\setup.h
798 lib\vc_lib
799 lib\vc_lib\mswunivd\wx\setup.h
800
801 Each lib\ subdirectory has wx subdirectory with setup.h as seen above.
802 This file is copied there from include\wx\msw\setup.h (and if it doesn't exist,
803 from include\wx\msw\setup0.h) and this is the copy of setup.h that is used by
804 all samples and should be used by your apps as well. If you are doing changes
805 to setup.h, you should do them in this file, _not_ in include\wx\msw\setup.h.
806
807 If you set CFG to something, the value is appended to directory names. E.g.
808 for CFG=MyBuild, you'll have object files in
809
810 build\msw\bcc_mswMyBuild
811 build\msw\bcc_mswdllMyBuild
812 etc.
813
814 and libraries in
815
816 lib\bcc_libMyBuild
817 lib\bcc_dllMyBuild
818 etc.
819
820 By now it is clear what CFG is for: builds with different CFG settings don't
821 share any files and they use different setup.h files. This allows you to e.g.
822 have two static debug builds, one with wxUSE_SOCKETS=0 and one with sockets
823 enabled (without CFG, both of them would be put into same directory and there
824 would be conflicts between the files).
825
826 General Notes
827 =================================================================
828
829 - Debugging: under Windows 95, debugging output isn't output in
830 the same way that it is under NT or Windows 3.1.
831 Please see DebugView available from http://www.sysinternals.com.
832