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 the Qt developers (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.

In all other cases, before creating a patch, it is recommended to
contact the Qt developers via a new task in
http://bugreports.qt.nokia.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 from
  tests/auto in the source tree).

  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 are allowed to create as many commits as necessary to
  accomplish a working change that can be easily reviewed.

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

  f) merge the patch branch to master:
      git checkout master
      git merge 4.5.1-patched

  g) push the changes you made to your branch and to the main server:
      git push git@gitorious.org:qt/kde-qt.git master 4.5.1-patched patches/0180-window-role
  (Don't forget to list all 3 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

10. Maintenance: updating kde-qt to a newer Qt version
======================================================

When a new version of Qt is released, do the following to update the
repository (assuming Qt 4.6.1 is the release you're updating to):

 a) rebase each of the individual patches against this new version.
      for branch in patches/*; do
        git checkout -b $branch origin/$branch
        git rebase v4.6.1
        resolve conflicts
      done   # Note: pseudo-shell, don't try to run this

    If a given branch is no longer valid (it's been applied to this Qt
    version), then delete it on the server:
      git push origin :$branch

 b) create a new "patched" branch locally, starting on the release tag:
      git checkout -b 4.6.1-patched v4.6.1

 c) merge the patch branches and the README branch, one by one. There
    should be no conflicts at this stage; if there are, it indicates
    one patch conflicts with another.
      git merge patches/0997-patch1
      git merge patches/0998-patch2
      git merge patches/0999-patch3
      # etc.
      git merge README

 d) overwrite the master branch's contents with the new branch. If the
    Git merge strategy "theirs" exist (it doesn't as of Git 1.6), use
    it:
      git checkout master
      git merge -s theirs 4.6.1-patched

    If it doesn't exist, do the equivalent by inverting the point of
    view:
      git checkout -b tmp 4.6.1-patched
      git merge -s ours master
      git checkout master
      git merge tmp
      git branch -d tmp

    Also possible using Git plumbing:
      git checkout master
      git merge -s ours --no-commit 4.6.1-patched
      rm .git/index
      git read-tree 4.6.1-patched
      git commit

  e) push everything to kde-qt.git, including the new Qt. Note that
     the individiual patch branches will require force, because they
     have been rebased (that is, the new branch tip is no longer a
     direct descendant of the previous tip).

      # Push the individual patch branches with force
      git push -f origin patches/0997-patch1 patches/0998-patch2 patches/0999-patch3 etc
      # Push the tag, the new patched branch and master
      git push v4.6.1 4.6.1-patched master
