diff options
Diffstat (limited to 'ubuntu/precise/dependencies/qt3/debian/README.Debian')
| -rw-r--r-- | ubuntu/precise/dependencies/qt3/debian/README.Debian | 277 |
1 files changed, 277 insertions, 0 deletions
diff --git a/ubuntu/precise/dependencies/qt3/debian/README.Debian b/ubuntu/precise/dependencies/qt3/debian/README.Debian new file mode 100644 index 000000000..7cc02d1ec --- /dev/null +++ b/ubuntu/precise/dependencies/qt3/debian/README.Debian @@ -0,0 +1,277 @@ +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 |