From 39b24a10e4dee27357b9760b735c2ab98b132963 Mon Sep 17 00:00:00 2001
From: Thiago Macieira <thiago@doriath.(none)>
Date: Sun, 21 Jun 2009 13:46:54 -0300
Subject: [PATCH 11/18] Update this file to reflect the workflow with Git, as well as use Git commands
---
README.kde-qt | 163 +++++++++++++++++++++++++++++++--------------------------
1 files changed, 88 insertions(+), 75 deletions(-)
diff --git a/README.kde-qt b/README.kde-qt
index f605a0b..db3feb6 100644
--- a/README.kde-qt
+++ b/README.kde-qt
@@ -1,27 +1,20 @@
-This is a copy of Qt version 4.5.1. It may include
-modifications which are necessary for KDE; these are listed in the
-patches directory.
+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. Qt-copy patches
-==================
-
-You may also consider running the apply_patches script before configuring qt-copy,
-which will apply all not yet applied patches from the patches/ directory that
-are considered safe (they mostly include optimizations and features that don't
-add new API). Note that most of those patches haven't been accepted
-by Qt Software yet. and therefore they'll make your qt-copy differ from official
-Qt version.
-
-2. Configuring Qt
+1. Configuring Qt
=================
The recommended compile line is:
--default-config-begin--
-./configure -qt-gif -debug -fast -no-exceptions -no-separate-debug-info \
- -system-libpng -system-libjpeg -system-zlib \
- -dbus -webkit -no-phonon -plugin-sql-mysql \
- -nomake examples -nomake demos -prefix <installdir>
+
+ ./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
@@ -31,6 +24,7 @@ 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.
@@ -41,17 +35,11 @@ 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.
-It also contains the "-no-exceptions" argument, which disables C++
-exception support. Disabling exception support may improve memory
-consumption if GCC is being used. However, that also disables the
-QtXmlPatterns module since that requires exception support. If you
-plan on using that module, remove the option.
-
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.
-3. Compiling Qt
+2. Compiling Qt
===============
To compile Qt on a Unix platform, run:
@@ -65,34 +53,49 @@ 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.
-4. Modifying & rebuilding Qt
+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 modified src/corelib/io/qiodevice.cpp, do:
+For example, if you've modified src/corelib/io/qiodevice.cpp, do:
cd src/corelib
make
-Do not commit your modifications to qt-copy as such. If you have a fix
-that benefit others, see the "Creating Qt-copy patches" section below.
+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.
-5. Building Qt examples and demos
+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:
+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
-6. Building Qt documentation (only applies to Snapshot versions of Qt)
+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:
@@ -119,21 +122,25 @@ Attention: DO NOT run
If you do, Qt will overwrite your include/ directory with its
installation.
-8. Creating Qt-copy patches
-===========================
+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 qt-copy module because they
+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 next release of Qt), then
-it can be applied directly to qt-copy. In this case, the patch
-should still be placed in patches/ as usual, but it should have a
-header line
- Applied: yes
+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
@@ -141,37 +148,42 @@ be a solution for the problem already or a new direction that should
be accounted for.
To create a patch, do the following:
- a) make sure your Qt sources are clean of other changes. Run:
- svn revert -R .
- b) make your changes to the Qt source code and verify that it
- compiles, links and works.
- c) open the patches/README file and get the next patch number
- (you must read and understand the README file; if you don't, ask for
- help from other KDE developers)
- d) create the patch with:
- svn diff > patches/NNNN-short-description-of-your-patch.diff
- where NNNN is the next available number.
- e) open the file you've just created and add the header to it. The
- header should be the template in patches/README followed by a longer
- description of your patch.
-
-Don't forget to submit your patch to qt-bugs@trolltech.com along with
-the long description of the issue found, if you haven't already.
-Qt Software does not monitor the patches/ directory, so qt-copy
-patches do not get automatically applied to Qt official releases.
-
-When you receive the issue number and task tracker numbers, update the
-patch file.
-
-9. Known issues with current Qt code
-====================================
-
-In case you have strange issues with non-resizing windows and similar, use
- export QT_USE_NATIVE_WINDOWS=1
-before starting KDE.
-
-10. Troubleshooting: Re-configuring and re-compiling
-===================================================
+ 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
@@ -185,4 +197,5 @@ Sometimes ./configure will refuse to run. You may need to:
If you think you may have run "make install" on an install-less Qt
(srcdir == $QTDIR), run:
- svn revert -R include
+ rm -rf include
+ bin/syncqt
--
1.6.2.5