X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e80264fdbeac5faccb10210a936a825070ab57b0..ce1546160882d1ac98932420d7aeb4ff21d06301:/docs/msw/install.txt?ds=sidebyside diff --git a/docs/msw/install.txt b/docs/msw/install.txt index a68fff35ef..123d796484 100644 --- a/docs/msw/install.txt +++ b/docs/msw/install.txt @@ -24,8 +24,15 @@ fixing the problems so this ensures that your report will be addressed sooner. -Unarchiving -=========== +Table of Contents: + - Installation + - Building wxWidgets + - Configuring the Build + - Building Applications Using wxWidgets + + +Installation +============ Please simply uncompress the .zip file manually into any directory. However we advise avoiding using directories with spaces in their @@ -33,9 +40,6 @@ names (notably "C:\Program Files") as this risks creating problems with makefiles and other command-line tools. -Configuration -============= - In the majority of cases, you don't need to change the default library build configuration. If you wish to change some of the build options you need to edit the include/wx/msw/setup.h file enabling or @@ -50,13 +54,21 @@ Notice that this file is later copied into a directory under lib for each of the build configurations which allows to have different build options for different configurations too. +See "Configuring the Build" section for more information. + -Compilation -=========== +Building wxWidgets +================== The following sections explain how to compile wxWidgets with each supported -compiler. Search for one of Microsoft/Borland/Watcom/Symantec/Metrowerks/ -Cygwin/Mingw32 to quickly locate the instructions for your compiler. +compiler, see the "Building Applications" section about the instructions for +building your application using wxWidgets. + +Search for one of Microsoft/Borland/Watcom/Symantec/Cygwin/Mingw32 keywords +to quickly locate the instructions for your compiler. Notice that the primary +compilers for wxWidgets under MSW are Microsoft Visual C++ and GNU g++, other +compilers are more rarely tested and might not work so please consider using +one of these two if possible. All makefiles and project are located in build\msw directory. @@ -114,11 +126,10 @@ Microsoft Visual C++ Compilation You may wish to visit http://wiki.wxwidgets.org/Microsoft_Visual_C%2B%2B_Guide for a more informal and detailed description of the process summarized below. -Please note that the VC++ 6.0 project files will work for VC++ .NET as well. - -VC++ 5.0 can also be used, providing Service Pack 3 is applied. Without it -you will have trouble with internal compiler errors. It is available for -download at: ftp://ftp.microsoft.com/developr/visualstudio/sp3/full. +Please note that currently ready to use projeect files are provided for VC++ +versions 6 through to 9 (also known as 6, 2003, 2005 and 2008). For VC++ 10 and +11 (2010 and 2012, respectively), you will need to import the existing VC9 +project files. Using project files (VC++ 6 and later): @@ -127,7 +138,6 @@ Using project files (VC++ 6 and later): 2. Open build\msw\wx.dsw, which has configurations for static compilation or DLL compilation, and each of these available in Unicode/ANSI, Debug/Release and wxUniversal or native variations. - Normally you'll use a static linking ANSI configuration. Choose the Win32 Debug or Win32 Release configuration (or any other that suits your needs) and use Batch Build to compile _all_ projects. If you know you won't need some of the libraries (e.g. the HTML part), you don't have @@ -136,7 +146,7 @@ Using project files (VC++ 6 and later): If you want to build DLL configurations in wx.dsw project you unfortunately need to build them in the proper order (jpeg, png, tiff, zlib, regex, expat, - base, net, odbc, core, gl, html, media, qa, adv, dbgrid, xrc, aui, richtext, + base, net, core, gl, html, media, qa, adv, xrc, aui, richtext, propgrid) manually because VC6 doesn't always respect the correct build order. Alternatively, use the special wx_dll.dsw project which adds the @@ -209,8 +219,8 @@ the .NET Framework SDK: Using project files: -1. Open the VC++ 6 workspace file: build\msw\wx.dsw. Visual Studio will then - convert the projects to the current Visual C++ project format. +1. Open the solution file for the version you use: build\msw\wx_vc8.sln or + wx_vc9.sln. 2. To add 64-bit targets, go to the 'Build' menu and choose 'Configuration Manager...'. In the 'Active solution platform' drop down choose '', @@ -233,7 +243,7 @@ Using project files: build other configurations. 4. To compile one of the samples open one of the sample projects, such as - samples\minimal\minimal.dsw. Visual Studio will convert the project as in + samples\minimal\minimal_vc7.vcproj. Visual Studio will convert the project as in step 1, then add a 64-bit target as in step 2, and build. Using makefiles: @@ -241,7 +251,7 @@ Using makefiles: 1. Open a 64-bit build command prompt, for either x64 or Itanium. Change directory to build\msw. Then for x64 type: - nmake -f makefile.vc TARGET_CPU=AMD64 + nmake -f makefile.vc TARGET_CPU=X64 or for Itanium: @@ -254,7 +264,7 @@ Using makefiles: 2. Change to the directory of one of the samples such as samples\minimal. Type the same command used to build the main library, for example for x64: - nmake -f makefile.vc TARGET_CPU=AMD64 + nmake -f makefile.vc TARGET_CPU=X64 Notes: @@ -265,7 +275,7 @@ additional library to be linked or the following error is received. If you receive this error add bufferoverflowu.lib to link, e.g.: - nmake -f makefile.vc TARGET_CPU=AMD64 LDFLAGS=bufferoverflowu.lib + nmake -f makefile.vc TARGET_CPU=X64 LDFLAGS=bufferoverflowu.lib See http://support.microsoft.com/?id=894573 for more information. @@ -334,12 +344,6 @@ the following preprocessor directive: (check the samples -- e.g., \wx2\samples\minimal\minimal.cpp -- for more details) -Borland 16 Bit Compilation for Windows 3.1 ----------------------------------------------------------------- - -The last version of wxWidgets to support 16-bit compilation with Borland was -2.2.7 - Please download and read the instructions in that release - Watcom C++ 10.6/11 and OpenWatcom Compilation ---------------------------------------------------------------- @@ -367,76 +371,6 @@ Note (4): wxUSE_STD_STRING is disabled in wx/string.h for Watcom as this for __WATCOM__). -Metrowerks CodeWarrior Compilation ----------------------------------------------------------------- - -** NOTE: We don't use Metrowerks compiler any more and so depend on -** your contributions to keep it up to date. It is possible that -** the project files mentioned below are out of date due to recently -** added files, please add them manually if you get linking errors. -** The authoritative list of files is in build/bakefiles/files.bkl - -1. CodeWarrior Pro 7 project files in XML format are already - included in wxMSW-2.8.x.zip and the setup version. - -2. Review the file include\wx\msw\setup.h (or include\wx\msw\setup0.h if - you are working from the SVN version) to make sure the settings reflect - what you want. If you aren't sure, leave it alone and go with the - default settings. A few notes: - - Don't use wxUSE_DEBUG_NEW_ALWAYS: it doesn't mix well with MSL - - wxUSE_GLOBAL_MEMORY_OPERATORS works, but memory leak reports - will be rather confusing due to interactions with the MSL ANSI - and runtime libs. - -3. The project file to build the Win32 wxWidgets libraries relies on the - Batch File Runner plug-in. This plug-in is not installed as part of - a normal CW7 installation. However, you can find this plug-in on the - CodeWarrior Reference CD, in the Thrill Seekers folder; it's called the - "Batch File Post Linker". - -4. If you choose not to install the Batch File Runner plug-in, then you - need to do the following by hand: - (1) Create the directories lib\cw7msw\include\wx and copy the file - include\wx\msw\setup.h (or include\wx\msw\setup0.h if you are - working from the SVN version) to lib\cw7msw\include\wx\setup.h - (2) Create the directories lib\cw7mswd\include\wx and copy the file - include\wx\msw\setup.h (or include\wx\msw\setup0.h if you are - working from the SVN version) to lib\cw7mswd\include\wx\setup.h - -5. Import src\wxWidgetsW7.xml to create the project file wxWidgetsW7.mcp. - Store this project file in directory src. You may get warnings about - not being able to find certain project paths; ignore these warnings, the - appropriate paths will be created during the build by the Batch File Runner. - -6. Choose the wxlib Win32 debug or wxlib Win32 Release target and build. You - will get some warnings about hidden virtual functions, illegal conversions - from const pointers to pointers, etc., all of which you can safely ignore. - ***Note: if you get errors that the compiler can't find "wx/setup.h", just - stop the build and build again. These errors occur because sometimes the - compiler starts doing its thing before the copying of setup.h has completed. - -7. The following libraries will be produced depending on chosen - target: - - wx_x86.lib ANSI Release (static) - - wx_x86_d.lib ANSI Debug (static) - -8. Sorry, I haven't had time yet to create and test Unicode or DLL versions. - Volunteers for this are welcome (as neither DLLs nor Unicode builds are - big priorities for me ;). - -9. CodeWarrior Pro7 project files (in XML format) are also provided for some - of the samples. In particular, there are project files for the minimal, - controls, dialogs, dnd, nd docview samples. You can use these project - files as templates for the other samples and for your own projects. - - For example, to make a project file for the "grid" sample, - just copy the project file for the "minimal" sample, minimalW7.mcp - (made by importing minimalW7.xml into CodeWarrior), into the - sample/grid directory, calling it gridW7.mcp. Open - newgridW7.mcp and revise the project by deleting the files - minimal.rc and minimal.cpp and adding the files griddemo.rc and - griddemo.cpp. Build and run.... - - Cygwin/MinGW Compilation ---------------------------------------------------------------- @@ -451,8 +385,7 @@ and MinGW from: Both Cygwin and MinGW can be used with configure (assuming you have MSYS installed in case of MinGW). You will need new enough MinGW version, preferably -MinGW 2.0 (ships with gcc3) or at least 1.0 (gcc-2.95.3). GCC versions older -than 2.95.3 don't work; you can use wxWidgets 2.4 with them. +MinGW 3.4.2+ (ships with gcc3). NOTE: some notes specific to old Cygwin (< 1.1.x) are at the end of this section (see OLD VERSIONS) @@ -522,16 +455,7 @@ Notes: 2. libwx.a is 100 MB or more - but much less if compiled with no debug info (-g0) and level 4 optimization (-O4). -3. If you get a link error under MinGW 2.95.2 referring to: - - EnumDAdvise__11IDataObjectPP13IEnumSTATDATA@8 - - then you need to edit the file objidl.h at line 663 and add - a missing PURE keyword: - - STDMETHOD(EnumDAdvise)(THIS_ IEnumSTATDATA**) PURE; - -4. There's a bug in MinGW headers for some early distributions. +3. There's a bug in MinGW headers for some early distributions. in include/windows32/defines.h, where it says: @@ -543,7 +467,7 @@ Notes: (a missing bracket). -5. OpenGL support should work with MinGW as-is. However, +4. OpenGL support should work with MinGW as-is. However, if you wish to generate import libraries appropriate either for the MS OpenGL libraries or the SGI OpenGL libraries, go to include/wx/msw/gl and use: @@ -556,7 +480,7 @@ Notes: and similarly for glu[32].def. -6. The 'make install' step is optional, and copies files +5. The 'make install' step is optional, and copies files as follows: /usr/local/lib - wxmswXYZd.dll.a and wxmswXYZd.dll @@ -566,12 +490,12 @@ Notes: You may need to do this if using wx-config with the default root path. -7. With Cygwin, you can invoke gdb --nw myfile.exe to +6. With Cygwin, you can invoke gdb --nw myfile.exe to debug an executable. If there are memory leaks, they will be flagged when the program quits. You can use Cygwin gdb to debug MinGW executables. -8. Note that gcc's precompiled headers do not work on current versions of +7. Note that gcc's precompiled headers do not work on current versions of Cygwin. If your version of Cygwin is affected you will need to use the --disable-precomp-headers configure option. @@ -590,50 +514,26 @@ OLD VERSIONS: from e.g. the MinGW distribution, to a directory in your path. -Symantec & DigitalMars C++ Compilation +DigitalMars C++ Compilation ---------------------------------------------------------------- -The DigitalMars compiler is a free successor to the Symantec compiler -and can be downloaded from http://www.digitalmars.com/ - -1. You need to download and unzip in turn (later packages will overwrite - older files) - Digital Mars C/C++ Compiler Version 8.40 or later - Basic utilities - from http://www.digitalmars.com/download/freecompiler.html - -2. Change directory to build\msw and type 'make -f makefile.dmc' to - make the wxWidgets core library. - -3. Change directory to samples\minimal and type 'make -f makefile.dmc' - to make this sample. Most of the other samples also work. - - -Note that if you don't have the files makefile.dmc you may create them yourself -using bakefile tool according to the instructions in build\bakefiles\README: - - cd build\bakefiles - bakefile_gen -f dmars -b wx.bkl - bakefile_gen -f dmars -b ../../samples/minimal/minimal.bkl +Digital Mars compiler is no longer updated as the project is discontinued. +wxWidgets 2.8 was the last version to compile with this compiler. -Note that wxUSE_STD_STRING is disabled in wx/string.h for Digital Mars as this -compiler doesn't come with standard C++ library headers by default. If you -install STLPort or another STL implementation, you'll need to edit wx/string.h -and remove the check for Digital Mars in it (search for __DMC__). - - -16-bit compilation is no longer supported. - Configuring the Build ================================================================ So far the instructions only explain how to build release DLLs of wxWidgets and did not cover any configuration. It is possible to change many aspects of -the build, including debug/release and ANSI/Unicode settings. All makefiles in -build\msw directory use same options (with a few exceptions documented below) -and the only difference between them is in object files and library directory -names and in make invocation command. +the build, including debug/release and static/dynamic settings. + +Notice that in the previous versions of wxWidgets it was possible to build the +library in either ANSI or Unicode mode but in wxWidgets 2.9 and later only a +single, combined, build mode exists. It is still possible to set UNICODE=0 to +disable Unicode support entirely but it is strongly not recommended and should +be never necessary. + Changing the Settings ---------------------------------------------------------------- @@ -652,26 +552,26 @@ Examples of invoking make in Unicode debug build (other options described below are set analogically): Visual C++: - > nmake -f makefile.vc BUILD=debug UNICODE=1 + > nmake -f makefile.vc BUILD=debug Borland C++: - > make -f makefile.bcc -DBUILD=debug -DUNICODE=1 + > make -f makefile.bcc -DBUILD=debug (Note that you have to use -D to set the variable, unlike in other make tools!) Watcom C/C++: - > wmake -f makefile.wat BUILD=debug UNICODE=1 + > wmake -f makefile.wat BUILD=debug MinGW using native makefiles: - > mingw32-make -f makefile.gcc BUILD=debug UNICODE=1 + > mingw32-make -f makefile.gcc BUILD=debug MinGW using configure: - > ./configure --enable-debug --enable-unicode + > ./configure --enable-debug (see ./configure --help on details; configure is not covered in this section) Cygwin using configure: - > ./configure --disable-precomp-headers --enable-debug --enable-unicode + > ./configure --disable-precomp-headers --enable-debug (use --disable-precomp-headers if Cygwin doesn't support precompiled headers) @@ -682,22 +582,23 @@ Basic Options ---------------------------------------------------------------- BUILD=release - Builds release version of the library. It differs from default 'debug' - in lack of appended 'd' in name of library, does not define __WXDEBUG__ - and not include debug information compiled into object files and the - executable. + Builds release version of the library. It differs from default 'debug' in + lack of appended 'd' in name of library and uses the release CRT libraries + instead of debug ones. Notice that even release builds do include debug + information by default, see DEBUG_FLAG for more information about it. SHARED=1 Build shared libraries (DLLs). By default, DLLs are not built (SHARED=0). UNICODE=0 - To build ANSI versions of the libraries, add UNICODE=0 to make invocation - (default is UNICODE=1). If you want to be able to use Unicode version on - Windows9x, you will need to set MSLU=1 as well. + To completely disable Unicode support (default is UNICODE=1). It should not + be necessary to do this unless, perhaps, you still wish to target Win9x + systems and can't use MSLU (which requires MSLU=1) for some reason. - This option affect name of the library ('u' is appended) and the directory - where the library and setup.h are store (ditto). + This option affect name of the library ('u' is appended in the default + Unicode build) and the directory where the library and setup.h are store + (ditto). WXUNIV=1 Build wxUniversal instead of native wxMSW (see @@ -751,18 +652,24 @@ MSLU=1 DEBUG_FLAG=0 DEBUG_FLAG=1 - If set to 1, define __WXDEBUG__ symbol, append 'd' to library name and do - sanity checks at runtime. If set to 0, don't do it. By default, this is - governed by BUILD option (if 'debug', DEBUG_FLAG=1, if 'release' it is 0), - but it is sometimes desirable to modify default behaviour and e.g. define - __WXDEBUG__ even in release builds. +DEBUG_FLAG=2 + Specifies the level of debug support in wxWidgets. Notice that + this is independent from both BUILD and DEBUG_INFO options. By default + always set to 1 meaning that debug support is enabled: asserts are compiled + into the code (they are inactive by default in release builds of the + application but can be enabled), wxLogDebug() and wxLogTrace() are available + and __WXDEBUG__ is defined. Setting it to 0 completely disables all + debugging code in wxWidgets while setting it to 2 enables even the time + consuming assertions and checks which are deemed to be unsuitable for + production environment. DEBUG_INFO=0 DEBUG_INFO=1 - Same as DEBUG_FLAG in behaviour, this option affects whether debugging - information is included in the executable or not. + This option affects whether debugging information is generated. If + omitted or set to 'default' its value is determined the value of + the BUILD option. -TARGET_CPU=AMD64|IA64 +TARGET_CPU=X64|IA64 (VC++ only.) Set this variable to build for x86_64 systems. If unset, x86 build is performed. @@ -868,10 +775,40 @@ you to have two static debug builds, one with wxUSE_SOCKETS=0 and one with socke enabled (without CFG, both of them would be put into same directory and there would be conflicts between the files). -General Notes -================================================================= - -- Debugging: under Windows 95, debugging output isn't output in - the same way that it is under NT or Windows 3.1. - Please see DebugView available from http://www.sysinternals.com. +Building Applications Using wxWidgets +===================================== + +NB: The makefiles and project files provided with wxWidgets samples show which + flags should be used when building applications using wxWidgets so in case + of a problem, e.g. if the instructions here are out of date, you can always + simply copy a makefile or project file from samples\minimal or some other + sample and adapt it to your application. + +Independently of the compiler and make/IDE you are using you must do the +following to use wxWidgets: + +* Add $WXWIN/include to the + - compiler + - resource compiler + include paths. +* Define the following symbols for the preprocessor: + - __WXMSW__ to ensure you use the correct wxWidgets port. + - _UNICODE unless you want to use deprecated ANSI build of wxWidgets. + - NDEBUG if you want to build in release mode, i.e. disable asserts. + - WXUSINGDLL if you are using DLL build of wxWidgets. +* Add $WXWIN/lib/prefix_lib-or-dll to the libraries path. The prefix depends + on the compiler, by default it is "vc" for MSVC, "gcc" for g++ and so on. +* Add the list of libraries to link with to the linker input. The exact list + depends on which libraries you use and whether you built wxWidgets in + monolithic or default multlib mode and basically should include all the + relevant libraries from the directory above, e.g. "wxmsw29ud_core.lib + wxbase29ud.lib wxtiffd.lib wxjpegd.lib wxpngd.lib wxzlibd.lib wxregexud.lib + wxexpatd.lib" for a debug build of an application using the core library only + (all wxWidgets applications use the base library). + + +Microsoft Visual C++ users can simplify the linker setup by prepending the +directory $WXWIN/msvc to the include path (it must come before $WXWIN/include +directory!) and omitting the last step: the required libraries will be linked +in automatically using the "#pragma comment(lib)" feature of this compiler.