source: trunk/README.OS2@ 315

This is Beta 4 of Qt version 4.5.1 for OS/2 and eCS.

This document contains a brief information on the OS/2 version of the Qt library
plus a brief list of OS/2-specific changes from release to release (section
CHANGES below). Please visit the project page at

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

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



REQUIREMENTS

In order to compile the Qt library, 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 above (not tested).
    You can download a copy of the compiler using the following link:

      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

  - 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

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.

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.

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

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.

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 go to the src subdirectory and 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.

NOTES:

  1. Please keep in mind that due to dropping the QTDIR variable recognition,
     qmake.exe now unconditionally uses hard-coded paths to locate various Qt4
     components (such as the include or source directory) during the makefile
     generation process and therefore if you move the Qt source tree to another
     location you will need to run configure.cmd again in order to update these
     hard-coded paths and rebuild qmake and other dependent parts of the
     library.

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



CURRENT LIMITATIONS

  1. configure.cmd is not yet capable to generate 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. OS/2 bitmap fonts are not yet supported. Use TTF or Type1 (PFB) fonts with
     Qt.

  3. Make sure you have the LANG environment variable properly set. The format
     is 'set LANG=ll_CC[.encoding]' where <ll> is the language code, <CC> is the
     country code and <encoding> is the optional encoding to use. If LANG is
     missing or invalid, string conversion operations may work incorrectly
     resulting in distorted text input or output. Note that for most languages
     you will have to specify the encoding number explicitly because Qt and OS/2
     usually disagree about the default encoding for the given language.

     To specify the correct encoding for Qt you need to know your system code
     page number. You can find this number in the COUNTRY statement of your
     CONFIG.SYS. Note however that the code page number from CONFIG.SYS and the
     encoding name you specify in LANG are different things. Qt doesn't
     understand IBM code page numbers directly. In most cases, you can get the
     encoding name by prepending 'cp' to the code page number (for example,
     'cp850' for code page 850) but sometimes this will not work because not all
     encodings have 'cp'-like aliases. In this case, you should google around to
     find the correct encoding name for your code page number. Here is a couple
     of examples of the proper LANG specification:

       set LANG=de_DE.cp850             - for the German OS/2 locale
       set LANG=ru_RU.cp866             - for the Russian OS/2 locale

     Later, the correct encoding for the system code page will be detected
     automatically and specifying it in LANG will not be necessary.

  4. Some functionality of the already available Qt classes may be limited or
     unimplemented. If you find such a case and there is no ticket for it
     in the bug tracker, feel free to add one.

  5. No qt3support module. This functionality is rarely necessary in mature
     real life applications and has low priority.

  6. 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).
     Note that v0.5 of the font has known sizing and spacing problems and also
     supports only the Latin1 code page. To avoid these problems, use v0.4 which
     you can download here:

       http://users.socis.ca/~ataylo00/creative/fonts/wpsu_ttf_04.zip

  7. QProcess: when starting PM applications from text-mode applications and
     when detaching applications with startDetached(), the returned PID is a
     PID of the intermediate cmd.exe process, not the target application.

  8. No QDesigner, no QAssistant.

  9. No clipboard, no Drag&Drop, no printer support. See the project roadmap for
     more information on the current progress and future plans:

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



CHANGES

Beta 4 (11-11-2009)

  Improvements:

  - Added sound support (implemented QSound class).

  - Added system tray support (QSystemTrayIcon class). This support requires
    the Extended system tray XCenter plugin to be installed. See the note above
    on how to compile and install this plugin.

  - Enabled QPlugin support on OS/2. This in turn enables SVG support for
    QIcon (which is built as a Qt plugin DLL by default).

  - Better widget modality support (widgets blocked by modality cannot be
    activated and moved using the mouse and the title bar anymore).

  - Added support for 'console' and 'windows' CONFIG options in .pro files.
    Now, if 'windows' is present, the target executable will have the WINDOWAPI
    attribute set which effectively makes it a PM application. This, in
    particular, disables standard input, output and error streams so that when
    started, the application will not have a console window attached to it and
    will not support input/output redirection operators on the command line.
    By default, 'console' mode is active unless you perform a release build and
    the application is linked against the QtGui library ('QT = gui' in .pro),
    in which case the default is 'windows'.

  - Improved paint speed in Qt windows which should increase overall graphical
    UI performance by 10%-20% in Qt4 applications.

  - Implemented setting window icons for top-level windows (using
    QWidget::setWindowIcon()).

  - Added LxLite support to provide compression for executables and DLLs. The
    compression is controlled by the 'exepack' CONFIG option which is turned on
    by default for release builds if the LxLite executable is present in PATH
    during the configure.cmd invocation. The compression may be turned off on a
    per-project basis by adding a 'CONFIG -= exepack' line to the .pro file.

  - Improved the section of this README.OS2 file that describes how to properly
    set the LANG variable to have correct national characters in file names and
    in window titles of Qt applications.

  Fixes:

  - QProcess: The executable's path was not always added to BEGINLIBPATH.

  - Fixed-size top-level widgets could not be moved.

  - Application crash after pressing a button in a dialog window that resizes
    this dialog (for example, makes it bigger to show more information).

  - Resizing top level windows using the top border broke mouse coordinates so
    that Qt tought you pressed the mouse button in a different place of the
    window than where you actually did it.

  - Events posted with QCoreApplication::postEvent() were only processed upon
    receiving a next message from the system. This caused funny delays such as
    controls in a Qt window still indicating the input focus (the dotted
    rectangle) after the window was deactivated and losing this indication only
    when the mouse pointer was moved over the window.

  - Don't replay mouse button press on a push button that is showing a popup
    menu but instead hide the popup menu and unpress the button to get more
    native look and feel.

  - Deactivating the window with a push button showing a popup menu would hide
    the popup but leave the button pressed.

  - Fixed incorrect Qt dirty widget region calculation when processing WM_PAINT
    messages. This fixes a lot of redraw problems (menu items in the main menu
    bar, text in combo-boxes, various redraw problems in smplayer when switching
    interfaces and going to/from fullscreen, and similar).

Beta 3 (17-10-2009)

  Improvements:

  - Added proper font support. All outline (scalable) fonts visible in the Font
    Palette should be now recognized by Qt. The fonts are hinted and antialiased
    using the Freetype2 library when drawing text.

  - System fonts and colors are now used by default for Qt widgets.

  - configure.cmd now generates the main Makefile to simplify building of Qt.

  - corelib: QProcess: Implemented child termination detection.

  - corelib: QProcess: Implemented redirection to another QProcess.

  - corelib: QProcess now uses native pipes for stream redirection. This fixes
    various issues like 'Socket operation on non-socket' errors during
    parent-child communication.

  - corelib: QProcess: Make sure that the directory containing the executable
    file is always searched (first) for DLLs needed by this executable. This
    makes it unnecessary to change the current directory to the executable's
    directory or add it to LIBPATH before starting the Qt application.

  - corelib: QProcess can now start applications of different type (e.g. PM
    applications from text-mode applications) directly.
    QProcess::startDetached() also works.

  - qmake: In debug_and_release mode, 'release-(all|clean|distclean|install|
    uninstall)' and 'debug-(all|clean|distclean|install|uninstall)' make
    targets are now available.

  Fixes:

  - Doing 'make clean' could result into a hang due to CMD.EXE command line
    length limitation.

  - corelib: Fixed: QProcess: Lost data during stream redirection.

  - corelib: QSettings could sometimes distort data when saving it to the
    registry (by replacing some characters with codes 0x80 and above with '?').

Beta 2 (17-09-2009)

  Improvements:

  - Ported the network module (QtNetwork4.dll) and added to the default build.

  - Added modules sql, svg, xmlpatterns, scripttools, plugins to the default
    build.

  - gui: Added recognition of dead keys which makes it possible to type
    umlauts and other accented characters that require composition.

  - gui: Implemented standard cursor shapes in Qt applications.

  Fixes:

  - qmake: Fixed the trailing slash problem which caused qmake to generate
    incorrect makefiles and fail to build the Qt library on some platforms.

  - configure.cmd: Return to the root source tree directory after building
    qmake.

  - qmake: Automatically use different link flags when linking qmake with WLINK.

  - qmake: Recognize TARGET_SHORT that allows to specify a short DLL name
    (vital for OS/2 which reqires DLL names to be in 8x3 format).

  - build: Set short DLL names for Qt modules on OS/2 using TARGET_SHORT.

  - corelib: Various fixes to file system classes that deal with the file name
    case (which should be ignored on OS/2) and forward and back slashes.

  - corelib: Fixed: QMutex could let more than one thread access the protected
    resource.

  - corelib: Standard stream redirection in QProcess should now work for
    kLIBC-based child processes. Redirection for all other applications
    (such as CMD.EXE) will be added later (seems to be a kLIBC bug/feature).

  - gui: Fixed erroneous QFileDialog behavior (duplicate entires in the list,
    incomplete contents of the root directory of the current drive).

  - gui: Fixed: Ctrl+A..Z should generate characters with codes 0x01-0x1F.

  - gui: Fixed: Close popups when resizing/moving the top level window.

  - gui: Enabled actual enforcing min/max Qt widget constraints for top-level windows.

  - gui: Fixed child widget duplication when resizing top level widgets after
    showing a popup; moving native child widgets should now work correctly.
    This also fixed a number of redraw problems (for example, drawing the main
    menu and tool bars in smplayer, moving tool bars around in other
    applications such as textedit from the demo folder).

Beta 1 (29-08-2009)

  - First public release.



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.