source: trunk/README.OS2@ 684

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



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.

  - 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

  - eCUPS 1.3.11 or later to support printing in Qt. The eCUPS WPI is available
    at:

      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

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

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

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.



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.

When the environment is set up, go to the directory where you unpacked the
Qt4 source tree and type:

  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.

The next step is to type:

  make

This will compile and link the 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
co-exist in the same source tree and may be used in parallel: all the debug DLLs
get a 'd' letter in their name preceeding the Qt major version number and use
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.

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 built during the normal Qt build process
     and can be found in the file \plugins\xcenter\xsystray.dll in the Qt source
     tree. In order to install the plugin, do the following:

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

     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 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!

     In order to nicely solve this problem, netlabs.org provides the official
     binary builds of the Qt library distributed as WPI packages which are
     described in the next section.



USING OFFICIAL BINARY QT PACKAGES

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
helper binaries) necessary to run applications created using the Qt framework.
This package is usually installed by end users together with the Qt applications
they want to use.

The "dev" package 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
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.

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 really difficult to identify various
     distributions and track possible problems with the builds.



QMAKE CONFIG OPTIONS

The following CONFIG options of the qmake utility 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. This option is set by default.

  exepack           Turns on compression for executables and DLLs. The option is
                    turned on by default for release builds if configure.cmd
                    finds 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.



ENVIRONMENT VARIABLES

The Qt library recognizes a number of OS/2-specific environment variables that
affect its functionality at runtime. The table below lists these variables and
their meaning:

  QT_PM_NO_SOUND_SHARE      If set, Qt will open the audio device in exclusive
                            only one sound may be played on the computer at a
                            time. This mode is recommended for some sound cards
                            when using the Uniaud audio driver as it is known to
                            have problems with simultaneous playback. In current
                            Qt builds, this is the default behavior if neither
                            this nor the QT_PM_SOUND_SHARE variable is set.

  QT_PM_SOUND_SHARE         The opposite to the above. If set, Qt will open the
                            audio device in shared mode. This variable is
                            ignored if QT_PM_NO_SOUND_SHARE is set.

  QT_PM_NO_REGISTRY         If set, Qt will not use the Open32 registry to store
                            application settings with QSettings. Instead, plain
                            text INI files will be used for both NativeFormat
                            and IniFormat. Due to a number of problems in the
                            Open32 registry implementation (that may easily lead
                            to registry corruption), this is the default
                            behavior if neither this nor the QT_PM_REGISTRY
                            variable is set.

  QT_PM_REGISTRY            The opposite to the above. If set, Qt will use the
                            Open32 registry to store application settings. This
                            variable is ignored if QT_PM_NO_REGISTRY is set.

  QT_PM_NO_SYSTEM_LOCALE    If set, Qt will ignore the regional settings from
                            the system locale object found in the Country
                            Palette located in the System Setup folder and will
                            take them from the internal Qt locale database
                            according to the current country and language
                            settings. Due to the fact that this internal Qt
                            database usually has a better representation of the
                            regional settings, this is the default behavior if
                            neither this nor the QT_PM_SYSTEM_LOCALE variable is
                            set.

  QT_PM_SYSTEM_LOCALE       The opposite to the above. If set, Qt will use the
                            regional settings as found in the default locale
                            object set the Country Palette.  This variable is
                            ignored if QT_PM_NO_SYSTEM_LOCALE is set.

  LANG                      This variable can be used to override the default
                            country and language used in the Qt application both
                            for regional settings and for translations. The
                            format of the value is "ll_CC" where <ll> is the
                            two-letter ISO language code and <CC> is the two-
                            letter ISO country code. Note that if this variable
                            is not set, Qt will derive the language and country
                            from the system country code specified in the
                            COUNTRY statement of CONFIG.SYS.



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.



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
     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
     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
     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
     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).

  See the project roadmap for more information on the current progress and
  future plans:

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

  Feel free to request new features and report bugs using the project bug
  tracker abaialble at:

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



CREDITS

Dmitry A. Kuminov (development)
Silvan Scherrer (management)

netlabs.org (hosting & support)

Nokia Corporation (original Qt library)

We also want to THANK all individuals and organizations who made the donations
to this project and helped to make it happen. Please visit

  http://qt.netlabs.org/en/site/index.xml

to get the full list of sponsors and to find information on how you can support
the project.


Qt is a trademark of Nokia Corporation and/or its subsidiary(-ies).
OS/2 and OS/2 Warp are trademarks of the IBM Corporation and/or its subsidiary(-ies).
eComStation is a trademark of Serenity Systems International and/or its subsidiary(-ies).
Etc.