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