source: trunk/README.OS2@ 1040

This is Qt version 4.6.3 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.

  - IBM RC (Resource Compiler) Version 5.00.007 (comes with OS/2 Toolkit 4.5)
    or Version 4.00.011 (comes with eCS 2.0). Other versions may not work
    correctly.

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:

  - Perl 5.8.2 or above. This is required if you want to perform a shadow build
    of the Qt library (which is a recommended way to go). Please refer to
    section "COMPILING QT" for more information about shadow builds. Recent
    builds of Perl for OS/2 are available here:

      http://os2ports.smedley.info/index.php?page=perl

  - MAPSYM 4.00.000 (Oct 4 2001) to enable generation of symbol (.SYM) files for
    DLLs and executables. This tool comes with OS/2 Toolkit 4.5. Note that other
    versions of this tool may not work correctly.

  - LxLite 1.3.3 or above (not tested) to enable the compression of DLLs and
    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

  - CUPS 1.3.11 or later to support printing in Qt. The CUPS libraries are
    available at:

      http://download.smedley.info/cups-1.3.11-os2-20090807.zip

    Linking against eCUPS also requires pthread.lib:

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

  - OpenSSL 0.9.8o or later to support OpenSSL in Qt. The OpenSSL libraries are
    available at:

      http://bauxite.sakura.ne.jp/tmp/os2/openssl-1.0.0a-os2knix-20100706-runtime.zip
      http://bauxite.sakura.ne.jp/tmp/os2/openssl-1.0.0a-os2knix-20100706-dev.zip

  - MySQL 5.1 or later for the MySQL Qt plugin. The MySQL libraries are
    available at:

      http://download.smedley.info/mysql-5.1.51-os2-20101001.zip

    Note that you will also need the above OpenSSL libraries and pthread.lib to
    be able to use this MySQL build. The MySQL Qt plugin itself will require
    OpenSSL DLLs in your LIBPATH at runtime.

  - PostgersSQL 9.0.1 or later to support the PostgresSQL Qt plugin. The
    PostgresSQL libraries are available at:

      http://download.smedley.info/postgresql-9.0.1-os2-20101108.zip

    Note that you will also need libc064x.dll for this PostgresSQL build:

      http://download.smedley.info/libc064x.zip

    Note that you will also need the above OpenSSL libraries and pthread.lib to
    be able to use this PostgresSQL build. The PostgresSQL Qt plugin itself will
    require OpenSSL DLLs in your LIBPATH at runtime.



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 "USING OFFICIAL BINARY QT ARCHIVES" below.

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:

  - Unzip the CUPS libraries to some directory and set the following environment
    variables to tell the Qt configure script its location:

      set CUPS_INCLUDEPATH=<path_to_CUPS>\include
      set CUPS_LIBS=-L<path_to_CUPS>\lib -llibcups.a -L<path_to_pthread> -lpthread.lib

  - Unzip the OpenSSL libraries to some directory and set the following
    environment variables to tell the Qt configure script its location:

      set OPENSSL_INCLUDEPATH=<path_to_OpenSSL>\include
      set OPENSSL_LIBS=

    Note that you will also need to place OpenSSL DLLs to BEGINLIBPATH (if they
    are not already in your LIBPATH) so that Qt applications can find them at
    runtime:

      set BEGINLIBPATH=<path_to_OpenSSL>\dll;%BEGINLIBPATH%

  - Unzip the MySQL archive to some directory and set the following environment
    variables to tell the Qt configure script the library location:

      set MYSQL_INCLUDEPATH=<path_to_MySQL>\include'
      set MYSQL_LIBS=-L<path_to_MySQL>\lib -lmysqlclient_r -L<path_to_OpenSSL>\lib -llibssl -llibcrypto -L<path_to_pthread> -lpthread

    Note that you will also need to place OpenSSL DLLs to BEGINLIBPATH (as
    described above) because the MySQL plugin links statically to them and Qt
    will not be able to load it otherwise.

  - Unzip the PostgresSQL archive to some directory and set the following
    environment variables to tell the Qt configure script the library location:

      set PSQL_INCLUDEPATH=<path_to_PostgresSQL>\include'
      set PSQL_LIBS=-L<path_to_PostgresSQL>\lib -llibpq -L<path_to_OpenSSL>\lib -llibssl -llibcrypto -L<path_to_pthread> -lpthread

    Note that you will also need to place OpenSSL DLLs to BEGINLIBPATH (as
    described above) because the PostgresSQL plugin links statically to them and
    Qt will not be able to load it otherwise.

Note that you need to make sure that OpenSSL DLLs are in BEGINLIBPATH or in
LIBPATH before Qt attempts to load the SQL plugins for the first time. If it
fails to load them, it will cache a failure and will not retry even if the
plugins can be loaded later. To fix that, you need to delete the file
%HOME%\.config\Trolltech.ini where this cache is stored.



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 as described above, you may build the Qt library.
There are two distinct ways of doing this: in the source tree or in a separate
directory of your choice. In the first case, all results of the build process
(intermediate object files as well as final executables and DLLs) will be placed
right in the source tree. In the second case, they will be placed in the
separate directory -- this is called a shadow build.

Shadow builds are the recommended way to go because they keep the source
directories clean and also allow to use the same source tree for creating any
number of builds, each with its own build options.

To perform a shadow build, do the following steps:

  1. Create a directory outside the Qt4 source tree.

  2. Go to that directory.

  3. Type:

     <source_tree>\configure.cmd

     where <source_tree> is the directory containing the Qt4 source tree. This
     will create all necessary configuration files, headers, Makefiles and will
     also build the qmake tool which is necessary to control the rest of the
     build process (note that building qmake will take some time).

  4. Once the configure process is finished, type:

     make

  Note that by the default the shadow build will produce the release version of
  the Qt library. This may be changed by passing command line options to
  configure.cmd at step 3. For example, the debug build can be requested using
  the '-debug' option. For a full list of options supported by configure.cmd,
  type:

     configure.cmd -h

To perform a normal build, you execute 'configure.cmd' followed by 'make' right
in the directory containing the Qt4 source tree. The default in this case is to
build both the debug and release versions of the Qt library.

Please keep in mind that in case of the dual debug and release build (where both
flavors are stored in the same build directory), only DLL and LIB files will be
separated (because the debug versions of them will have the 'd' suffix in the
file name). Executable files are normally taken from the release build but,
since the file names are identical, sometimes they may be overwritten by the
debug versions (e.g. when you rebuild parts of the library later). For this
reason, performing dual builds is not recommended.

The Qt library is huge so the build process will take several hours (or even
several dozen of hours) depending on your hardware and configure options.

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 'make'.

NOTE:

     This version of Qt for OS/2 includes the Extended system tray plugin for
     XCenter/eCenter which is necessary to enable Qt support for the special
     notification area on the XCenter/eCenter panel (called the "system tray")
     which is used by many long-running applications to display their status.
     In order to activate this support, you need to install this plugin to your
     XCenter or eCenter. The plugin is split in two DLLs, the plugin DLL and
     the API DLL. Both are built as part of the normal build process and can be
     found in the "src\3rdparty\os2\xsystray\tmp\dist" subdirectory of the Qt
     build tree. In order to install them, do the following:

     a. Copy "plugin\xsystray.dll" to "<XWorkplace_install>\plugins\xcenter\"
        (on eComStation, this will be "C:\ecs\system\ewps\plugins\xcenter\"
        where C: is your boot drive).

     b. Copy "apilib\xsystray.dll" to a directory listed in LIBPATH.

     b. Restart WPS.

     c. Add the "Extended system tray" widget to the XCenter/eCenter panel using
        the XCenter context menu ('Create new widget').

     Note that if you upgrade from the previous version of the plugin then
     please unlock xsystray.dll in the target folder using the UNLOCK.EXE
     utility (which you can find in the LxLite package, for example) before
     performing step a., otherwise the copy operation will fail.

IMPORTANT NOTE:

     Please take into account that the Qt library you build on your own as
     described above is NOT intended for wide distribution with Qt applications
     you port or create. Such private Qt builds help you develop Qt applications
     (because you can easily debug your program and parts of the Qt framework at
     the source level) but being widely distributed they will create a so-called
     DLL hell when a program running on a user computer crashes because it picks
     up a wrong build of the Qt library. This will happen because even a single
     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 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 archives which are
     described in the next section.



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) 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 Qt applications
they want to use.

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

     All .DLL and .EXE files of the official binary build contain a DESCRIPTION
     string with the vendor field set to "netlabs.org" (by contrast, all custom
     Qt builds will set the vendor field to what the USER environment variable
     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 difficult to identify various distributions
     and track possible problems with the builds.



QMAKE CONFIG OPTIONS

The following CONFIG options of the qmake tool have a special meaning in OS/2:

  windows           Turns on generation of PM (WINDOWAPI) executables. By
                    default, this option is set for release builds that link
                    to the Qt GUI library.

  console           Turns on generation of text mode (WINDOWCOMPAT) executables.
                    By default, this option is set when setting the "windows"
                    option is not appropriate (see above).

In addition, qmake recognizes the following OS/2-specific CONFIG options:

  map               Turns on generation of the .map files for executables and
                    DLLs. Note that this option is not set by default.

  sym               Turns on generation of the .sym files for executables and
                    DLLs. The option is turned on by default if configure.cmd
                    is able to find the MAPSYM tool in PATH.

  exepack           Turns on compression for executables and DLLs. The option is
                    turned on by default for release builds if configure.cmd
                    is able to find a compression tool (LxLite) in PATH.

  highmem           Turns on high memory usage for dynamically allocated memory
                    in DLLs and executables. When this option is set, a special
                    compiler flag (-Zhigh-mem for GCC) is used to enable high
                    memory support in the C library (LIBC). This option is set
                    by default so that all Qt DLLs and Qt applications built
                    with qmake are enabled for high memory. Note that high
                    memory support must be enabled for all LIBC-based DLLs
                    linked to the executable as well as for the executable
                    itself: high memory usage will be disabled if one of them
                    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.



FILE WATCHING FUNCTION

Qt supports a mechanism of notifying Qt applications about changes to the file
system, such as creating files or directories, changing their attributes or
deleting them, even if these changes are performed outside Qt applications. In
particular, this is used in standard Qt open file dialogs where you can
instantly observe changes made to the directory contents by third-party
applications running in the background.

In order to support this functionality on OS/2, Qt relies on the file watching
mechanism provided by the Presentation Manager. This mechanism is a global
system resource so that only one process may use it at a time. In a standard
installation of OS/2 or eComStation this resource is exclusively used by the
Workplace Shell and is not available to other applications. In order to overcome
this limitation, a respective function was included to xWorkplace, the famous
WPS extension (which lives inside the WPS process), starting with version 1.0.8.
This function allows any number of other processes to receive notifications
about file system changes and it gets utilized by Qt as well.

If an earlier version of xWorkplace is installed on the user system, or if no
xWorkplace extension is present at all, Qt uses its own method of detecting
file system changes which is based on polling the directory contents in regular
intervals. While this method works well for a small number of watched
directories with just few files in them, it may significantly slow down the
system if you work with a directory containing thousands of files.