This is Beta 5 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. 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. 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 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 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. 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 /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-os2_g++-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 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 \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-os2_g++-lib-X_Y_Z.wpi - Runtime DLLs and binaries ("lib" package) qt-os2_g++-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. 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 binary "lib" and the "dev" packages, the following official non-binary packages exist that you may also find useful: qt-examples-src-X_Y_Z.wpi - Demo and example sources ("examples") 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. 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. 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 and specifying LANG will be not necessary at all. 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. 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 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 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 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.