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

	rm src/corelib/global/qconfig.*

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