source: trunk/README.OS2@ 763

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
library. Please read it carefully before starting your work. You may also
visit the project page at

  http://svn.netlabs.org/qt4/wiki

to get more information and the latest news and also to report bugs.

To get a brief list of OS/2-specific changes from release to release
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.



REQUIREMENTS

In order to compile the Qt library and Qt-based applications, you will need
the following tools:

  - One of the OS/2 Warp 4, OS/2 Warp 4.5 or eComStation operating systems.

  - 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
    from:

      ftp://ftp.netlabs.org/incoming/eCUPS003.wpi   or
      ftp://ftp.netlabs.org/pub/ecups/eCUPS003.wpi

    Linking against eCUPS also requires pthread.lib:

      http://web.os2power.com/download/lib/pthread-20100217-os2.zip



SETTING UP THE ENVIRONMENT

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).
Execute this script in a command line session to make it ready for building
Qt 4 applications (for example, using the "qmake" command follwed by "make"
for applications based on qmake project files which most of them are). If you
go that way, you may skip the rest of this section and proceed directly to
section called "USING OFFICIAL BINARY QT ARCHIVES" or further. 

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 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,
qmake will use the specification stored in the <Qt4_Home>/mkspecs/default
directory, which on OS/2 always refers to the "os2-g++" specification, the only
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 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