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 - 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% 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 /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 \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. 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. In order to let Qt correctly detect the regional settings and choose the right language for translating the user interface, the LANG environment variable must be set. The format is set LANG=ll_CC where is the language code and is the country code (refer to wikipedia.org to find correct letters for your langage and country if you do not know them). Note that the optional encoding part of the LANG specification is ignored by Qt for OS/2 since 4.5.1 Beta 5 because it now detects the encoding automatically based on the system OS/2 settings. Later, the correct language will be detected from the system settings so that specifying LANG will be not necessary at all. 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. 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/ 7. 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. 8. 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. 9. No QAssistant, no printer support (QT_NO_PRINTER and QT_NO_PRINTDIALOG are defined). 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.