tde-packaging/ubuntu/maverick/dependencies/qt3/debian/README.Debian

Qt for Debian README
--------------------

1. Preface

This README is intended to give developers and users exact information
about how the qt-x11-free package provided by TrollTech AS has been packaged
for Debian in case you either want to faciliate it for development 
of applications and libraries or plugins using the Qt class library. With 
qt-x11-3.1.1, the Debian packages have been massively restructured to get 
the most out of theoriginal Qt package and spit the contents up into 
several packages so that they make the most sensefor several groups of 
users; developers, application users, translators of Qt-based 
applications and Debian packagers who are packaging applications developed 
with Qt.2. 

2. General Overview

As Qt is a huge package that contains a complete environment for 
developers, it needs to be split up into several packages that make it 
easier for everyone else to handle it and not to require 
unnecessary disk space for end-users. Additionally, Qt can be configured 
in several ways - and therefore also used in several ways. Qt development 
usually requires the environment variable QTDIR. As Debian is placing 
libraries and header files in a quite specific filesystem order, this 
usually breaks setting a single environment variable to meet the 
requirements of packages. Therefore, symlinks are used to set up the system 
to meet both, the Debian filesystem standard and the QTDIR variable. All of 
Qt (so the QTDIR path) is available in /usr/share/qt3. If you need to set 
QTDIR, do export QTDIR=/usr/share/qt3

As far as the common build configuration goes, we note explicitely that the 
Debian package of Qt will in very rare cases break the compilation (most 
likely the linking) of applications on Debian which use Qt, in particular 
utilizing styles in an incorrect way by deriving from one of the styles 
that ship with Qt. In case you are a Debian packager and encounter 
problems, contact Debian Qt/KDE Maintainers (debian-qt-kde@lists.debian.org).
We will tell you why things don't work and what you should communicate on 
with the programmers of your application that you are packaging. The build 
configuration generally is intended to provide a Qt version that is as 
small as possible in terms of the memory size it requires. Therefore, 
everything inside Qt that can be compiled as plugins has been compiled that 
way. This includes: 

- imageformats: jpeg and mng - codecs (for languages like arab, japanese 
  etc provided with Qt) 
- sql drivers for databases (MySQL, ODBC and PostgreSQL)

The only exception is the imageformat png which has been compiled built-in 
due to the fact that there is literally no program that uses no icons at 
all and icons are to be used preferrably in png format. The plugins are all 
located under /usr/lib/qt3/plugins. This is also the install location you
should choose as a package maintainer for 
qt-plugins so the user doesn't have to customize his library path for 
loading Qt plugins. The only exception is that KDE delivers a set of Qt 
plugins as well (mainly styles and designer plugins); those are placed in 
/usr/lib/trinity/plugins. 

QMotif Extension: As this code is only available in commercial environments 
(and produces a static library libqmotif.a anyway that those commercial 
applications have to be linked against in addition to Qt), we left out all 
header files of the libqt3-headers package that are belonging to this 
QMotif extension.

Oracle Database driver, Sybase & Microsoft SQL Server driver: Those drivers 
are only available in a commercial version of Qt due to license 
incompatibilities with the GPL. If you need to faciliate those drivers, 
please visit http://www.trolltech.com and have a read at 
http://doc.trolltech.com/3.0/sql-driver.html.
  
3. Packages (End-User) 

The Qt built has been split up into several packages that allow for easy 
installation for all types of users. The End-user usually only requires to 
have the following packages installed to run an application that links 
against Qt:

Threaded version:libqt3-mt (the library libqt-mt.so.* and libqui.so.* for 
loading designer-made user interfaces at runtime).

Optionally depending on the program's requirements:

libqt3-mt-odbc
libqt3-mt-mysql
libqt3-mt-psql 

In addition to the libraries, it may make sense to install the program 
qtconfig to customize the look and behaviorof Qt programs. If you have KDE 
installed, the KDE control center will take this task automatically in most 
cases. qtconfig is available in the package qt3-qtconfig.

Also, Qt programs can make use of the online-help tool that ships with Qt, 
the Qt Assistant. The Assistant can be installed with the package 
qt3-assistant.

Qt Configuration files
----------------------
Qt programs most often use QSettings to store their information in configuration
files. With Qt 3.2, the new option --sysconfdir has been introduced that allows
us to use /etc/qt3 as the system-wide location where qt-program specific global
configuration files can go. If you're a programmer that wants to get familiar with
that, please look at the examples, documentation and the code in designer or
assistant as well as qtconfig.

4. Packages (Package maintainers)

In addition to the library, a package maintainer will require an additional 
set of packages to compile a package that requires Qt. Depending on the 
version of the qt library, you will require a different set of packages; 
the most common option should be to make your application link against the 
multi-threaded version (-mt).Packages necessary for compiling Qt 
applications from source:

libqt3-mt-dev   (use libqt3-dev for linking against -lqt, this package only 
                contains the .so files and the header file for libqui.so)

libqt3-headers  (header files for libqt and libqt-mt)
 
qt3-dev-tools  (this package contains the tools uic and moc as well as 
qmake, required for building Qt applications) 

If, however, you encounter an older program not to compile with this set 
read the FAQ at the end of this document.

5. Packages (Developers)

In addition to the packages that packagers require, a developer usually 
will require the Qt API documentationas well as tools like the assistant, 
linguist or designer. However, you should be fine with installing the API 
documentation that you can browse with a webbrowser, optionally with the 
assistant. They are available in /usr/share/doc/qt3-doc/html.
For a regular development environment, install qt3-designer and qt3-doc.

For faciliating Qt's extended environment to write plugins for the Qt 
Designer or extend the Designer as well as utilizing the Qt Assistant by 
calling it from within your program, install qt3-apps-dev, which contains
the static libraries and header files required for this functionality.

For Embedded Developers, the program qvfb (Qt Virtual Frambuffer) and 
makeqpf (embedded fonts tool)have been packaged into 
qt3-dev-tools-embedded. For developers that work on migrating their program 
from any Qt version prior to Qt 3.x to the Qt 3.x platform you will find 
additional tools in the qt3-dev-tools-compat.

For using the QTranslator class and where to find the qm-file for qt as 
well as where to place your translations,see the next section.

If your program doesn't compile with those settings in case you have 
started your project with Qt 1.x or 2.x, please read the FAQ section at the 
end of this document.

5. Packages (Translators)

In order to translate a Qt program into any other language, the Qt 3 way to 
do this is to let the developer create a ts-file containing the strings 
that the program exposes on the user interface. The tools to create the 
ts-file and to create the final qm (Q-message binary) file, lupdate and 
lrelease, are included in qt3-dev-tools.The single translator that only 
gets provided the ts file and has to return a translated ts file, it 
is absolutely enough to install qt3-linguist; the package qt3-assistant can 
be installed to access the online-help for the Qt Linguist itself.
In case you're converting an application using Qt prior to Qt 3, you may 
want to uitilize the qt3-dev-tools-compat which include the necessary tools 
to convert older qm files to the new ts file standard.

Locations of message translations: 

Qt ships with a set of translations for the strings used inside Qt. Those 
translations will be installed into /usr/share/qt3/translations (qm files 
only), which equals $QTDIR/translations respectively 
qInstallPath() + QString( "/translations" ). 

The configure option --translationdir has been set to /usr/share/qt3/translations
accordingly since it was introduced in Qt 3.2. 

To correctly enable your program to display the translations to the Qt 
library and to load the translation of the program itself, we currently 
suggest to either install your translations along with any other data files 
into/usr/share/<appname>/, translation files into the subdirectory 
translations (that is /usr/share/<appname>/translations) The code that your 
application should use to load the Qt translation will have to look like 
the following:    

int main( int argc, char **argv )
    {
        QApplication app( argc, argv );

        // translation file for Qt
        QTranslator qt( 0 );
        qt.load( QString( "qt_" ) + QTextCodec::locale(), qInstallPath() + 
        QString( "/translations" );
        app.installTranslator( &qt );

        // translation file for application strings
        QTranslator myapp( 0 );
        myapp.load( QString( "myapp_" ) + QTextCodec::locale(), "." ); 
        // use a substitue for $prefix/share/appname/translations here      
        app.installTranslator( &myapp );

6. Frequently Asked Questions

Using Qt for Debian as a developer or packager 
----------------------------------------------

Q: I want to compile a source package that utilizes qmake to build the 
Makefiles. What do I need to do to makeit work ?

A: qmake requires two environment variables to be set, QTDIR and QMAKESPEC. 
To make it work, do
export QTDIR=/usr/share/qt3
export QMAKESPEC=linux-g++

Then run qmake -o Makefile <projectfile>.pro

After that, the Makefile is correctly created to build your application on 
Debian. As a packager, export thosetwo variables in the rules file before 
calling qmake.

Q: I have an application that when linking gives me symbol referencing 
errors to Q*Style. Why does my applicationnot link correctly ?

A: The author of the program is using the styles that ship with Qt directly 
instead of using the QStylePlugin interface.If you are the author of the 
program, change your program to use QStylePlugin. If you are a packager, 
write to theauthor of the program that he is assuming that the styles 
shipped with Qt are built-in to the library which is not the case on Debian 
and that he please should fix this and use QStylePlugin.

Q: Where are all the examples and tutorials ? And how do I build them ?

A: Qt ships with examples and tutorials; so does the Linguist and Designer. 
The tutorials and examples are compressed tarballs which you can unpack with 
tar -zxvf into your home directory. Change into the qt3-examples directory
and run the provided ./build-examples script. All Qt examples and tutorials,
including those for designer and the linguist, will be compiled. You will
notice however, that those examples that inherit from style classes which
are not built-in into Qt but configured as a plugin will not compile due
to the fact that they can't link to the Qt library. 

Q: I'm writing a pure Qt application and I want to ship it with a default 
configuration file. Where does that global configuration file go if I make 
use of the QSettings class ? 

A: With qt-3.2.0, Trolltech has introduced a configure option to Qt called
--sysconfdir which we intentionally set to /etc/qt3 similar to /etc/trinity for
KDE programs. Install your application's system wide configuration file
to /etc/qt3. 

Q: I'm compiling a program and I have a compile error due to a missing 
include. Why isn't that include not present in the Debian packages anymore 
? It compiled with older versions of Debian packages of Qt !

A: This may be due to two reasons: either the package still uses the old 
includes from Qt 1.x or 2.x that got basically renamed by Trolltech due to 
the naming convention. The filenames are now all following the scheme 

ClassName -> classname.h. 

Therefore, if you are the developer of the affected program, change your 
sources according to this scheme. Qt ships with two tools, qt20fix and 
qtrename140, to help developers migrate their API to the Qt 3 version, 
which can help you in the transition upgrade to Qt 3.

If you are affected by this as a packager, notify upstream to fix those 
problems and in the meanwhile use libqt3-compat-headers as a build 
dependency which includes the compatibility headers that just include the 
right files from the new API again.

Q: I have a question not covered by this FAQ and README file. Who should I 
turn to ?

A: Please turn to Debian Qt/KDE Maintainers (debian-qt-kde@lists.debian.org) 
for any questions regarding Qt on Debian.

 -- Ralf Nolden <nolden@kde.org>  Sun, 26 Jan 2003 20:39:19 +0100
 -- Ralf Nolden <nolden@kde.org>  Mon,  1 Sep 2003 19:24:16 +0200
 -- Modestas Vainius <modestas@vainius.eu> Fri, 22 Feb 2008 01:40:06 +0200