This is a patched version of Qt.  It may include changes made by KDE
and Qt developers that have either not been accepted for inclusion
into Qt, or have been accepted for a later version of Qt than this
one.

1. Configuring Qt
=================

The recommended compile line is:

--default-config-begin--

  ./configure -qt-gif -debug -fast -no-separate-debug-info \
     -system-libpng -system-libjpeg -system-zlib \
     -dbus -webkit -plugin-sql-mysql \
     -nomake examples -nomake demos -prefix <installdir>

--default-config-end--

It contains "-debug", which greatly improves the use for backtraces (but
also needs a lot more disk space and makes things slower). To build in
release mode, replace it with "-release".

It also contains "-no-separate-debug-info", which disables separate .debug
files. Instead, the debug information will be built into the libraries.
This option is needed when you install Qt.

If you don't install Qt, it can be useful to disable this option,
thus having separate debug symbol files. With separate debug files, you can
just move those debug files to another directory to remove Qt debug symbols.
Moving the files back will enable Qt debug symbols again.
This is useful if you rarely need to step into Qt functions during debugging,
because GDB loads much faster and uses less memory without Qt debug symbols.
In the rare case you need to step into Qt code, you can temporarily enable
debug symbols again by moving the debug files back. You can even load the Qt
debug symbols from within GDB on demand, using the "symbol-file" command.

If you are planning to compile Qt using an Icecream cluster you have to
pass the option -no-pch (no precompiled headers) to configure to make
distributed compilation work.

2. Compiling Qt
===============

To compile Qt on a Unix platform, run:

   export MAKEFLAGS=-j2
   make
   make install

If your computer has more than one core or processor, you may consider
increasing the "2" above. If you've got a compile farm available, you
should adjust the -j argument to match the number of slots in that
farm.

3. Modifying & rebuilding Qt
============================

If you make modifications to the Qt source code, you don't need to
build everything again. Simply go to the directory containing the
Makefile closest to the files you changed and run "make" again.

For example, if you've modified src/corelib/io/qiodevice.cpp, do:

   cd src/corelib
   make

If you make a change that is not temporary, you should create a Git
commit out of it. However, you shouldn't push those changes to
kde-qt.git. If you have a fix that benefit others, see the "Creating
kde-qt.git modifications" section below.

4. Building Qt examples and demos
=================================

The "-nomake examples -nomake demos" arguments to the configure script
mean that those two sections will not be configured for building,
which is unneeded for usage of the library.  If you want to compile
the examples or demos later, just enter either directory and type:

   qmake
   make

5. Build Qt tests
=================

(Official information: http://qt.gitorious.org/qt/pages/QtAutotestsEnvironment)

In order to run Qt tests, you must have a "developer build" of Qt. For
that, you need to reconfigure Qt and add the "-developer-build"
option. That option is technically equivalent to the options:

   -debug -prefix $PWD -DQT_BUILD_INTERNAL

To run a test, go to its source dir in tests/auto/testname. Type
"make" to build it, then run it (either ./tst_testname, or "make install").

6. Building Qt documentation
============================

To build and install the documentation, run:

   make docs
   ./config.status
   make install

It is necessary to do this once only, even if you rebuild Qt later.

7. Using Qt uninstalled
=======================

To use without having to install it, configure it as follows:

   ./configure <other configure options>  -prefix $PWD
   make sub-src
   make sub-tools

Attention: DO NOT run

   make install

If you do, Qt will overwrite your include/ directory with its
installation.

8. Creating kde-qt.git modifications
====================================

If you have fixed a bug in Qt or modified it in any way that may
benefit others, please share your change in the form of a patch. Do
not commit your changes directly to the main branch because they
may be lost in a future update if they have not been added to the
official Qt release.

The exception to the above rule is that if the fix has been accepted
by Qt Software (and so will appear in the very next release of Qt),
then it should be simply cherry-picked from the Qt development
branch. Note that you shouldn't do this for changes that have been
accepted into a release which is not the very next.
In this case, you should use the following command:

   git cherry-pick -x SHA1_OF_THE_FIX
where SHA1_OF_THE_FIX is the SHA-1 of the commit that you want to
introduce. Then push the change to the server.

Before creating a patch, it is recommended to contact Qt Software
support via qt-bugs@trolltech.com and explain the situation. There may
be a solution for the problem already or a new direction that should
be accounted for.

To create a patch, do the following:
  a) look at the listing of branches in
  http://qt.gitorious.org/+kde-developers/qt/kde-qt/commits/HEAD and
  select the next number.

  b) create a new branch out of a clean, released version of Qt, (for
  example, 4.5.1), using the number above and a brief description of
  your fix. For example:
      git checkout -b patches/0180-window-role v4.5.1
  You can see the available released versions of Qt with:
      git tag

  c) make your changes to the Qt source code and verify that it
  compiles, links and works (please run the respective unit tests).

  c) commit your changes to Git, using the "git commit" command. Please
  see http://qt.gitorious.org/qt/pages/GitIntroductionWithQt and
  http://qt.gitorious.org/qt/pages/QtCodingStyle for information on
  how to create commits
  Note that you can create multiple commits.

  e) merge the change to the main branch, for example, 4.5.1-patched:
      git checkout 4.5.1-patched
      git merge patches/0180-window-role

  f) push the changes you made to your branch and to the main server:
      git push git@gitorious.org:qt/kde-qt.git 4.5.1-patched patches/0180-window-role
  (Don't forget to list both branch names)

Don't forget to submit your patch to using the Qt Contribution Model,
along with the long description of the issue found. See
http://qt.gitorious.org/qt/pages/QtContributionGuidelines for
information how. You can submit the branch you've just sent to the
server.

9. Troubleshooting: Re-configuring and re-compiling
==================================================

For those updating the source in a directory where Qt has already
been compiled, you may need to run the following commands from the
top directory of your Qt sources:

	find . -name '*.moc' | xargs rm

Sometimes ./configure will refuse to run.  You may need to:
	rm .qmake.cache

If you think you may have run "make install" on an install-less Qt
(srcdir == $QTDIR), run:

	rm -rf include
	bin/syncqt
