X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/fd9f42b6a94f9d68c66cf363093442b12cd4e953..530710322731ae53c2de235c04e529554cb70975:/docs/msw/install.txt diff --git a/docs/msw/install.txt b/docs/msw/install.txt index b7908f8fe7..ac42c1c935 100644 --- a/docs/msw/install.txt +++ b/docs/msw/install.txt @@ -21,7 +21,7 @@ Please report bugs using the SourceForge bug tracker: Unarchiving ------------ +=========== A setup program is provided (setup.exe) to automatically copy files to a directory on your hard disk. Do not install into a @@ -59,7 +59,7 @@ Other add-on packages are available from the wxWindows Web site, such as: General installation notes --------------------------- +========================== If installing from the CVS server, copy include/wx/msw/setup0.h to include/wx/msw/setup.h and edit the resulting file to choose @@ -79,14 +79,13 @@ Where compiled files are stored ------------------------------- After succesful compilation you'll find the libraries in a subdirectory -of lib directory named after the compiler, toolkit name and DLL and Unicode -settings. A couple of examples: +of lib directory named after the compiler and DLL/staitc settings. +A couple of examples: - lib\vc_msw VC++ compiled static libraries - lib\vc_mswdll VC++ DLLs - lib\bcc_mswud Static libraries for Borland C++, - Unicode debug build - lib\wat_mswunivdll Watcom C++ DLLs of wxUniversal port + lib\vc_lib VC++ compiled static libraries + lib\vc_dll VC++ DLLs + lib\bcc_lib Static libraries for Borland C++ + lib\wat_dll Watcom C++ DLLs Names of compiled wxWindows libraries follow this scheme: libraries that don't depend on GUI components begin with "wxbase" followed by version number and @@ -103,7 +102,23 @@ libraries (release versions on left, debug on right side): wxmsw25_html.lib wxmsw25d_html.lib wxmsw25_adv.lib wxmsw25d_adv.lib -These directories also contain wx/setup.h header. +Their Unicode debug counterparts in wxUniversal build would be + + wxbase25ud.lib + wxbase25ud_net.lib + wxbase25ud_xml.lib (notice these libs are same for wxUniv and wxMSW) + wxmswuniv25ud_core.lib + wxmswuniv25ud_html.lib + wxmswuniv25ud_adv.lib + +These directories also contain subdirectory with wx/setup.h header. This +subdirectory is named after port, Unicode, wxUniv and debug settings and +you must add it to include paths when compiling your application. Some +examples: + + lib\vc_lib\msw\wx\setup.h VC++ static, wxMSW + lib\vc_lib\mswud\wx\setup.h VC++ static, wxMSW, Unicode, debug + lib\vc_lib\mswunivd\wx\setup.h VC++ static, wxUniversal, debug Below are compiler specific notes followed by customizing instructions that apply to all compilers (search for "Configuring the build"). @@ -129,10 +144,14 @@ Using project files (VC++ 6 and later): 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 for the wxWindows - project, and compile. Alternatively, use Batch Build to build more than - one configuration. It will also produce similar variations on jpeg.lib, + 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 (i.e. html part), you don't have + to compile it. It will also produce similar variations on jpeg.lib, png.lib, tiff.lib, zlib.lib, and regex.lib. + If you want to build DLLs, you have to either build them one by one in + proper order (jpeg, png, tiff, zlib, regex, expat, base, core, the rest + in any order) or to use wx_dll.dsw workspace which has correct dependencies. 3. Open a sample project file, choose a configuration such as Win32 Debug using Build | Set Active Configuration..., and compile. The project files don't use precompiled headers, to save disk @@ -144,18 +163,14 @@ Using project files (VC++ 6 and later): Using makefiles: -1. If you do NOT have the TIFF or JPEG source code, please remove - the tiff and jpeg targets from the 'all' target in - src\msw\makefile.vc. Also ensure the settings in - include\wx\msw\setup.h specify not to use JPEG or TIFF. -2. Change directory to build\msw. Type: +1. Change directory to build\msw. Type: 'nmake -f makefile.vc' to make the wxWindows core library as release DLL. See "Configuring the build" for instruction how to build debug or static libraries. -3. Change directory to samples and type 'nmake -f makefile.vc' +2. Change directory to samples and type 'nmake -f makefile.vc' to make all the samples. You can also make them individually. Makefile notes: @@ -213,7 +228,7 @@ Compiling using the makefiles (updated 24 Sept 02): 1. Change directory to build\msw. Type 'make -f makefile.bcc' to make the wxWindows core library. Ignore the compiler warnings. - This produces a couple of librarie in the lib\bcc_mswdll directory. + This produces a couple of libraries in the lib\bcc_mswdll directory. 2. Change directory to a sample or demo such as samples\minimal, and type 'make -f makefile.bcc'. This produces a windows exe file - by default @@ -233,35 +248,12 @@ recompile wxWindows. The same applies if compiling using the IDE. Note (3): If you wish debug messages to be sent to the console in debug mode, edit makefile.bcc and change /aa to /Tpe in link commands. -Compiling using the IDE files: [Borland C++ 5.0, not Cbuilder] - -1. Load src\bc32.ide from the file bc32.zip at - http://biolpc22.york.ac.uk/pub/ports/bcc32/wxwin21/ and select Release settings -2. Go to Options|Project... and specify the correct BC++ include and lib path for - your file structure. -3. Press F9 to compile the wxWindows library. -4. Load samples\bc32.ide. -5. Go to Options|Project... and specify the correct BC++ include and lib path for - your file structure. -6. Press F9 to compile the samples (build each node separately if - you prefer, by right clicking and choose Build Node). -7. Run each sample: you may need to run from each sample's directory - since some (notably the wxHTML samples) look for files - relative to the working directory. - -Note (1): the samples project file contains a selection of -samples, and not all samples. The remaining samples can be made -with the makefiles. See also the demos hierarchy which doesn't -have any BC++ project files yet. +Compiling using the IDE files for Borland C++ 5.0: not supported - please +use version 2.4.1 (using the make utility in commandline mode works fine_ -Note (2): to make the png, zlib, jpeg and tiff libraries (needed for -some samples) you need to compile them with bc32.ide. +Compiling using CBuilder (v1-v6): not supported - please +use version 2.4.1 (using the make utility in commandline mode works fine_ -Note (3): the debug version of the wxWindows library is about 40 MB, and the -release version is around 5 MB. - -See also the file docs/tech/tn0007.txt for further instructions and details -of how to create your own project files. ** REMEMBER ** @@ -276,21 +268,6 @@ the following preprocessor directive: more details) -Borland C++Builder IDE compilation ----------------------------------- - -1. Build the wxWindows libraries using the Borland make utility as - specified in the section called "Borland C++ 5.0 compilation" - above. (C++ Builder includes a stand-alone C++ compiler. For example, - C++ Builder 4.0 comes with C++ 5.4.) - -2. You can use the process_sample_bcb.bat command which is in - wxwindows\distrib\msw to generate a .mak or .bpr file for most of the - samples [mak for Cbuilder 1-6; v4 and after will convert this to bpr]. - Execute this in the sampledirectory, passing the name of the cpp files - on the command line. For more details, see the instructions in - docs/tech/tn0004.htm or http://biolpc22.york.ac.uk/wx/bc/ide.html. - Borland 16 Bit compilation for Windows 3.1 ------------------------------------------ @@ -302,7 +279,7 @@ Watcom C++ 10.6/11 and OpenWatcom compilation 1. Change directory to build\msw. Type 'wmake -f makefile.wat' to make the wxWindows core library. -2. Change directory to wx\samples\minimal and type 'wmake -f makefile.wat' +2. Change directory to samples\minimal and type 'wmake -f makefile.wat' to make this sample. Repeat for other samples of interest. @@ -436,7 +413,7 @@ All targets have 'clean' targets to allow removal of object files and other intermediate compiler files. Using configure -=============== +--------------- Instead of using the makefiles, you can use the configure system to generate appropriate makefiles, as used on Unix @@ -531,7 +508,7 @@ OLD VERSIONS: Symantec & DigitalMars C++ compilation ------------------------- +-------------------------------------- The DigitalMars compiler is a free succssor to the Symantec compiler and can be downloaded from http://www.digitalmars.com/ @@ -544,7 +521,7 @@ and can be downloaded from http://www.digitalmars.com/ 2. Change directory to build\msw. Type 'make -f makefile.dm' to make the wxWindows core library. -3. Change directory to wx\samples\minimal and type 'make -f makefile.dm' +3. Change directory to samples\minimal and type 'make -f makefile.dm' to make this sample. The mdi and image sample also work; others may give linker erros due to missing libraries @@ -554,25 +531,233 @@ and can be downloaded from http://www.digitalmars.com/ Configuring the build ===================== - CONFIGURING THE BUILD +So far the instructions only explained how to build release DLLs of wxWindows +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. +Changing the settings +--------------------- - To build Unicode versions of the libraries, add UNICODE=1 - to the nmake invocation (default is UNICODE=0). If you want to - be able to use Unicode version on Windows9x, you will need - MSLU (Microsoft Layer for Unicode) runtime DLL and import lib. - The former can be downloaded from Microsoft, the latter is part - of the latest Platform SDK from Microsoft (see msdn.microsoft.com - for details). An alternative implementation of import library can - be downloaded from http://libunicows.sourceforge.net - unlike the - official one, this one works with other compilers and does not - require 300+ MB Platform SDK update. Add MSLU=1 to the nmake - invocation to enable MSLU. +There are two ways to modify the settings: either by passing the values as +arguments when invoking make or by editing build\msw\config.$(compiler) file +where $(compiler) is same extension as the makefile you use has (see below). +The latter is good for setting options that never change in your development +process (e.g. GCC_VERSION or VENDOR). If you want to build several versions of +wxWindows and use them side by side, the former method is better. Settings in +config.* files are shared by all makefiles (samples, contrib, main library), +but if you pass the options as arguments, you must use same arguments you used +for the library when building samples or contrib libraries! +Examples of invoking make in Unicode debug build (other options described +below are set analogically): -General Notes +Visual C++: + > nmake -f makefile.vc BUILD=debug UNICODE=1 + +Borland C++: + > nmake -f makefile.bcc -DBUILD=debug -DUNICODE=1 + (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 + +MinGW using native makefiles: + > mingw32-make -f makefile.gcc BUILD=debug UNICODE=1 + +MinGW using configure or Cygwin: + > ./configure --enable-debug --enable-unicode + (see ./configure --help on details; configure is not covered in this + section) + +Brief explanation of options and possible values is in every +build\msw\config.* file; more detailed description follows. + +Basic options ------------- +BUILD=debug + Builds debug version of the library (default is 'release'). This affects + name of the library ('d' is appended), __WXDEBUG__ is defined and debug + information compiled into object files and the executable. + +SHARED=0 + Build static libraries instead of DLLs. By default, DLLs are build + (SHARED=1). + +UNICODE=1 + To build Unicode versions of the libraries, add UNICODE=1 to make invocation + (default is UNICODE=0). If you want to be able to use Unicode version on + Windows9x, you will need to set MSLU=1 as well. + + This option affect name of the library ('u' is appended) and the directory + where the library and setup.h are store (ditto). + +WXUNIV=1 + Build wxUniversal instead of native wxMSW (see + http://www.wxwindows.org/wxuniv.htm for more information). + +Advanced options +---------------- + +MONOLITHIC=1 + Starting with version 2.5.0, wxWindows has the ability to be built as + several smaller libraries instead of single big one as used to be the case + in 2.4 and older versions. This is called "multilib build" and is the + default behaviour of makefiles. You can still build single library + ("monolithic build") by setting MONOLITHIC variable to 1. + +USE_GUI=0 + Disable building GUI parts of the library, build only wxBase components used + by console applications. Note that if you leave USE_GUI=1 then both wxBase + and GUI libraries are built. If you are building monolithic library, then + you should set wxUSE_GUI to 1 in setup.h. + +USE_OPENGL=1 + Build wxmsw25_gl.lib library with OpenGL integration class wxGLCanvas. + You must also modify your setup.h to #define wxUSE_GLCANVAS 1. Note that + OpenGL library is always built as additional library, even in monolithic + build! + +USE_ODBC=1 + Build two additional libraries in multilib mode, one with database + classes and one with wxGrid database support. You must + #define wxUSE_ODBC 1 in setup.h + +USE_HTML=0 + Do not build wxHTML library. If MONOLITHIC=1, then you must also + #define wxUSE_HTML 1 in setup.h. + +RUNTIME_LIBS=static + Links static version of C and C++ runtime libraries into the executable, so + that the program does not depend on DLLs provided with the compiler (e.g. + Visual C++'s msvcrt.dll or Borland's cc3250mt.dll). + Caution: Do not use static runtime libraries when building DLL (SHARED=1)! + +MSLU=1 + Enables MSLU (Microsoft Layer for Unicode). This setting makes sense only if + used together with UNICODE=1. If you want to be able to use Unicode version + on Windows9x, you will need MSLU (Microsoft Layer for Unicode) runtime DLL + and import lib. The former can be downloaded from Microsoft, the latter is + part of the latest Platform SDK from Microsoft (see msdn.microsoft.com for + details). An alternative implementation of import library can be downloaded + from http://libunicows.sourceforge.net - unlike the official one, this one + works with other compilers and does not require 300+ MB Platform SDK update. + +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_INFO=0 +DEBUG_INFO=1 + Same as DEBUG_FLAG in behaviour, this option affects whether debugging + information is included in the executable or not. + +VENDOR= + Set this to a short string identifying your company if you are planning to + distribute wxWindows DLLs with your application. Default value is 'custom'. + This string is included as part of DLL name. wxWindows DLLs contain compiler + name, version information and vendor name in them. For example + wxmsw250_core_bcc_custom.dll is one of DLLs build using Borland C++ with + default settings. If you set VENDOR=mycorp, the name will change to + wxmsw250_core_bcc_mycorp.dll. + +CFG= + Sets configuration name so that you can have multiple wxWindows build with + different setup.h settings coexisting in same tree. See "Object and library + directories" below for more information. + +Compiler specific options +------------------------- + +* MinGW + +If you are using gcc-2.95 instead of gcc3, you must set GCC_VERSION to +2.95. In build\msw\config.gcc, change +> GCC_VERSION = 3 +to +> GCC_VERSION = 2.95 + +* Visual C++ + +DEBUG_RUNTIME_LIBS=0 +DEBUG_RUNTIME_LIBS=1 + If set to 1, msvcrtd.dll is used, if to 0, msvcrt.dll is used. By default + msvcrtd.dll is used only if the executable contains debug info and + msvcrt.dll if it doesn't. It is sometimes desirable to build with debug info + and still link against msvcrt.dll (e.g. when you want to ship the app to + customers and still have usable .pdb files with debug information) and this + setting makes it possible. + +Fine-tuning the compiler +------------------------ + +All makefiles have variables that you can use to specify additional options +passed to the compiler or linker. You won't need this in most cases, but if you +do, simply add desired flags to CFLAGS (for C compiler), CXXFLAGS (for C++ +compiler), CPPFLAGS (for both C and C++ compiler) and LDFLAGS (the linker). + +Object and library directories +------------------------------ + +All object files produced during library build are stored in a directory under +build\msw. It's name is derived from build settings and CFG variable and from +compiler name. Examples of directory names: + + build\msw\bcc_msw SHARED=0 + build\msw\bcc_mswdll SHARED=1 + build\msw\bcc_mswunivd SHARED=0, WXUNIV=1, BUILD=debug + build\msw\vc_mswunivd ditto, with Visual C++ + +Libraries and DLLs are copied into subdirectory of lib directory with +name derived from compiler and static/DLL setting and setup.h into directory +with name that contains other settings: + + lib\bcc_msw + lib\bcc_lib\msw\wx\setup.h + lib\bcc_dll + lib\bcc_dll\msw\wx\setup.h + lib\bcc_lib + lib\bcc_lib\mswunivd\wx\setup.h + lib\vc_lib + lib\vc_lib\mswunivd\wx\setup.h + +Each lib\ subdirectory has wx subdirectory with setup.h as seen above. +This file is copied there from include\wx\msw\setup.h (and if it doesn't exist, +from include\wx\msw\setup0.h) and this is the copy of setup.h that is used by +all samples and should be used by your apps as well. If you are doing changes +to setup.h, you should do them in this file, _not_ in include\wx\msw\setup.h. + +If you set CFG to something, the value is appended to directory names. E.g. +for CFG=MyBuild, you'll have object files in + + build\msw\bcc_mswMyBuild + build\msw\bcc_mswdllMyBuild + etc. + +and libraries in + + lib\bcc_libMyBuild + lib\bcc_dllMyBuild + etc. + +By now it is clear for CFG is for: builds with different CFG settings don't +share any files and they use different setup.h files. This allows you to e.g. +have two static debug builds, one with wxUSE_SOCKETS=0 and one with sockets +enabled (without CFG, both of them would be put into same directory and there +would be conflict 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 (bin/dbgview.exe in the distribution), also