Doc: compiling Qt and Qt Creator on Windows

Reviewed-by: con
Reviewed-by: Friedemann Kleint

1 files changed, 144 insertions, 22 deletions

diff --git a/README b/README
index 973534fdd5..80bf6d81c1 100644
--- a/README
+++ b/README
@@ -1,14 +1,14 @@
 Qt Creator
 ==========
-Qt Creator is a crossplatform C++ IDE for development with the Qt framework.
+Qt Creator is a cross-platform C++ IDE for development with the Qt framework.
 
 Supported Platforms
 ===================
 The binary packages support the following platforms:
 
-Windows XP SP2, Windows Vista
-(K)Ubuntu Linux 7.04 32bit and 64bit
-Mac OS 10.5 and later
+Windows 7, Windows XP SP2, Windows Vista
+(K)Ubuntu Linux 8.04 (32-bit and 64-bit) or later
+Mac OS 10.5 or later
 
 Building the sources requires Qt 4.7.0 or later.
 
@@ -16,43 +16,165 @@ Compiling Qt Creator
 ====================
 Prerequisites:
    * Qt 4.7
-   * On Windows: mingw 4.4 or later, Visual Studio 2008 or later
-   * On Mac: XCode 2.5 or later, compiling on 10.4 requires to set the
+   * On Windows:
+     -  ActiveState Active Perl (version 5.8.9 for Symbian development)
+     -  MinGW 4.4 or later, Visual Studio 2008 or later
+     -  jom
+     The Qt SDK provides you with most of the required software.
+   * On Mac: XCode 2.5 or later, compiling on 10.4 requires setting the
      environment variable QTC_TIGER_COMPAT before running qmake
 
 We recommend that you build Qt Creator not in the source directory, but in a
 separate directory. To do that, use the following commands:
+
 mkdir $BUILD_DIRECTORY
 cd $BUILD_DIRECTORY
 qmake $SOURCE_DIRECTORY/qtcreator.pro
 make (or mingw32-make or nmake or jom, depending on your platform)
 
-QmlDesigner requires private headers from Qt 4.7.1
---------------------------------------------------
+Compiling Qt Quick Designer
+---------------------------
 
-The QmlDesigner plugin depends on "private" headers from Qt 4.7.1, specifically from
-the  QtDeclarative module. These private headers always end with an "_p.h", and Nokia
-does not make any promises to keep the files or API's binary or source compatible
-between releases. This means that when compiled, the plugin has a dependency to the
-exact Qt version it was compiled with. Running Qt Creator with the plugin against
-updated Qt libraries (also for patch releases) might lead to link time failures,
-or even crashes.
+Qt Quick Designer (QmlDesigner plugin) depends on "private" headers from Qt
+4.7.1, specifically from the QtDeclarative module. These private headers always
+end with an "_p.h". Nokia does not promise to keep these files or APIs binary
+or source compatible between releases. This means that when compiled, the
+plugin has a dependency to the exact Qt version it was compiled with. Running
+Qt Creator with the plugin against updated Qt libraries (also for patch
+releases) might lead to link time failures, or even crashes.
 
 If you want to disable the plugin, you can pass "QT_PRIVATE_HEADERS=" to qmake:
 
   qmake "QT_PRIVATE_HEADERS=" $SOURCE_DIRECTORY/qtcreator.pro
 
-Anyhow, the plugin will not be compiled when the private header files needed
-are not found. This might be the case when you are using a Qt version from your
-distribution, or when you installed your self-compiled Qt to a separate
-directory via 'make install'. You can fix this by either re-building your Qt
-with the "-developer-build" configure option, or pass the include directory in
-the source directory to qmake, e.g.
+The plugin is not compiled if the private header files are not found. This
+might be the case when you use a Qt version from your distribution, or
+installed a self-compiled Qt to a separate directory via 'make install'. You
+can fix this by either re-building your Qt with the "-developer-build"
+configure option, or by passing the include directory in the source directory
+to qmake. For example:
 
   qmake "QT_PRIVATE_HEADERS=$$QT_SOURCE_TREE/include" $SOURCE_DIRECTORY/qtcreator.pro
 
 
-Third-party components
+Compiling Qt and Qt Creator on Windows
+--------------------------------------
+
+This section provides step by step instructions for compiling the latest
+versions of Qt and Qt Creator on Windows. Alternatively, to avoid having to
+compile Qt yourself, you can use one of the versions of Qt shipped with the Qt
+SDK (release builds of Qt using MinGW and Visual C++ 2008).
+
+   1.  Decide which compiler to use: MinGW or Microsoft Visual Studio. If you
+       plan to contribute to Qt Creator, you should compile your changes with
+       both compilers.
+
+   2.  Install msysGit from http://code.google.com/p/msysgit/. If you plan to
+       use the MinGW compiler suite, do not choose to put git in the
+       default path of Windows command prompts. For more information, see
+       step 9.
+
+   3.  Create a working directory under which to check out Qt and Qt Creator,
+       for example, c:\work. If you plan to use MinGW and Microsoft Visual
+       Studio simultaneously or mix different Qt versions, we recommend
+       creating a directory structure which reflects that. For example:
+       C:\work\qt4.7.1-vs10, C:\work\qt4.7.2-mingw.
+
+   4.  Download and install Perl from http://www.activestate.com/activeperl
+       and check that perl.exe is added to the path.
+
+   5.  In the working directory, check out the respective branch of Qt
+       (we recommend 4.7; see http://qt.gitorious.org/qt).
+
+   6.  Check out Qt Creator (master branch, see
+       http://qt.gitorious.org/qt-creator).
+       You should now have the directories qt and creator under your working
+       directory.
+
+   7.  Install a compiler:
+       - For MinGW (4.4 onwards), see http://www.mingw.org/. Note that gcc 4.5
+         produces insufficient debugging information, and therefore, we
+         recommend that you use gcc 4.4 for debugging.
+
+       - For Microsoft Visual C++, install the Windows SDK and the "Debugging
+         Tools for Windows" from the SDK image. We strongly recommend using the
+         64-bit version and 64-bit compilers on 64-bit systems.
+
+         When using Visual C++ 2010, you must apply a hotfix that is available
+         from http://support.microsoft.com/kb/2280741
+         (See http://bugreports.qt.nokia.com/browse/QTBUG-11445).
+
+         For the Visual C++ compilers, it is recommended to use the tool 'jom'.
+         It is a replacement for nmake that utilizes all CPU cores and thus
+         speeds up compilation significantly. Download it from
+         ftp://ftp.qt.nokia.com/jom/ and add the executable to the path.
+
+   8.  For convenience, we recommend creating shell prompts with the correct
+       environment. This can be done by creating a .bat-file
+       (such as, <working_directory>\qtvars.bat) that contains the environment
+       variable settings.
+       A .bat-file for MinGW looks like:
+
+         set QTDIR=<working_directory>\qt
+         set PATH=%QTDIR%\bin;<path_to_mingw>\bin;<working_directory>\creator\bin;%PATH%
+         set QMAKESPEC=win32-g++
+
+       For the Visual C++ compilers, call the .bat file that sets up the
+       environment for the compiler (provided by the Windows SDK or the
+       compiler):
+
+         CALL "C:\Program Files (x86)\MSVC10\VC\vcvarsall.bat" amd64
+         set QTDIR=<working_directory>\qt
+         set PATH=%QTDIR%\bin;<working_directory>\creator\bin;%PATH%
+         set QMAKESPEC=win32-msvc2010
+
+       You can create desktop links to the bat files using the working
+       directory and specifying
+
+       %SystemRoot%\system32\cmd.exe /E:ON /V:ON  /k <working_directory>\qtvars.bat
+
+   9.  When using MinGW, open the shell prompt and enter:
+
+       sh.exe
+
+       That should result in a 'sh is not recognized as internal or external
+       command...' error. If a sh.exe is found, the compile process will fail.
+       You have to remove it from the path.
+
+  10.  You are now ready to configure and build Qt and Qt Creator.
+       To use MinGW, open the the shell prompt and enter:
+
+         cd qt
+         configure -debug && mingw32-make -s
+         cd ..\creator
+         qmake && mingw32-make -s
+
+       To use the Visual C++ compilers, enter:
+
+         cd qt
+         configure -debug && jom
+         cd ..\creator
+         qmake && jom
+
+   11. To launch Qt Creator, enter:
+       qtcreator
+
+   12. When using  Visual C++ with the "Debugging Tools for Windows" installed,
+       the extension library qtcreatorcdbext.dll to be loaded into the
+       Windows console debugger (cdb.exe) should have been built under
+       lib\qtcreatorcdbext32 or lib\qtcreatorcdbext64.
+       When using a 32 bit-build of Qt Creator with the 64 bit version of the
+       "Debugging Tools for Windows" the library should also be built with
+       a 64 bit compiler (rebuild src\libs\qtcreatorcdbext using a 64 bit
+       compiler).
+
+Note that unlike on Unix, you cannot overwrite executables that are running.
+Thus, if you want to work on Qt Creator using Qt Creator, you need a
+separate build of it. We recommend using a separate, release-built version
+of Qt and Qt Creator to work on a debug-built version of Qt and Qt Creator
+or using shadow builds.
+
+Third-party Components
 ======================
 Qt Creator includes the following third-party components,
 we thank the authors who made this possible: