update Watcom section; minor additions to the other ones

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@18865 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/msw/install.txt

@@ -1,14 +1,11 @@
-
 Installing wxWindows 2.5.0
 --------------------------
 
-This is wxWindows 2.5.0 for Microsoft Windows 9x/ME, Windows NT,
+This is wxWindows 2.5.0 for Microsoft Windows 9x/ME, Windows NT, Windows 2000
-Windows 2000 and Windows XP. This is an unstable development release.
+and Windows XP. This is an unstable development release. Note that unstable in
+this context doesn't mean that it crashes a lot, just that the library API may
+change in backwards incompatible way during the 2.5 branch life time.
 
-Please note that the library naming conventions for VC++
-compilation have changed after 2.3.1. This means that
-you will need to change your application project files. See the
-relevant section below for details.
 
 IMPORTANT NOTE: If you experience problems installing, please
 re-read this instructions and other related files (changes.txt,
@@ -22,6 +19,7 @@ Please report bugs using the SourceForge bug tracker:
 
   http://sourceforge.net/bugs/?group_id=9863
 
+
 Unarchiving
 -----------
 
@@ -59,6 +57,7 @@ Other add-on packages are available from the wxWindows Web site, such as:
 - tex2rtf3.zip. Tex2RTF: create Windows Help, HTML, and Word RTF files from
   the same document source.
 
+
 General installation notes
 --------------------------
 
@@ -70,14 +69,17 @@ 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
 the features you would like to compile wxWindows with[out].
 
+
 Compilation
------------
+===========
 
 The following sections explain how to compile wxWindows with each supported
-compiler.
+compiler. Search for one of Microsoft/Borland/Watcom/Symantec/Metrowerks/
+Cygwin/Mingw32 to quickly locate the instructions for your compiler.
 
-Visual C++ compilation
+
----------------------------
+Microsoft Visual C++ compilation
+--------------------------------
 
 Please note that the VC++ 6.0 project files will work for VC++ .NET also, but
 you must open the .dsp files and not the .dsw files and in this case you will
@@ -216,6 +218,7 @@ applications in the VC++ IDE" (technical note docs/tech/tn0010.htm in the
 wxWindows distribution). You can also copy .dsp and .dsw
 files from an existing wxWindows sample and adapt them.
 
+
 Visual C++ 1.5 compilation (16-bit)
 -----------------------------------
 
@@ -235,6 +238,7 @@ versions of the library and samples.
 Use the 'clean' target to clean all objects, libraries and
 executables.
 
+
 Borland C++ 4.5/5.0/5.5 compilation
 -------------------------------
 
@@ -377,8 +381,9 @@ the following preprocessor directive:
 (check the samples -- e.g., \wx2\samples\minimal\minimal.cpp -- for
 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++ 4.5/5.0 compilation"
@@ -393,25 +398,47 @@ Borland C++Builder IDE compilation
    samples [mak for Cbuilder 1-3; bpr for v4]. Execute this in the sample
    directory, passing the name of the cpp files on the command line.
 
-Watcom C++ 10.6/11 compilation
+
----------------------------
+Watcom C++ 10.6/11 and OpenWatcom compilation
+---------------------------------------------
 
 1. Make sure your WXWIN variable is set, and uses the DOS short
    name form.
-2. Change directory to wx\src\msw. Type 'wmake -f makefile.wat all' to
+2. Change directory to wx\src\msw. Type 'wmake -f makefile.wat' to
    make the wxWindows core library.
-3. Change directory to wx\samples\minimal and type 'wmake -f makefile.wat all'
+3. Change directory to wx\samples\minimal and type 'wmake -f makefile.wat'
    to make this sample. Repeat for other samples of interest.
 
-Note (1): makewat.env uses the odbc32.lib supplied in wxWindows' lib\watcom
+
-directory. See the notes in that directory.
+There are several makefile variables which may be modified:
-Note (2): if variant.cpp is compiled with date/time class
+
-options, the linker gives up. So the date/time option is switched
+- FINAL may be set to 1 (e.g. 'wmake -f makefile.wat FINAL=1') to build
-off for Watcom C++. Also, wxAutomationObject is not compiled with
+  the release version of the library, i.e. without debug info and with
-Watcom C++.
+  optimizations enabled
-Note (3): if Watcom can't read the precompiled header when
+
-building a sample, try deleting src\msw\watcom.pch and
+- WATCOM_SUFFIX is appended to the names of all libraries produced by the
-compiling the sample again.
+  makefile -- this allows to use several compilers in the same wxWindows
+  source tree. If you only use Watcom compiler, set WATCOM_SUFFIX to nothing.
+
+- OUTPUTDIR may be set to the name of the directory where you want all the
+  object files to be generated (the library files are always created in
+  %WXWIN\lib). You may set it to nothing to create them in the same directory
+  as the sourcse, however using a separate directory is preferable if you use
+  several different compilers. If you change OUTPUTDIR, make sure that it is
+  either empty or has a trailing backslash!
+
+
+Note (1): if your installation of Watcom doesn't have odbc32.lib file and
+          you need it (i.e. you have wxUSE_ODBC=1), you can use the file
+          from lib\watcom directory. See the notes in that directory.
+
+Note (2): if variant.cpp is compiled with date/time class options, the linker
+          gives up. So the date/time option is switched off for Watcom C++.
+          Also, wxAutomationObject is not compiled with Watcom C++ 10.
+
+Note (3): if Watcom can't read the precompiled header when building a sample,
+          try deleting src\msw\watcom.pch and compiling the sample again.
+
 
 Metrowerks CodeWarrior compilation
 ----------------------------------
@@ -468,8 +495,9 @@ Metrowerks CodeWarrior compilation
          minimal.rc and minimal.cpp and adding the files griddemo.rc and
          griddemo.cpp.  Build and run....
 
+
 Cygwin/MinGW compilation
-----------------------------------
+------------------------
 
 wxWindows 2 supports Cygwin (formerly GnuWin32) betas and
 releases, and MinGW. Cygwin can be downloaded from:
@@ -481,7 +509,11 @@ and MinGW from:
     http://www.mingw.org/
 
 Both Cygwin and MinGW can be used with the same makefiles, and both can be
-used with configure.
+used with configure. However the (strongly) preferred way to build wxWindows
+is using configure with Cygwin and using the makefiles with MinGW as these
+configurations are test much more often than the remaining two and so are much
+more likely to work out of the box.
+
 
 NOTE: some notes specific to old Cygwin (< 1.1.x)
       and MinGW (< 1.0) are at the end of this section
@@ -687,6 +719,7 @@ OLD VERSIONS:
 - If using GnuWin32 b18, you will need to copy windres.exe
   from e.g. the MinGW distribution, to a directory in your path.
 
+
 Symantec C++ compilation
 ------------------------
 
@@ -705,6 +738,7 @@ Some functionality is missing using this compiler (see makefile).
 Add -D__WIN95__ if your SC++ has Windows 95 support, and ignore
 Step (2). 16-bit compilation is left as an exercise for the user!
 
+
 Salford C++ compilation
 -----------------------
 
@@ -724,6 +758,7 @@ the debugging version of the library is 90MB, with samples coming in
 at 40MB :-) However, wxWindows at least makes a good test suite for
 improving the compiler.
 
+
 TWIN32 and gcc on Linux
 -----------------------
 
@@ -739,6 +774,7 @@ described above. Not all sample makefiles are supplied yet.
 For some reason, I found I had to copy TWIN32's Windows resource
 compiler (rc) to the current working directory for it to be found.
 
+
 General Notes
 -------------