1 Installing wxWidgets for Windows
2 -----------------------------------------------------------
4 This is wxWidgets for Microsoft Windows 9x/ME, Windows NT
5 and later (2000, XP, Vista, 7, etc) and Windows CE.
7 These installation notes can be found in docs/msw/install.txt
8 in your wxWidgets distribution.
10 IMPORTANT NOTE: If you experience problems installing, please
11 re-read these instructions and other related files (changes.txt,
12 readme.txt, FAQ) carefully before posting to wx-users list.
14 If you are sure that you found a bug, please report it at
17 http://trac.wxwidgets.org/newticket
19 Please notice that often trying to correct the bug yourself is the
20 quickest way to fix it. Even if you fail to do it, you may
21 discover valuable information allowing us to fix it while doing
22 it. We also give much higher priority to bug reports with patches
23 fixing the problems so this ensures that your report will be
30 Please simply uncompress the .zip file manually into any directory.
31 However we advise avoiding using directories with spaces in their
32 names (notably "C:\Program Files") as this risks creating problems
33 with makefiles and other command-line tools.
39 In the majority of cases, you don't need to change the default
40 library build configuration. If you wish to change some of the build
41 options you need to edit the include/wx/msw/setup.h file enabling or
42 disabling the features you would like to compile wxWidgets with[out].
44 NB: If you checked your sources from version control repository and
45 didn't obtain them from a release file, the file above doesn't
46 exist and you will need to copy include/wx/msw/setup0.h to
47 include/wx/msw/setup.h.
49 Notice that this file is later copied into a directory under lib for
50 each of the build configurations which allows to have different
51 build options for different configurations too.
57 The following sections explain how to compile wxWidgets with each supported
58 compiler. Search for one of Microsoft/Borland/Watcom/Symantec/Metrowerks/
59 Cygwin/Mingw32 to quickly locate the instructions for your compiler.
61 All makefiles and project are located in build\msw directory.
63 Where Compiled Files are Stored
64 -------------------------------
66 After successful compilation you'll find the libraries in a subdirectory
67 of lib directory named after the compiler and DLL/static settings.
70 lib\vc_lib VC++ compiled static libraries
72 lib\bcc_lib Static libraries for Borland C++
73 lib\wat_dll Watcom C++ DLLs
75 Names of compiled wxWidgets libraries follow this scheme: libraries that don't
76 depend on GUI components begin with "wxbase" followed by a version number and,
77 optionally, letters indicating Unicode compilation ('u') and a debug build ('d').
78 The last component is the name of the wxWidgets component (unless you build the
79 library as single monolithic library; look for "Configuring the Build" below).
80 This is a typical set of release ANSI build libraries (release versions on
81 left, debug on right side):
83 wxbase29.lib wxbase29d.lib
84 wxbase29_net.lib wxbase29d_net.lib
85 wxbase29_xml.lib wxbase29d_xml.lib
86 wxmsw29_core.lib wxmsw29d_core.lib
87 wxmsw29_html.lib wxmsw29d_html.lib
88 wxmsw29_adv.lib wxmsw29d_adv.lib
90 Their Unicode debug counterparts in wxUniversal build would be
94 wxbase29ud_xml.lib (notice these libs are same for wxUniv and wxMSW)
95 wxmswuniv29ud_core.lib
96 wxmswuniv29ud_html.lib
99 These directories also contain a subdirectory with the wx/setup.h header. This
100 subdirectory is named after the port, Unicode, wxUniv and debug settings and
101 you must add it to the include paths when compiling your application. Some
104 lib\vc_lib\msw\wx\setup.h VC++ static, wxMSW
105 lib\vc_lib\mswud\wx\setup.h VC++ static, wxMSW, Unicode, debug
106 lib\vc_lib\mswunivd\wx\setup.h VC++ static, wxUniversal, debug
108 Below are compiler specific notes followed by customizing instructions that
109 apply to all compilers (search for "Configuring the Build").
111 Microsoft Visual C++ Compilation
112 ----------------------------------------------------------------
114 You may wish to visit http://wiki.wxwidgets.org/Microsoft_Visual_C%2B%2B_Guide
115 for a more informal and detailed description of the process summarized below.
117 Please note that the VC++ 6.0 project files will work for VC++ .NET as well.
119 VC++ 5.0 can also be used, providing Service Pack 3 is applied. Without it
120 you will have trouble with internal compiler errors. It is available for
121 download at: ftp://ftp.microsoft.com/developr/visualstudio/sp3/full.
123 Using project files (VC++ 6 and later):
125 1. Unarchive wxWidgets-x.y.z-vc.zip, the VC++ 6 project
126 makefiles (already included in wxMSW-x.y.z.zip and the setup version).
127 2. Open build\msw\wx.dsw, which has configurations for static
128 compilation or DLL compilation, and each of these available in
129 Unicode/ANSI, Debug/Release and wxUniversal or native variations.
130 Normally you'll use a static linking ANSI configuration.
131 Choose the Win32 Debug or Win32 Release configuration (or any other that
132 suits your needs) and use Batch Build to compile _all_ projects. If you
133 know you won't need some of the libraries (e.g. the HTML part), you don't have
134 to compile it. It will also produce similar variations on jpeg.lib,
135 png.lib, tiff.lib, zlib.lib, and regex.lib.
137 If you want to build DLL configurations in wx.dsw project you unfortunately
138 need to build them in the proper order (jpeg, png, tiff, zlib, regex, expat,
139 base, net, odbc, core, gl, html, media, qa, adv, dbgrid, xrc, aui, richtext,
140 propgrid) manually because VC6 doesn't always respect the correct build order.
142 Alternatively, use the special wx_dll.dsw project which adds the
143 dependencies to force the correct order (but, because of this, doesn't work
144 for the static libraries) or simply redo the build several times until all
145 DLLs are linked correctly. Please notice that it's normal that dbgrid project
146 doesn't build if wxUSE_ODBC is set to 0 (default).
147 3. Open a sample project file, choose a configuration such as
148 Win32 Debug using Build | Set Active Configuration..., and compile.
149 The project files don't use precompiled headers, to save disk
150 space, but you can switch PCH compiling on for greater speed.
151 NOTE: you may also use samples/samples.dsw to access all
152 sample projects without opening each workspace individually.
153 You can use the Batch Build facility to make several samples
158 1. Change directory to build\msw. Type:
160 'nmake -f makefile.vc'
162 to make the wxWidgets core library as release DLL.
163 See "Configuring the Build" for instruction how to build debug or static
166 2. Change directory to samples and type 'nmake -f makefile.vc'
167 to make all the samples. You can also make them individually.
171 Use the 'clean' target to clean all objects, libraries and
174 Note (1): if you wish to use templates, please edit
175 include\wx\msw\setup.h and set wxUSE_DEBUG_NEW_ALWAYS to 0.
176 Without this, the redefinition of 'new' will cause problems in
177 the headers. Alternatively, #undef new before including template headers.
178 You will also need to set wxUSE_IOSTREAMH to 0 if you will be
179 using templates, to avoid the non-template stream files being included
182 Note (2): libraries and applications generated with makefiles and
183 project files are now (hopefully) compatible where static libraries
184 are concerned, but please exercise caution nevertheless and if
185 possible, use one method or the other.
187 Note (3): some crash problems can be due to inconsistent compiler
188 options. If strange/weird/impossible things start to happen please
189 check (dumping IDE project file as makefile and doing text comparison
190 if necessary) that the project settings, especially the list of defined
191 symbols, struct packing, etc. are exactly the same for all items in
192 the project. After this, delete everything (including PCH) and recompile.
194 Note (4): to create your own IDE files, copy .dsp and .dsw
195 files from an existing wxWidgets sample and adapt them, or
196 visit http://wiki.wxwidgets.org/Microsoft_Visual_C%2B%2B_Guide.
198 Microsoft Visual C++ Compilation for 64-bit Windows
199 ----------------------------------------------------------------
201 Visual Studio 2005 includes 64-bit compilers, though they are not installed by
202 default; you need to select them during the installation. Both native 64-bit
203 compilers and 32-bit hosted cross compilers are included, so you do not need a
204 64-bit machine to use them (though you do to run the created executables).
205 Visual C++ Express Edition does not include 64-bit compilers.
207 64-bit compilers are also available in various SDKs, for example
208 the .NET Framework SDK:
209 http://msdn.microsoft.com/netframework/programming/64bit/devtools/
213 1. Open the VC++ 6 workspace file: build\msw\wx.dsw. Visual Studio will then
214 convert the projects to the current Visual C++ project format.
216 2. To add 64-bit targets, go to the 'Build' menu and choose 'Configuration
217 Manager...'. In the 'Active solution platform' drop down choose '<new>',
218 then you can choose either 'Itanium' or 'x64'.
220 For more detailed instructions see:
221 http://msdn2.microsoft.com/en-us/library/9yb4317s(en-us,vs.80).aspx
223 Note: 64-bit targets created this way will use the build directory of the
224 corresponding 32-bit target for some files. Therefore after building
225 for one CPU it is necessary to clean the build before building the
226 equivalent target for another CPU. We've reported the problem to MS
227 but they say it is not possible to fix it.
229 3. To build, go to the 'Build' menu and choose 'Batch Build...'. Tick all the
230 all the 'x64|Debug' or all the 'Itanium|Debug' projects, and click 'Build'.
232 This will build a debug version of the static libs. The section above on
233 Visual C++ in general has more information about adjusting the settings to
234 build other configurations.
236 4. To compile one of the samples open one of the sample projects, such as
237 samples\minimal\minimal.dsw. Visual Studio will convert the project as in
238 step 1, then add a 64-bit target as in step 2, and build.
242 1. Open a 64-bit build command prompt, for either x64 or Itanium. Change
243 directory to build\msw. Then for x64 type:
245 nmake -f makefile.vc TARGET_CPU=AMD64
249 nmake -f makefile.vc TARGET_CPU=IA64
251 This will build a debug version of wxWidgets DLLs. See "Configuring the
252 build" for instruction how to build other configurations such as a release
253 build or static libraries.
255 2. Change to the directory of one of the samples such as samples\minimal. Type
256 the same command used to build the main library, for example for x64:
258 nmake -f makefile.vc TARGET_CPU=AMD64
262 The versions of the VC++ 8 compiler included with some SDKs requires an
263 additional library to be linked or the following error is received.
265 LNK2001 unresolved external symbol __security_check_cookie
267 If you receive this error add bufferoverflowu.lib to link, e.g.:
269 nmake -f makefile.vc TARGET_CPU=AMD64 LDFLAGS=bufferoverflowu.lib
271 See http://support.microsoft.com/?id=894573 for more information.
273 Borland C++ Compilation
274 ----------------------------------------------------------------
276 The minimum version required is 5.5 (last version supported by BC++ 5.0 was
277 2.4.2), which can be downloaded for free from:
278 http://www.borland.com/products/downloads/download_cbuilder.html
280 We have found that the free Turbo Explorer and commercial BDS work fine; the
281 debugger is very good. To avoid linker errors you will need to add
282 -DSHARED=1 to the makefile line for the library
284 The version 5.6 included in Borland C++ Builder 2006 works as well after the
285 following small change: please remove the test for __WINDOWS__ from line 88
286 of the file BCCDIR\include\stl\_threads.h.
288 Compiling using the makefiles:
290 1. Change directory to build\msw. Type 'make -f makefile.bcc' to
291 make the wxWidgets core library. Ignore the compiler warnings.
292 This produces a couple of libraries in the lib\bcc_lib directory.
294 2. Change directory to a sample or demo such as samples\minimal, and type
295 'make -f makefile.bcc'. This produces a windows exe file - by default
296 in the bcc_mswd subdirectory.
298 Note (1): the wxWidgets makefiles assume dword structure alignment. Please
299 make sure that your own project or makefile settings use the
300 same alignment, or you could experience mysterious crashes. To
301 change the alignment, change CPPFLAGS in build\msw\config.bcc.
303 Note (2): if you get undefined _SQL... symbols at link time,
304 either install odbc32.lib from the BC++ CD-ROM into your BC++ lib
305 directory, or set wxUSE_ODBC to 0 in include\wx\msw\setup.h and
306 recompile wxWidgets. The same applies if compiling using the IDE.
308 Note (3): If you wish debug messages to be sent to the console in
309 debug mode, edit makefile.bcc and change /aa to /Tpe in link commands.
311 Using the Debugger and IDE in BDS or Turbo Explorer
312 ---------------------------------------------------
314 Doubleclick / open samples\minimal\borland.bdsproj. The current version
315 is to be used with a dynamic build of wxWidgets-made by running
316 make -f Makefile.bcc -DBUILD=debug -DSHARED=1
317 in wxWidgets\build\msw. You also need the wxWidgets\lib\bcc_dll
318 directory in your PATH. The debugger tracks your source and also
319 traces into the wxWidgets sources.
321 To use this to debug other samples, copy the borland_ide.cpp
322 and borland.bdsproj files, then replace all occurrences of
323 "minimal" with the name of the new project files
325 Compilation succeeds with CBuilderX personal edition and CBuilder6, but
326 you may have to copy make.exe from the 5.5 download to the new bin directory.
328 Compiling using the IDE files for Borland C++ 5.0 and using CBuilder IDE
329 (v1-v6): not supported
333 In all of your wxWidgets applications, your source code should include
334 the following preprocessor directive:
340 (check the samples -- e.g., \wx2\samples\minimal\minimal.cpp -- for
343 Borland 16 Bit Compilation for Windows 3.1
344 ----------------------------------------------------------------
346 The last version of wxWidgets to support 16-bit compilation with Borland was
347 2.2.7 - Please download and read the instructions in that release
349 Watcom C++ 10.6/11 and OpenWatcom Compilation
350 ----------------------------------------------------------------
352 1. Change directory to build\msw. Type 'wmake -f makefile.wat' to
353 make the wxWidgets core library.
355 2. Change directory to samples\minimal and type 'wmake -f makefile.wat'
356 to make this sample. Repeat for other samples of interest.
358 Note (1): if your installation of Watcom doesn't have odbc32.lib file and
359 you need it (i.e. you have wxUSE_ODBC=1), you can use the file
360 from lib\watcom directory. See the notes in that directory.
362 Note (2): if variant.cpp is compiled with date/time class options, the linker
363 gives up. So the date/time option is switched off for Watcom C++.
364 Also, wxAutomationObject is not compiled with Watcom C++ 10.
366 Note (3): RawBitmaps won't work at present because they use unsupported template
369 Note (4): if Watcom can't read the precompiled header when building a sample,
370 try deleting .pch files in build\msw\wat_* and compiling
373 Note (5): wxUSE_STD_STRING is disabled in wx/string.h for Watcom as this
374 compiler doesn't come with standard C++ library headers by default.
375 If you install STLPort or another STL implementation, you'll need to
376 edit wx/string.h and remove the check for Digital Mars in it (search
380 Metrowerks CodeWarrior Compilation
381 ----------------------------------------------------------------
383 ** NOTE: We don't use Metrowerks compiler any more and so depend on
384 ** your contributions to keep it up to date. It is possible that
385 ** the project files mentioned below are out of date due to recently
386 ** added files, please add them manually if you get linking errors.
387 ** The authoritative list of files is in build/bakefiles/files.bkl
389 1. CodeWarrior Pro 7 project files in XML format are already
390 included in wxMSW-2.8.x.zip and the setup version.
392 2. Review the file include\wx\msw\setup.h (or include\wx\msw\setup0.h if
393 you are working from the SVN version) to make sure the settings reflect
394 what you want. If you aren't sure, leave it alone and go with the
395 default settings. A few notes:
396 - Don't use wxUSE_DEBUG_NEW_ALWAYS: it doesn't mix well with MSL
397 - wxUSE_GLOBAL_MEMORY_OPERATORS works, but memory leak reports
398 will be rather confusing due to interactions with the MSL ANSI
401 3. The project file to build the Win32 wxWidgets libraries relies on the
402 Batch File Runner plug-in. This plug-in is not installed as part of
403 a normal CW7 installation. However, you can find this plug-in on the
404 CodeWarrior Reference CD, in the Thrill Seekers folder; it's called the
405 "Batch File Post Linker".
407 4. If you choose not to install the Batch File Runner plug-in, then you
408 need to do the following by hand:
409 (1) Create the directories lib\cw7msw\include\wx and copy the file
410 include\wx\msw\setup.h (or include\wx\msw\setup0.h if you are
411 working from the SVN version) to lib\cw7msw\include\wx\setup.h
412 (2) Create the directories lib\cw7mswd\include\wx and copy the file
413 include\wx\msw\setup.h (or include\wx\msw\setup0.h if you are
414 working from the SVN version) to lib\cw7mswd\include\wx\setup.h
416 5. Import src\wxWidgetsW7.xml to create the project file wxWidgetsW7.mcp.
417 Store this project file in directory src. You may get warnings about
418 not being able to find certain project paths; ignore these warnings, the
419 appropriate paths will be created during the build by the Batch File Runner.
421 6. Choose the wxlib Win32 debug or wxlib Win32 Release target and build. You
422 will get some warnings about hidden virtual functions, illegal conversions
423 from const pointers to pointers, etc., all of which you can safely ignore.
424 ***Note: if you get errors that the compiler can't find "wx/setup.h", just
425 stop the build and build again. These errors occur because sometimes the
426 compiler starts doing its thing before the copying of setup.h has completed.
428 7. The following libraries will be produced depending on chosen
430 - wx_x86.lib ANSI Release (static)
431 - wx_x86_d.lib ANSI Debug (static)
433 8. Sorry, I haven't had time yet to create and test Unicode or DLL versions.
434 Volunteers for this are welcome (as neither DLLs nor Unicode builds are
435 big priorities for me ;).
437 9. CodeWarrior Pro7 project files (in XML format) are also provided for some
438 of the samples. In particular, there are project files for the minimal,
439 controls, dialogs, dnd, nd docview samples. You can use these project
440 files as templates for the other samples and for your own projects.
441 - For example, to make a project file for the "grid" sample,
442 just copy the project file for the "minimal" sample, minimalW7.mcp
443 (made by importing minimalW7.xml into CodeWarrior), into the
444 sample/grid directory, calling it gridW7.mcp. Open
445 newgridW7.mcp and revise the project by deleting the files
446 minimal.rc and minimal.cpp and adding the files griddemo.rc and
447 griddemo.cpp. Build and run....
450 Cygwin/MinGW Compilation
451 ----------------------------------------------------------------
453 wxWidgets supports Cygwin (formerly GnuWin32) betas and
454 releases, and MinGW. Cygwin can be downloaded from:
456 http://sources.redhat.com/cygwin/
460 http://www.mingw.org/
462 Both Cygwin and MinGW can be used with configure (assuming you have MSYS
463 installed in case of MinGW). You will need new enough MinGW version, preferably
464 MinGW 2.0 (ships with gcc3) or at least 1.0 (gcc-2.95.3). GCC versions older
465 than 2.95.3 don't work; you can use wxWidgets 2.4 with them.
467 NOTE: some notes specific to old Cygwin (< 1.1.x) are at the end of this
468 section (see OLD VERSIONS)
470 There are two methods of compiling wxWidgets, by using the
471 makefiles provided or by using 'configure'.
473 Retrieve and install the latest version of Cygwin, or MinGW, as per
474 the instructions with either of these packages.
476 If using MinGW, you can download the add-on MSYS package to
477 provide Unix-like tools that you'll need to build wxWidgets using configure.
479 Using makefiles Directly
480 ----------------------------------------------------------------
482 NOTE: The makefile.gcc makefiles are for compilation under MinGW using
483 Windows command interpreter (command.com/cmd.exe), they won't work in
484 other environments (such as UNIX or Unix-like, e.g. MSYS where you have
485 to use configure instead, see the section below)
487 Use the makefile.gcc files for compiling wxWidgets and samples,
488 e.g. to compile a debugging version of wxWidgets:
490 > mingw32-make -f makefile.gcc BUILD=debug
491 > cd c:\wx\samples\minimal
492 > mingw32-make -f makefile.gcc BUILD=debug
493 (See below for more options.)
495 Notice that Windows command interpreter (cmd.exe) and mingw32-make must be
496 used, using Bash (sh.exe) and make.exe from MSYS will only work when using
497 configure-based build procedure described below!
499 You can also use the 'strip' command to reduce executable/dll size (note that
500 stripping an executable/dll will remove debug information!).
502 All targets have 'clean' targets to allow removal of object files
503 and other intermediate compiler files.
506 ----------------------------------------------------------------
508 Instead of using the makefiles, you can use the configure
509 system to generate appropriate makefiles, as used on Unix
510 and Mac OS X systems.
512 Change directory to the root of the wxWidgets distribution,
513 make a build directory, and run configure and make in this directory.
520 ../configure --with-msw --enable-debug --enable-debug_gdb --disable-shared
522 make install % This step is optional, see note (6) below.
529 1. See also the Cygwin/MinGW on the web site or CD-ROM for
530 further information about using wxWidgets with these compilers.
532 2. libwx.a is 100 MB or more - but much less if compiled with no
533 debug info (-g0) and level 4 optimization (-O4).
535 3. If you get a link error under MinGW 2.95.2 referring to:
537 EnumDAdvise__11IDataObjectPP13IEnumSTATDATA@8
539 then you need to edit the file objidl.h at line 663 and add
540 a missing PURE keyword:
542 STDMETHOD(EnumDAdvise)(THIS_ IEnumSTATDATA**) PURE;
544 4. There's a bug in MinGW headers for some early distributions.
546 in include/windows32/defines.h, where it says:
548 #define LPSTR_TEXTCALLBACKA (LPSTR)-1L)
552 #define LPSTR_TEXTCALLBACKA ((LPSTR)-1L)
556 5. OpenGL support should work with MinGW as-is. However,
557 if you wish to generate import libraries appropriate either for
558 the MS OpenGL libraries or the SGI OpenGL libraries, go to
559 include/wx/msw/gl and use:
561 dlltool -k -d opengl.def -llibopengl.a
565 dlltool -k -d opengl32.def -llibopengl32.a
567 and similarly for glu[32].def.
569 6. The 'make install' step is optional, and copies files
572 /usr/local/lib - wxmswXYZd.dll.a and wxmswXYZd.dll
573 /usr/local/include/wx - wxWidgets header files
574 /usr/local/bin - wx-config
576 You may need to do this if using wx-config with the
579 7. With Cygwin, you can invoke gdb --nw myfile.exe to
580 debug an executable. If there are memory leaks, they will be
581 flagged when the program quits. You can use Cygwin gdb
582 to debug MinGW executables.
584 8. Note that gcc's precompiled headers do not work on current versions of
585 Cygwin. If your version of Cygwin is affected you will need to use the
586 --disable-precomp-headers configure option.
590 - Modify the file wx/src/cygnus.bat (or mingw32.bat or mingegcs.bat)
591 to set up appropriate variables, if necessary mounting drives.
592 Run it before compiling.
594 - For Cygwin, make sure there's a \tmp directory on your
595 Windows drive or bison will crash (actually you don't need
596 bison for ordinary wxWidgets compilation: a pre-generated .c file is
599 - If using GnuWin32 b18, you will need to copy windres.exe
600 from e.g. the MinGW distribution, to a directory in your path.
603 Symantec & DigitalMars C++ Compilation
604 ----------------------------------------------------------------
606 The DigitalMars compiler is a free successor to the Symantec compiler
607 and can be downloaded from http://www.digitalmars.com/
609 1. You need to download and unzip in turn (later packages will overwrite
611 Digital Mars C/C++ Compiler Version 8.40 or later
613 from http://www.digitalmars.com/download/freecompiler.html
615 2. Change directory to build\msw and type 'make -f makefile.dmc' to
616 make the wxWidgets core library.
618 3. Change directory to samples\minimal and type 'make -f makefile.dmc'
619 to make this sample. Most of the other samples also work.
622 Note that if you don't have the files makefile.dmc you may create them yourself
623 using bakefile tool according to the instructions in build\bakefiles\README:
626 bakefile_gen -f dmars -b wx.bkl
627 bakefile_gen -f dmars -b ../../samples/minimal/minimal.bkl
630 Note that wxUSE_STD_STRING is disabled in wx/string.h for Digital Mars as this
631 compiler doesn't come with standard C++ library headers by default. If you
632 install STLPort or another STL implementation, you'll need to edit wx/string.h
633 and remove the check for Digital Mars in it (search for __DMC__).
636 16-bit compilation is no longer supported.
638 Configuring the Build
639 ================================================================
641 So far the instructions only explain how to build release DLLs of wxWidgets
642 and did not cover any configuration. It is possible to change many aspects of
643 the build, including debug/release and ANSI/Unicode settings. All makefiles in
644 build\msw directory use same options (with a few exceptions documented below)
645 and the only difference between them is in object files and library directory
646 names and in make invocation command.
648 Changing the Settings
649 ----------------------------------------------------------------
651 There are two ways to modify the settings: either by passing the values as
652 arguments when invoking make or by editing build\msw\config.$(compiler) file
653 where $(compiler) is same extension as the makefile you use has (see below).
654 The latter is good for setting options that never change in your development
655 process (e.g. GCC_VERSION or VENDOR). If you want to build several versions of
656 wxWidgets and use them side by side, the former method is better. Settings in
657 config.* files are shared by all makefiles (samples, contrib, main library),
658 but if you pass the options as arguments, you must use same arguments you used
659 for the library when building samples or contrib libraries!
661 Examples of invoking make in Unicode debug build (other options described
662 below are set analogically):
665 > nmake -f makefile.vc BUILD=debug UNICODE=1
668 > make -f makefile.bcc -DBUILD=debug -DUNICODE=1
669 (Note that you have to use -D to set the variable, unlike in other make
673 > wmake -f makefile.wat BUILD=debug UNICODE=1
675 MinGW using native makefiles:
676 > mingw32-make -f makefile.gcc BUILD=debug UNICODE=1
678 MinGW using configure:
679 > ./configure --enable-debug --enable-unicode
680 (see ./configure --help on details; configure is not covered in this
683 Cygwin using configure:
684 > ./configure --disable-precomp-headers --enable-debug --enable-unicode
685 (use --disable-precomp-headers if Cygwin doesn't support precompiled
688 Brief explanation of options and possible values is in every
689 build\msw\config.* file; more detailed description follows.
692 ----------------------------------------------------------------
695 Builds release version of the library. It differs from default 'debug'
696 in lack of appended 'd' in name of library, does not define __WXDEBUG__
697 and not include debug information compiled into object files and the
701 Build shared libraries (DLLs). By default, DLLs are not built
705 To build ANSI versions of the libraries, add UNICODE=0 to make invocation
706 (default is UNICODE=1). If you want to be able to use Unicode version on
707 Windows9x, you will need to set MSLU=1 as well.
709 This option affect name of the library ('u' is appended) and the directory
710 where the library and setup.h are store (ditto).
713 Build wxUniversal instead of native wxMSW (see
714 http://www.wxwidgets.org/wxuniv.htm for more information).
717 ----------------------------------------------------------------
720 Starting with version 2.5.1, wxWidgets has the ability to be built as
721 several smaller libraries instead of single big one as used to be the case
722 in 2.4 and older versions. This is called "multilib build" and is the
723 default behaviour of makefiles. You can still build single library
724 ("monolithic build") by setting MONOLITHIC variable to 1.
727 Disable building GUI parts of the library, build only wxBase components used
728 by console applications. Note that if you leave USE_GUI=1 then both wxBase
729 and GUI libraries are built. If you are building monolithic library, then
730 you should set wxUSE_GUI to 1 in setup.h.
733 Build wxmsw29_gl.lib library with OpenGL integration class wxGLCanvas.
734 You must also modify your setup.h to #define wxUSE_GLCANVAS 1. Note that
735 OpenGL library is always built as additional library, even in monolithic
739 Build two additional libraries in multilib mode, one with database
740 classes and one with wxGrid database support. You must
741 #define wxUSE_ODBC 1 in setup.h
744 Do not build wxHTML library. If MONOLITHIC=1, then you must also
745 #define wxUSE_HTML 1 in setup.h.
748 Do not build XRC resources library. If MONOLITHIC=1, then you must also
749 #define wxUSE_HTML 1 in setup.h.
752 Links static version of C and C++ runtime libraries into the executable, so
753 that the program does not depend on DLLs provided with the compiler (e.g.
754 Visual C++'s msvcrt.dll or Borland's cc3250mt.dll).
755 Caution: Do not use static runtime libraries when building DLL (SHARED=1)!
758 Enables MSLU (Microsoft Layer for Unicode). This setting makes sense only if
759 used together with UNICODE=1. If you want to be able to use Unicode version
760 on Windows9x, you will need MSLU (Microsoft Layer for Unicode) runtime DLL
761 and import lib. The former can be downloaded from Microsoft, the latter is
762 part of the latest Platform SDK from Microsoft (see msdn.microsoft.com for
763 details). An alternative implementation of import library can be downloaded
764 from http://libunicows.sourceforge.net - unlike the official one, this one
765 works with other compilers and does not require 300+ MB Platform SDK update.
769 If set to 1, define __WXDEBUG__ symbol, append 'd' to library name and do
770 sanity checks at runtime. If set to 0, don't do it. By default, this is
771 governed by BUILD option (if 'debug', DEBUG_FLAG=1, if 'release' it is 0),
772 but it is sometimes desirable to modify default behaviour and e.g. define
773 __WXDEBUG__ even in release builds.
777 Same as DEBUG_FLAG in behaviour, this option affects whether debugging
778 information is included in the executable or not.
780 TARGET_CPU=AMD64|IA64
781 (VC++ only.) Set this variable to build for x86_64 systems. If unset, x86
784 VENDOR=<your company name>
785 Set this to a short string identifying your company if you are planning to
786 distribute wxWidgets DLLs with your application. Default value is 'custom'.
787 This string is included as part of DLL name. wxWidgets DLLs contain compiler
788 name, version information and vendor name in them. For example
789 wxmsw290_core_bcc_custom.dll is one of DLLs build using Borland C++ with
790 default settings. If you set VENDOR=mycorp, the name will change to
791 wxmsw290_core_bcc_mycorp.dll.
793 CFG=<configuration name>
794 Sets configuration name so that you can have multiple wxWidgets builds with
795 different setup.h settings coexisting in same tree. See "Object and library
796 directories" below for more information.
798 COMPILER_PREFIX=<string>
799 If you build with multiple versions of the same compiler, you can put
800 their outputs into directories like "vc6_lib", "vc8_lib" etc. instead of
801 "vc_lib" by setting this variable to e.g. "vc6". This is merely a
802 convenience variable, you can achieve the same effect (but different
803 directory names) with the CFG option.
806 Compiler-Specific Options
807 ----------------------------------------------------------------
811 If you are using gcc-2.95 instead of gcc3, you must set GCC_VERSION to
812 2.95. In build\msw\config.gcc, change
821 If set to 1, msvcrtd.dll is used, if to 0, msvcrt.dll is used. By default
822 msvcrtd.dll is used only if the executable contains debug info and
823 msvcrt.dll if it doesn't. It is sometimes desirable to build with debug info
824 and still link against msvcrt.dll (e.g. when you want to ship the app to
825 customers and still have usable .pdb files with debug information) and this
826 setting makes it possible.
828 Fine-tuning the Compiler
829 ----------------------------------------------------------------
831 All makefiles have variables that you can use to specify additional options
832 passed to the compiler or linker. You won't need this in most cases, but if you
833 do, simply add desired flags to CFLAGS (for C compiler), CXXFLAGS (for C++
834 compiler), CPPFLAGS (for both C and C++ compiler) and LDFLAGS (the linker).
836 Object and Library Directories
837 ----------------------------------------------------------------
839 All object files produced during a library build are stored in a directory under
840 build\msw. Its name is derived from the build settings and CFG variable and from
841 the compiler name. Examples of directory names:
843 build\msw\bcc_msw SHARED=0
844 build\msw\bcc_mswdll SHARED=1
845 build\msw\bcc_mswunivd SHARED=0, WXUNIV=1, BUILD=debug
846 build\msw\vc_mswunivd ditto, with Visual C++
848 Libraries and DLLs are copied into a subdirectory of the lib directory with a
849 name derived from the compiler and a static/DLL setting and setup.h into a
850 directory with a name that contains other settings:
853 lib\bcc_lib\msw\wx\setup.h
855 lib\bcc_dll\msw\wx\setup.h
857 lib\bcc_lib\mswunivd\wx\setup.h
859 lib\vc_lib\mswunivd\wx\setup.h
861 Each lib\ subdirectory has wx subdirectory with setup.h as seen above.
862 This file is copied there from include\wx\msw\setup.h (and if it doesn't exist,
863 from include\wx\msw\setup0.h) and this is the copy of setup.h that is used by
864 all samples and should be used by your apps as well. If you are doing changes
865 to setup.h, you should do them in this file, _not_ in include\wx\msw\setup.h.
867 If you set CFG to something, the value is appended to directory names. E.g.
868 for CFG=MyBuild, you'll have object files in
870 build\msw\bcc_mswMyBuild
871 build\msw\bcc_mswdllMyBuild
880 By now it is clear what CFG is for: builds with different CFG settings don't
881 share any files and they use different setup.h files. For example, this allows
882 you to have two static debug builds, one with wxUSE_SOCKETS=0 and one with sockets
883 enabled (without CFG, both of them would be put into same directory and there
884 would be conflicts between the files).
887 =================================================================
889 - Debugging: under Windows 95, debugging output isn't output in
890 the same way that it is under NT or Windows 3.1.
891 Please see DebugView available from http://www.sysinternals.com.