# Documentation

## Qt Reference Documentation

Currently, the Qt Reference Documentation is not shipped with the OS/2 version of the Qt Toolkit (it will be done later).

You can view it online using this link: http://doc.trolltech.com/3.3/index.html.

## Known Bugs and Limitations

The OS/2 version of the Qt Library is not yet complete. Some features are still under development and there are some known bugs. They are briefly described below.

#### Missing features

1 | Drag & Drop (`QT_NO_DRAGANDDROP` is constantly defined for now)
2 | OS/2 widget style (a native look and feel of buttons, combo boxes and other common widgets)
3 | Printing support (`QPrinter` class is absent, `QT_NO_PRINTER` is constantly defined for now)
4 | Process management (`QProcess` class is absent)
5 | Audio support (`QSound` class)
6 | `sql` module (`QSql` class and friends)
7 | `table` module (`QTable` class, depends only on Drag & Drop)
8 | `iconview` module (`QIconView` class, depends only on Drag & Drop)
9 | `canvas` module (`QCanvas` and friends)
10 | `OpenGL` module (`QGL` class and friends)
11 | Plugin support
12 | Qt Designer tool (depends only on Drag & Drop)
13 | Qt Linguist tool (depends only on Drag & Drop)
14 | Qt Assistant tool (depends only on Drag & Drop)

#### Know Bugs and Limitations

1 | Unicode is not fully supported in GUI, to the effect that only the symbols from the current (system) 8-bit charset can appear in widgets and when drawing text.
2 | Alpha blending for pixmaps is not yet implemented [`themes` example].
3 | Complex text transformations (rotation etc.) don't work correctly with the FreeType2 rendering engine. Most likely a bug or a limitation of FreeType2 [`xform` example].
4 | Text rotation to values greater than 90 degrees clockwise doesn't work with truetype fonts and the standard TTF rendering engine. This seems like an OS/2 bug [`xform` example].
5 | Stay-on-top is not supported system-wide.

## GNUMAKE backend for qmake

The GNUMAKE backend generates makefiles for the GNU Make utility from `qmake`'s project files. A separate generator became necessary because the previously used MINGW generator has some problems and limitations that make it impossible to generate correct makefiles in several situations. This new generator is primarily intended to be used with GNU Make under OS/2, but theoretically can be used on any platform after some modifications. However, its usage under other platforms is not tested and not supported.

The GNUMAKE backend was initially based on the existing MINGW backend, so here is the list of its differences and improvements comparing to the MINGW backend:

1. `QMAKE_LINK_OBJECT_MAX`, `QMAKE_LINK_OBJECT_SCRIPT`, `QMAKE_LINK_OBJMOC_SCRIPT` are no longer supported, since the OS/2 version of GNU `LD` (linker) seems not to support object link scripts. The OS/2 CMD.EXE command line length limitation (1024 chars) is worked around in a different way (see the `\mkspecs\os2-g++\qmake.conf` if interested).

2. Added new qmake varibales `QMAKE_RUN_LINK` and `QMAKE_RUN_LIB` (intended to be used in qmake.conf) to explicitly specify the command to execute the linker and the librarian, respectively. These variables are optional and have the following defaults:

    $(LINK) $(LFLAGS) -o $(TARGET) $(DEF_FILE) $(OBJECTS) $(OBJMOC) $(LIBS)
    $(LIB) $(TARGET) $(OBJECTS) $(OBJMOC)

3. `QMAKE_EXTRA_WIN_COMPILERS` and `QMAKE_EXTRA_WIN_TARGETS` are renamed to `QMAKE_EXTRA_COMPILERS` and `QMAKE_EXTRA_TARGETS` respectively, for clarity.

4. Leaving `QMAKE_LIBS_QT_ENTRY` empty does not produce a qmake warning any more.

5. Added the new qmake variable `QMAKE_RUN_IMPLIB` used to produce the import library when the target is the dynamic link library. It is expected that this variable specifies the output import library name with the `$(TARGET_IMPLIB)` macro, which is defined by qmake as the project's target dll full basename with the `.lib` extension.

6. Added new qmake variables `QMAKE_RUN_GENDEF` and `QMAKE_GENDEF_DEPS`. They are intended to generate a `.def` file containing a list of DLL exports when the target is the dynamic link library (i.e. when `TEMPLATE = lib` and `CONFIG` contains `dll`) and the `DEF_FILE` variable is empty or not specified in the project file. In this case, the `DEF_FILE` macro is defined by qmake as the project's target full basename with the .def extension. `QMAKE_RUN_GENDEF` is the command to generate this `DEF_FILE` (its output must go to `$(DEF_FILE)`). `QMAKE_GENDEF_DEPS` is the list of dependencies for the `DEF_FILE`.

7. Empty `OBJECTS_DIR` and `MOC_DIR` qmake variables do not cause GNU Make to print warnings any more.

8. Fixed the `dist` makefile target: the generated zip didn't have the name (only extension).

9. Commands for custom (user defined) targets and for extra compilers (i.e. values of `<my_target>.commands` variables) are now splitted at '`;;` ' sequences (a double semicolon surrounded by single spaces) and placed to separate lines in the makefile. For example, the definition '`<my_target>.command = c1 ;; c2`' will apperar as follows:

    <my_target>: <my_target_deps>
        c1
        c2

10. Added new qmake variables `QMAKE_QUIET_CLEAN` and `QMAKE_IF_FILE_EXISTS`. `QMAKE_QUIET_CLEAN` is similar `QMAKE_CLEAN`, but adds `$(QMAKE_IF_FILE_EXISTS)` to the beginning of each `$(DEL_FILE)` statement to delete a file only if it exists (to avoid system warnings).

11. Object files are no more forced to have the `.o` extension. The standard qmake `QMAKE_EXT_OBJ` variable is used instead (by default, on OS/2 it equals to `.obj`). `QMAKE_EXT_CPP` variable is regarded as well.

12. Library files now have the `.lib` extension (instead of `.a`), and the `lib...` prefix is no more prepended.

13. Added new `QMAKE_CFLAGS_INCDIR`, `QMAKE_LFLAGS_LIBDIR`, `QMAKE_LFLAGS_LIB` qmake variables to make it possible to customize the coorresponding flags (i.e., `-I`, `-L` and `-l`, as for GCC) in the `.conf` file.

14. Added new `QMAKE_LIBS_QT_DLL` and `QMAKE_LIBS_QT_THREAD_DLL` qmake variables to specify the list of libraries required when the application is linked against the DLL version of Qt, separately from the list of libraries required for linking against the static Qt library.

15. The `QMAKESPECDIR` variable is defined in the generated makefile and points to the directory where a `qmake.conf` file being used was read from.

16. Added new qmake variables `DEF_FILE_TEMPLATE` and `DEF_FILE_MAP`. When the target is the dynamic link library and `DEF_FILE` is not defined in the project file, these variables (when defined) go to the generated makefile w/o any changes. They are also appended (as GNU make variables) to the contents of the `QMAKE_GENDEF_DEPS` variable (see 6). `DEF_FILE_TEMPLATE` is intended to point to an existing template for a `.def` file. `DEF_FILE_MAP` should point to an existing file used to store ordinals assigned to exported symbols (to make assignments persistent from build to build). The backend itself doesn't use these variables, they are used only to pass the information from the project file to the generated makefile. It is the responsibility of the `.conf` file to implement the described functionality.

17. Objects defining custom targets got the `.extradeps` attribute. This attrubute allows to specify additional target dependencies that are not followed by commands. That is, if you have the following extra target definition:

    my_target.target = somefile
    my_target.depends = anotherfile
    my_target.extradeps = export SOMETHING = something
    my_target.commands = coolcmd > $$my_target.target

you'll get in the generated makefile:

    somefile : export SOMETHING = something
    somefile : anotherfile
        coolcmd > somefile

Note that if you two or more additional dependencies each placed on a separate line, you can separate them using '`;;` ' (a double semicolon surrounded by single spaces) in the definition of the `.extradeps` attribute.