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