Index: trunk/README.OS2
===================================================================
--- trunk/README.OS2	(revision 624)
+++ trunk/README.OS2	(revision 740)
@@ -1,3 +1,3 @@
-This is Qt version 4.5.1 GA for OS/2 and eCS.
+This is Qt version 4.6.2 for OS/2 and eCS.
 
 This document contains a brief information on the OS/2 version of the Qt
@@ -12,4 +12,12 @@
 please see the CHANGES.OS2 file included in this distribution.
 
+Please note that this version is binary incompatible with previous versions of
+Qt 4 for OS/2! This is not a behavior of the original Qt library (where versions
+with the same major number are usually binary compatible), but it is due to the
+fact that we continue to add missing features to the OS/2 version ot Qt and this
+cannot be done witout breaking the binary compatibility. On practice, this means
+that you need to recompile your applications with the new version of the Qt
+library in order to make them work with it.
+
 
 
@@ -21,32 +29,37 @@
   - One of the OS/2 Warp 4, OS/2 Warp 4.5 or eComStation operating systems.
 
-  - InnoTek GCC compiler version 3.3.5 CSD3 or 4.4.2 (recommended).
-    You can download the GCC 4.4.2 compiler using the following link:
-
-      http://download.smedley.info/gcc-4.4.2-os2-20091205.zip
-
-    GCC 4.4.2 requires newer binutils available at:
-
-      http://download.smedley.info/binutils-2.19.1-os2-20090427.zip
-
-    Note that in order to use the above version of GCC, you will also need
-    to install the previous 3.x version (e.g. 3.3.5 CSD3) available at:
-
-      ftp://ftp.netlabs.org/pub/gcc/GCC-3.3.5-csd3.zip
-
-  - Patched OpenWatcom linker which you can download from here:
-
-      ftp://ftp.netlabs.org/pub/gcc/wl-hll-r1.zip
-
-    Note that if you use IBM ILINK (no matter what version), you will
-    not be able to build the debug version of the library due to
-    bugs/limitations of ILINK.
-
-  - GNU Make 3.81beta1 or above (not tested) available at:
-
-      http://unix.os2site.com/pub/binary/make/make-3_81beta1-bin-static.zip
+  - GCC compiler version 4.4.2 for OS/2, patched OpenWatcom linker and
+    GNU Make 3.81beta1 or above. The GCC compiler must be set up to use the
+    OpenWatcom linker for linking.
+
+    If you do not have a working GCC environment with the above requirements, it
+    is recommended to download a ready-to-use GCC 4.2.2 distribution from here:
+
+      ftp://ftp.netlabs.org/pub/qt4/gcc-4_4_2-complete-20091205.zip
+
+    This distribution includes all tools necessary to compile and build the Qt
+    library from the source code. Just follow the installation instructions
+    contained in the README file inside this ZIP archive to set up the GCC
+    environment.
+
+    Please note that starting from Qt 4.6.2, support for GCC 3.3.5 and earlier
+    versions of the compiler has been dropped and the Qt library will most
+    likely not build if you use one of these compilers. Later versions prior to
+    GCC 4.4.2 may work but they are not tested and not supported.
+
+There is also a set of optional tools which are necessary to enable the selected
+features of the Qt library. If these tools are missing, the Qt configuration
+script (discussed in section "COMPILING QT" below) will automatically disable
+the corresponding feature:
+
+  - LxLite 1.3.3 or above (not tested) to enable the compression of Qt DLLs and
+    application executables (which saves hard disk space and application startup
+    time). If you use a recent version of eComStation (e.g. 2.0 rc6) you will
+    already have LxLite installed. Otherwise, you may take it from here:
+
+      http://www.os2site.com/sw/util/archiver/lxlt133.zip
 
   - eCUPS 1.3.11 or later to support printing in Qt. The eCUPS WPI is available
-    at:
+    from:
 
       ftp://ftp.netlabs.org/incoming/eCUPS003.wpi   or
@@ -57,67 +70,54 @@
       http://web.os2power.com/download/lib/pthread-20100217-os2.zip
 
-  - LxLite 1.3.3 or above (not tested) if you want Qt DLLs and application
-    executables to be compressed (to save hard disk space and load time). If
-    you have a recent eComStation installation (e.g. 2.0 rc6) you will already
-    have LxLite installed. Otherwise, you may take it from here:
-
-      http://www.os2site.com/sw/util/archiver/lxlt133.zip
-
 
 
 SETTING UP THE ENVIRONMENT
 
-After unpacking the GCC archive, you will have to set up the compiler
-environment by invoking gccenv.cmd from the "bin" subdirectory with the correct
-arguments (type gccenv.cmd -? for help). For the OpenWatcom linker, specify
-WLINK as the second argument.
-
-Please note that setting up the GCC 4.x environment requires some additional
-steps. Please look through the README files contained within the OS/2
-distribution.
-
-You will also need to perform the following steps:
-
-  - Make sure the selected linker, the make utility and LxLite executable are
-    in PATH.
+First of all, make sure that your GCC environment is set up and meets the
+specified requirements. To perform a quick check, you may run the following
+command:
+
+  gcc --version && make --version && wl /version
+
+If the setup is done properly, it will print the versions of the key tools
+to the console.
+
+The next step is to set up the Qt environment. If you installed the Qt
+development libraries from the WPI archive (refer to section "USING OFFICIAL
+BINARY QT ARCHIVES" below for more details about existing WPI archives), you
+will only need to run the supplied "QtEnv.cmd" script which will do all the
+setup job for you. The script is located in the directory where you installed
+the developmnent libraries (or in the WPS folder created by the WPI installer).
+If you use this script, you may skip the rest of this section and proceed to the
+next one.
+
+If you use the full source code ZIP distribution of the Qt library or work
+directly with the Qt SVN tree, you will need to set up the environment yourself
+by performing the following steps:
+
+  - Add the "bin" subdirectory of the directory where you unpacked the Qt4
+    source tree to PATH and BEGINLIBPATH, like this:
+
+      set PATH=D:\Coding\Qt4\bin;%PATH%
+      set BEGINLIBPATH=D:\Coding\Qt4\bin;%BEGINLIBPATH%
+
+  - Add the system DLLs to the GCC library path with the following command:
+
+      set LIBRARY_PATH=C:\OS2\DLL;C:\MPTN\DLL;%LIBRARY_PATH%
+
+    where C: is your boot drive.
 
   - Make sure CMD.EXE is your command line processor (the generated makefiles
     will rely on its 'copy', 'if' and other commands). If you have a Unix shell
     (SH.EXE) in your environment, you may need to force GNU make to use CMD.EXE
-    by doing 'set MAKESHELL=C:\OS2\CMD.EXE' where C: is your boot drive.
-
-  - Do set LIBRARY_PATH=C:\OS2\DLL;C:\MPTN\DLL where C: is your boot drive.
-
-  - Make sure that there are no traces of any other Watcom or OpenWatcom
-    installation in the environment where you build Qt as it will most likely
-    interfere with the patched OpenWatcom linker we use. This basically means
-    removing all *WATCOM* environment variables and removing references to those
-    Watcom installations from PATH.
-
-  - Add the "bin" subdirectory of the directory where you unpacked the Qt4
-    source tree to PATH and BEGINLIBPATH using its full path, e.g.:
-
-      set PATH=D:\Coding\Qt4\bin;%PATH%
-      set BEGINLIBPATH=D:\Coding\Qt4\bin;%BEGINLIBPATH%
-
-  - Install the eCUPS WPI archive to enable printing support. If this WPI is
-    installed, the Qt build system will pick up all necessary libraries
-    automatically. Otherwise, you will need to use the following environment
-    variables to tell it where to look for CUPS:
-
-      set CUPS_INCLUDEPATH=X:\Path\to\CUPS\include
-      set CUPS_LIBS=X:\Path\to\CUPS\lib\libcups.a
-
-    Note that if the eCUPS WPI is not installed and these variables are not set,
-    printing support will be completely disabled in the resulting Qt build.
-
-    You will also need to make sure that pthread.lib is placed somewhere in your
-    system library path so that the compiler can find it.
-
-Note that the QTDIR environment variable used by previous Qt versions is not
-used by Qt4 anymore (except two rare cases that do not affect the OS/2 platform
-anyway and are probably leftovers after the migration of the qmake feature
-specifications to Qt4). Therefore, there is no need to set this variable
-explicitly. See also a note below about hard-coded paths to the source tree.
+    by executing the followingn command:
+
+       set MAKESHELL=C:\OS2\CMD.EXE
+
+    where C: is your boot drive.
+
+Note that the QTDIR environment variable used in previous Qt versions is not
+used in Qt4 anymore. Therefore, there is no need to set this variable
+explicitly.
 
 There is also no need to set the QMAKESPEC variable explicitly. If it is absent,
@@ -126,11 +126,39 @@
 one supported at the present time.
 
+NOTE:
+
+    It is especially important to make sure that there are no traces of any
+    other Watcom or OpenWatcom installation in the environment where you build
+    Qt as it will interfere with the patched OpenWatcom linker we use. This
+    basically means removing all environment variables containing "WATCOM" in
+    their names and also removing references to all those Watcom installations
+    from PATH.
+
+
+
+SETTING UP OPTIONAL TOOLS
+
+The following list describes the steps necessary to set up the optional tools
+that the Qt library depends on:
+
+  - Install the eCUPS WPI archive to enable printing support. If this WPI is
+    installed, the Qt build system will pick up all necessary libraries
+    automatically. Otherwise (e.g. if you use a ZIP or build eCUPS yourself),
+    you will need to use the following environment variables to tell it where to
+    look for CUPS:
+
+      set CUPS_INCLUDEPATH=X:\Path\to\CUPS\include
+      set CUPS_LIBS=X:\Path\to\CUPS\lib\libcups.a
+
+    You will also need to make sure that pthread.lib is placed somewhere in your
+    system library path so that the compiler can find it.
+
 
 
 COMPILING QT
 
-You should skip this section if you downloaded and installed a binary
-distribution of the Qt library for developers (qt-dev-X_Y_Z.wpi) and proceed
-directly to section USING OFFICIAL BINARY QT PACKAGES below.
+You should skip this section if you installed the Qt development libraries using
+the WPI archive (that already contains compiled release versions of the
+libraries) and proceed directly to the next section.
 
 When the environment is set up, go to the directory where you unpacked the
@@ -139,7 +167,6 @@
   configure.cmd
 
-This will set up the library (by creating necessary configuration and include
-files and a bunch of Makefiles for variuos components) and build the qmake
-utility.
+This will set up the Qt library (by creating necessary configuration and include
+files and a bunch of Makefiles for variuos components) and build the qmake tool.
 
 The next step is to type:
@@ -147,5 +174,5 @@
   make
 
-This will compile and link the library. Note that by default both the release
+This will compile and link the Qt library. Note that by default both the release
 and the debug version of the library are built (please be patient, it may take
 quite some time depending on your hardware). The release and debug libraries can
@@ -154,12 +181,12 @@
 separate directories for object files.
 
-To save time, you may also build the release and the debug versions of the
-library separately by typing 'make release' or 'make debug' accordingly
-instead of just 'make'.
-
-Once the library is successfully built, you may try to compile the demos
-and examples by visiting the individual example subdirectories in the source
-tree and typing 'qmake' followed by one of 'make', 'make release' or
-'make debug' in that subdirectory.
+To save time, you may build the release and the debug versions of the Qt library
+separately by typing 'make release' or 'make debug' accordingly instead of just
+'make'.
+
+Once the library is successfully built, you may try to compile the demos and
+examples by visiting the individual example subdirectories in the source tree
+and typing 'qmake' followed by one of 'make', 'make release' or 'make debug'
+in that subdirectory.
 
 NOTE:
@@ -199,66 +226,60 @@
      change to Qt configuration options may make your build binary incompatible
      with another build. And even if you convince the user to isolate different
-     DLLs (using BEGINLIBPATH and alike) it will create another major problem:
-     two different Qt applications will load two different Qt builds into memory
-     which will double resource usage; having three different builds will
-     tripple it and so on -- what a vaste of system resources!
+     DLLs (using LIBPATHSTRICT and BEGINLIBPATH) it will create another major
+     problem: two different Qt applications will load two different copies of Qt
+     into memory which will create an unnecessary overhead by doubling the
+     amount of used system resources.
 
      In order to nicely solve this problem, netlabs.org provides the official
-     binary builds of the Qt library distributed as WPI packages which are
+     binary builds of the Qt library distributed as WPI archives which are
      described in the next section.
 
 
 
-USING OFFICIAL BINARY QT PACKAGES
+USING OFFICIAL BINARY QT ARCHIVES
 
 For your convenience, netlabs.org provides the following binary distributions
-of the Qt library (where X_Y_Z is the Qt version number):
-
-  qt-lib-X_Y_Z.wpi   - Runtime DLLs and binaries ("lib" package)
-  qt-dev-X_Y_Z.wpi   - Development libraries, tools and headers ("dev" package)
-
-These packages are called the official binary packages of the Qt library for
-OS/2. An official binary distribution is the most complete Qt build available
-that enables all Qt library features and includes all standard Qt plugins that
-were implemented for OS/2.
-
-The "lib" package contains the release versions of DLLs (and may contain a few
+of the Qt library (where X_Y_Z is the Qt version number) distributed as WPI
+archives:
+
+  qt-lib-X_Y_Z.wpi   - Runtime DLLs and binaries ("lib" archive)
+  qt-dev-X_Y_Z.wpi   - Development libraries, tools and headers ("dev" archive)
+
+These archives are called the official binary archives of the Qt library for
+OS/2. An official binary archive contains the most complete Qt build that
+enables all features of the Qt library and includes all standard Qt plugins
+implemented for the OS/2 platform at the time of the release.
+
+The "lib" archive contains the release versions of DLLs (and may contain a few
 helper binaries) necessary to run applications created using the Qt framework.
-This package is usually installed by end users together with the Qt applications
+This package is usually installed by end users together with Qt applications
 they want to use.
 
-The "dev" package contains pre-built release versions of import libraries and
+The "dev" archive contains pre-built release versions of import libraries and
 a complete set of C++ include headers of the Qt framework. This package is used
 by developers and porters of Qt applications to build release versions of the
-applications for OS/2 that are binary compatibie with the "lib" package
-described above.
-
-Using the "dev" package requires the same environment as the one necessary for
-building Qt and described in section SETTING UP THE ENVIRONMET above with the
-exception that the "bin" subdirectory of the directory where you installed the
-"dev" package needs to be added to PATH instead of the "bin" subdirectory of
-the Qt4 source tree.
-
-The process of compiling Qt applications using the "dev" package is basically
-the same as with the hand made-build of Qt. Note, however, that if you are
-developing or porting a Qt application, it is still recommended that you build
-the debug version of the Qt library yourself and use it in your daily work since
-it will give you much more feedback than the stripped down release version
-contained in the "dev" package. The "dev" package, as said above, is intended
-for making the final release build of the application for subsequent
-distribution together with the official "lib" package.
-
-Besides the "lib" and the "dev" packages, the following official packages exist
+applications that are binary compatibie with the Qt runtime provided by the
+official "lib" archive described above. Using the "dev" package requires the
+same environment as described in section "SETTING UP THE ENVIRONMET" above.
+
+Please note again that the "dev" archive is intended to make a final release
+build of the Qt application which you do when you decide to ship a new version
+to the end users -- makes sure that the deployed application will share the same
+Qt runtime with other Qt applications. However, for daily work it is highly
+recommended that you build the debug version of the Qt library yourself (using
+the full source code ZIP archive or directly from SVN) as described in section
+"COMPILING QT").
+
+Besides the "lib" and the "dev" archives, the following official archives exist
 that you may also find useful:
 
   qt-examples-X_Y_Z.wpi  - Demo and example sources ("examples")
 
-The "examples" package contains the demo and example applications shipped with
-Qt along with the source code. They serve as a good demonstration of the Qt
-library features and it is recommended to look at them.
-
-Please note that this package does not contain all Qt demos and examples
-available since not all features have been implemented in the OS/2 version of
-Qt yet.
+The "examples" archive contains the source code and compiled binaries of the
+demo and example applications shipped with Qt. They serve as a good
+demonstration of the Qt library features and it is recommended to look at them.
+The binaries are compiled using the official "lib" archive. Please note that
+some demos and examples may miss from the arcvhice since not all features have
+been implemented in the OS/2 version of Qt yet.
 
 NOTE:
@@ -269,6 +290,6 @@
      contains or to "anonymous" if USER is not set). Please note that you must
      NOT set vendor to "netlabs.org" when creating your own builds of the Qt
-     library because it will make it really difficult to identify various
-     distributions and track possible problems with the builds.
+     library because it will make it difficult to identify various distributions
+     and track possible problems with the builds.
 
 
@@ -276,6 +297,5 @@
 QMAKE CONFIG OPTIONS
 
-The following CONFIG options of the qmake utility have a special meaning in
-OS/2:
+The following CONFIG options of the qmake tool have a special meaning in OS/2:
 
   windows           Turns on generation of PM (WINDOWAPI) executables. By
@@ -307,4 +327,27 @@
                     votes against it.
 
+  export_all        Cause the linker to export all public symbols in a generated
+                    DLL. By default (when this option is absent), only the
+                    symbols marked with the __declspec(dllexport) compiler
+                    directive in the source files.
+
+
+
+PRINTING SUPPORT
+
+Starting with version 4.6.2, Qt for OS/2 supports printing through the CUPS
+framework (provided that this support is enabled when building Qt, see the
+respective sections in the beginning of this document). The OS/2 implementation
+of the CUPS framework is provided by the eCUPS package available at
+http://svn.netlabs.org/ecups/.
+
+The Qt Runtime detects the presence of eCUPS in the system on the fly and talks
+to the CUPS daemon directly, bypassing the standard OS/2 printing subsystem.
+This means that in order to print from Qt applications, you don't need to create
+and configure printer objects using the standard OS/2 system printer setup
+procedure -- you only need to install eCUPS and configure your printers in
+there. Please refer to the eCUPS user manual to obtain the detailed instructions
+on how to configure CUPS printers.
+
 
 
@@ -314,4 +357,35 @@
 affect its functionality at runtime. The table below lists these variables and
 their meaning:
+
+  QT_PM_NO_DIVE             If set, Qt will not use DIVE (direct interface video
+                            extensions) for painting widgets even if DIVE (which
+                            provides a much faster painting speed than the
+                            regular GPI approach) is available. Currently, this
+                            is the default setting if the Panorama video driver
+                            is detected because its DIVE implementation contains
+                            a number of bugs.
+
+  QT_PM_DIVE=<mode>         Enables using DIVE for painting widgets. <mode> is
+                            one of:
+
+                              - FB (direct framebuffer access, which is the
+                                fastest mode but causes the curruption of the
+                                screen under the software mouse pointer due to
+                                the limitation of DIVE). If this mode is not
+                                available, BLIT will be used (see below).
+
+                              - FBSWM (the same FB but hides the mouse pointer
+                                before painting which introduces mouse flicker
+                                and may be a bit slower than the raw FB).
+
+                              - BLIT (slower than both FB and FBSWM but prevents
+                                screen corruption under the mouse pointer and
+                                does not produce a mouse pointer flicker
+                                effect).
+
+                            This variable is ignored if QT_PM_NO_DIVE is set. If
+                            neither this nor the QT_PM_NO_DIVE variable is set,
+                            the FBSWM mode is used by default (unless the
+                            current video driver is Panorama, see above).
 
   QT_PM_NO_SOUND_SHARE      If set, Qt will open the audio device in exclusive
@@ -368,19 +442,24 @@
 
 
-PRINTING SUPPORT
-
-Starting with version 4.6.1, Qt for OS/2 supports printing through the CUPS
-framework (provided that this support is enabled when building Qt, see the
-respective sections in the beginning of this document). The OS/2 implementation
-of the CUPS framework is provided by the eCUPS package available at
-http://svn.netlabs.org/ecups/.
-
-The Qt Runtime detects the presence of eCUPS in the system on the fly and talks
-to the CUPS daemon directly, bypassing the standard OS/2 printing subsystem.
-This means that in order to print from Qt applications, you don't need to create
-and configure printer objects using the standard OS/2 system printer setup
-procedure -- you only need to install eCUPS and configure your printers in
-there. Please refer to the eCUPS user manual to obtain the detailed instructions
-on how to configure CUPS printers.
+COMMAND LINE OPTIONS
+
+Any Qt executable recognizes a number of command line options that may change
+the behavior of the Qt application. Here are the most interesting ones:
+
+  -style <name>             Changes the default Qt widget style (theme) to a
+                            style with the given name. The buiil-in styles which
+                            are always available in the official build include:
+                            "windows" (currently, the default on OS/2), "motif",
+                            "cde", "plastique" and "cleanlooks". Other styles
+                            may be also provided by the style plugins.
+
+  -graphicssystem <name>    Changes the graphics system used to paint widgets.
+                            On OS/2, only two values are supported: "native"
+                            (the default one) and "raster". The "native" system
+                            uses DIVE (direct interface video extensions) when
+                            it is available. If DIVE is not available or if it
+                            is disabled (see the QT_PM_NO_DIVE environment
+                            variable description for details), the "raster"
+                            system will be automatically selected as a fallback.
 
 
@@ -388,40 +467,48 @@
 CURRENT LIMITATIONS
 
-  1. configure.cmd is not yet capable of generating individual Makefiles for
-     demos and examples, it only generates the main Makefile that builds the
-     library and the necessary tools. Demos and examples can be compiled by
-     hand (as described above).
-
-  2. configure.cmd does not understand any command line options. If you want
-     to customize the build of the Qt library (which is not recommended), you
-     may try to modify configure.cmd itself.
-
-  3. OS/2 bitmap fonts are not yet supported. Use TTF or Type1 (PFB) fonts with
-     Qt.
-
-  4. No qt3support module. This functionality is rarely necessary in mature
-     real life applications and has low priority.
-
-  5. No native PM style, but Qt will use fonts and colors from the current
+  1. configure.cmd is does not build demos and examples by default (to save
+     time). They may be built by hand, as described above.
+
+  2. configure.cmd does not understand any command line options yet. If you want
+     to customize your build of the Qt library (which is normally not
+     recommended and not supported), you may try to modify configure.cmd itself.
+
+  3. OS/2 bitmap fonts are not supported. Use TTF or Type1 (PFB) fonts with Qt.
+
+  4. No native PM style, but Qt will use fonts and colors from the current
      OS/2 theme. Hint: if your default OS/2 font is "WarpSans", install the
      "Workplace Sans" TTF font from Alex Taylor to get more native look & feel.
-     It is recommended to install version 0.6 of the Normal face and version 0.2
+     It is recommended to install version 0.7 of the Normal face and version 0.3
      of the Bold face which you can find here:
 
        http://users.socis.ca/~ataylo00/creative/fonts/workplace/
 
-  6. QProcess: when starting PM applications from text-mode applications, the
+  5. QProcess: when starting PM applications from text-mode applications, the
      returned PID is a PID of the intermediate cmd.exe process, not the target
      application.
 
-  7. The followign classes are not available due to their rare usage or low
+  6. The following classes are not available due to their rare usage or low
      importance on the OS/2 platform: QSharedMemory, QSystemSemaphore,
-     QInputContext, QAccessible. The following macros are defined to indicate
-     this: QT_NO_SYSTEMSEMAPHORE, QT_NO_SHAREDMEMORY,
-     QT_NO_IM, QT_NO_ACCESSIBILITY. Applications normally use them to guard the
-     relevant parts of code so they should still build.
-
-  8. No QAssistant. No IPV6 support in the network module (QT_NO_IPV6 is
-     defined).
+     QInputContext. On the source level, a number of macros is defined to
+     reflect this, respectively: QT_NO_SYSTEMSEMAPHORE, QT_NO_SHAREDMEMORY,
+     QT_NO_IM. Normally, Qt applications use these macros in the form of
+     "#fndef QT_NO_SOMEFEATURE" to isolate the relevant parts of the code that
+     uses these classes so that the application still builds when the
+     corresponding feature is missing.
+
+  7. No qt3support module. This functionality is rarely necessary in mature
+     real life Qt applications and has low priority. In the code, it is
+     reflected by the absense of the QT3_SUPPORT macro.
+
+  8. The following features are missing (either because of the lack of the
+     required support from the system side or because of the rare usage):
+
+     - IPV6 support in the network module (QT_NO_IPV6 is defined).
+     - OpenSSL support in the network module (QT_NO_OPENSSL is defined).
+     - phonon module (QT_NO_PHONON is defined).
+     - multimedia module (QT_NO_MULTIMEDIA is defined).
+     - OpenGL module (QT_NO_OPENGL is defined).
+     - declarative module (QT_NO_DECLARATIVE is defined).
+     - tablet support (QT_NO_TABLET is defined).
 
   See the project roadmap for more information on the current progress and
