From 8d18ec4207d161d93faf694e3a4bd70fc15022bf Mon Sep 17 00:00:00 2001
From: Friedemann Kleint <Friedemann.Kleint@nokia.com>
Date: Wed, 30 May 2012 12:37:09 +0200
Subject: [PATCH] Windows: Improve install, requirements and deployment
documentation.
Change-Id: I5028b6c58cf36346904758e14711e3376cf59e3a
Reviewed-by: Casper van Donderen <casper.vandonderen@nokia.com>
---
doc/src/deployment/deployment.qdoc | 20 ++-
doc/src/external-resources.qdoc | 40 +++++
doc/src/getting-started/installation.qdoc | 188 ++++++++++++++--------
doc/src/platforms/platform-notes.qdoc | 65 +++-----
4 files changed, 192 insertions(+), 121 deletions(-)
diff --git a/doc/src/deployment/deployment.qdoc b/doc/src/deployment/deployment.qdoc
index 3f76dbcb..69184dd4 100644
--- a/doc/src/deployment/deployment.qdoc
+++ b/doc/src/deployment/deployment.qdoc
@@ -540,7 +540,7 @@
This will build Qt statically. Note that unlike with a dynamic build,
building Qt statically will result in libraries without version numbers;
- e.g. \c QtCore4.lib will be \c QtCore.lib. Also, we have used \c nmake
+ e.g. \c QtCore5.lib will be \c QtCore.lib. Also, we have used \c nmake
in all the examples, but if you use MinGW you must use
\c mingw32-make instead.
@@ -681,10 +681,13 @@
\li {2, 1} \c plugins\pnp_extrafilters.dll
\row
\li The Qt Core module
- \li {2, 1} \c qtcore4.dll
+ \li {2, 1} \c qtcore5.dll
\row
\li The Qt GUI module
- \li {2, 1} \c qtgui4.dll
+ \li {2, 1} \c qtgui5.dll
+ \row
+ \li The Qt Widgets module
+ \li {2, 1} \c qtwidgets5.dll
\endtable
In addition, the archive must contain the following compiler
@@ -726,7 +729,7 @@
in the application's own directory. Any number of additional paths
can be added.
- \section2 Visual Studio 2005 Onwards
+ \section2 Manifest files
When deploying an application compiled with Visual Studio 2005 onwards,
there are some additional steps to be taken.
@@ -807,7 +810,13 @@
\section2 Additional Libraries
Depending on configuration, compiler specific libraries must be
- redistributed along with your application. You can check which
+ redistributed along with your application.
+
+ For example, if Qt is built using \l{ANGLE}, its shared libraries
+ and the shared libraries of the \l{Direct X SDK} need to be shipped
+ as well.
+
+ You can check which
libraries your application is linking against by using the
\l{Dependency Walker} tool. All you need to do is to run it like
this:
@@ -851,6 +860,7 @@
\li \list
\li MINGWM10.DLL - The MinGW run-time
\li LIBGCC_S_DW2-1.DLL
+ \li LIBSTDC++-6.dll
\endlist
\endtable
diff --git a/doc/src/external-resources.qdoc b/doc/src/external-resources.qdoc
index 15f8e807..eaa2884d 100644
--- a/doc/src/external-resources.qdoc
+++ b/doc/src/external-resources.qdoc
@@ -88,6 +88,11 @@
\title GNU Emacs
*/
+/*!
+ \externalpage http://gnuwin32.sourceforge.net/packages.html
+ \title GnuWin32 Project
+*/
+
/*!
\externalpage http://www.amnesty.org/
\title Amnesty International
@@ -180,6 +185,11 @@
\title RFC 3986
*/
+/*!
+ \externalpage http://tdm-gcc.tdragon.net/
+ \title TDM-GCC
+*/
+
/*!
\externalpage http://www.dependencywalker.com/
\title Dependency Walker
@@ -220,6 +230,16 @@
\title ActivePerl
*/
+/*!
+ \externalpage http://code.google.com/p/angleproject/
+ \title ANGLE
+*/
+
+/*!
+ \externalpage http://msdn.microsoft.com/en-us/directx/default.aspx
+ \title Direct X SDK
+*/
+
/*!
\externalpage http://www.w3.org/TR/html401/
\title HTML 4
@@ -230,6 +250,26 @@
\title HTML 5
*/
+/*!
+ \externalpage http://site.icu-project.org/
+ \title ICU
+*/
+
+/*!
+ \externalpage http://qt-project.org/wiki/jom
+ \title jom
+*/
+
+/*!
+ \externalpage http://www.mingw.org/
+ \title MinGW
+*/
+
+/*!
+ \externalpage http://www.python.org/
+ \title Python
+*/
+
/*!
\externalpage http://pyxml.sourceforge.net/topics/xbel/
\title XML Bookmark Exchange Language Resource Page
diff --git a/doc/src/getting-started/installation.qdoc b/doc/src/getting-started/installation.qdoc
index 2e9a12cf..acc76f55 100644
--- a/doc/src/getting-started/installation.qdoc
+++ b/doc/src/getting-started/installation.qdoc
@@ -167,9 +167,6 @@ for your platform from the following list.
consult the installation instructions provided instead of the ones in
this document.
- Open Source Versions of Qt is not officially supported for use with
- any version of Visual Studio. Integration with Visual Studio is available
- as part of the \l{Qt Commercial Edition}.
\section1 Step 1: Install the License File (commercial editions only)
@@ -193,56 +190,73 @@ for your platform from the following list.
\section1 Step 3: Set the Environment variables
- In order to build and use Qt, the \c PATH environment variable needs to be
- extended:
+ We recommend creating a desktop link that opens a command
+ prompt with the environment set up similar to the
+ \uicontrol{Command Prompt} menu entries provided by the Windows SDKs.
+ This is done by creating an application link passing a \c .cmd file setting
+ up the environment and the command line option \c /k (remain open)
+ to \c cmd.exe.
-\snippet doc/src/snippets/code/doc_src_installation.qdoc 7
+ Assuming the file is called \c{qt5vars.cmd}
+ and the Qt folder is called \c qt-5 and located under \c C:\qt:
- This is done by adding \c{c:\Qt\%VERSION%\bin} to the \c PATH variable.
+ \code
+ REM Set up Windows SDK for 64bit
+ CALL "C:\Program Files (x86)\MSVC10\VC\vcvarsall.bat" amd64
+ set PATH=c:\qt\qt-5\qtbase\bin;c:\qt\qt-5\qtrepotools\bin;c:\qt\qt-5\gnuwin32\bin;%PATH%
+ set QMAKESPEC=win32-msvc2010
+ \endcode
- For newer versions of Windows, \c PATH can be extended through
- the \menu{Control Panel|System|Advanced|Environment variables} menu.
+ A desktop link can then be created by specifying the command
+ \c{%SystemRoot%\system32\cmd.exe /E:ON /V:ON /k c:\qt\qt5vars.cmd}
+ as application and \c{c:\qt\qt-5} as working directory.
- You may also need to ensure that the locations of your compiler and
- other build tools are listed in the \c PATH variable. This will depend
- on your choice of software development environment.
+ \note Setups for MinGW are similar; they differ
+ only in that the \c bin folder of the installation should be added to the
+ path instead of calling the Windows SDK setup script. For MinGW, please make
+ sure that no \c sh.exe can be found in the path, as it affects \c {mingw32-make}.
- \note If you don't use the configured shells, which is
- available in the application menu, in the \l{Open Source Versions of Qt},
- \c configure requires that \c sh.exe is not in the path
- or that it is run from \c msys. This also goes for mingw32-make.
+ Settings required by the additional libraries (see \l{Qt for Windows Requirements})
+ should also go this file below the call to the Windows SDK setup script.
\section1 Step 4: Build the Qt Library
+ The default behavior of configure is to create an in-source build
+ of Qt 5. If you want to install Qt 5 to a separate location,
+ you need to specify the command line option \c{-prefix <location>}.
+ Alternatively, the command line option \c -developer-build creates
+ an in-source build for developer usage.
- To configure the Qt library for your machine, type the following command
- in a \b{Visual Studio} command prompt:
+ To configure the Qt library for a debug build for your machine, type
+ the following command in the command prompt:
-\snippet doc/src/snippets/code/doc_src_installation.qdoc 8
+ \code
+ configure -debug -nomake examples -opensource
+ \endcode
Type \c{configure -help} to get a list of all available options. The
\l{Configuration Options for Qt} page gives a brief overview of these.
- If you have multiple compilers installed, and want to build the Qt library
- using a specific compiler, you must specify a \c qmake specification.
- This is done by pasing \c{-platform <spec>} to configure; for example:
+ To build Qt using \l{jom}, type:
+
+ \code
+ jom
+ \endcode
-\snippet doc/src/snippets/code/doc_src_installation.qdoc 9
+ If you do not have \l{jom} installed, type:
- In some cases you need to set up the compilation environment before running
- configure in order to use the right compiler. For instance, you need to do this
- if you have Visual Studio 2005 installed and want to compile Qt using the x64
- compiler because the 32-bit and 64-bit compiler both use the same
- \c qmake specification file.
- This is usually done by selecting
- \menu{Microsoft Visual Studio 2005|Visual Studio Tools|<Command Prompt>}
- from the \gui Start menu.
+ \code
+ nmake
+ \endcode
- The actual commands needed to build Qt depends on your development
- system. For Microsoft Visual Studio to create the library and
- compile all the examples, tools and tutorials type:
+ For MinGW, type:
-\snippet doc/src/snippets/code/doc_src_installation.qdoc 10
+ \code
+ mingw32-make
+ \endcode
+
+ If an installation prefix was given, type
+ \c{jom install}, \c{nmake install} or \c{mingw32-make install}.
\note If you later need to reconfigure and rebuild Qt from the
same location, ensure that all traces of the previous configuration are
@@ -254,9 +268,8 @@ for your platform from the following list.
\section1 Qt Demos and Examples
If you are new to Qt, we suggest that you take a look at the
- examples to see Qt in action. Run the Qt Examples
- either by typing \c qtdemo on the command line or through the
- desktop's Start menu.
+ examples to see Qt in action (provided in the \c examples folder
+ of each module).
You might also want to try the following links:
@@ -537,50 +550,87 @@ in the \l{Qt for Windows CE Requirements} document.
\brief Setting up the Windows environment for Qt.
\previouspage General Qt Requirements
- If you are using a binary version of Qt with Visual Studio 2005, you must
- first install the Visual Studio Service Pack 1 available
- \l{http://www.microsoft.com/downloads/details.aspx?FamilyId=BB4A75AB-E2D4-4C96-B39D-37BAF6B5B1DC&displaylang=en}{here}
- to avoid runtime conflicts.
- Additionally, you must use the Check for Updates feature in the Help menu of the Visual Studio 2005 IDE to apply at least the following security updates: KB937061, KB971023, KB971090, KB973673.
+ \section1 Graphics Drivers
+
+ For QML2 to work, a graphics driver that provides OpenGL 2.1 or higher is required.
+ The Windows default driver provides only OpenGL 1.1, which is not sufficient.
- If you are using a source edition of Qt, you must first install Perl so
- that the syncqt script invoked by configure can be executed. You can download
- this \l{http://www.activestate.com/downloads/}{here}.
+ Alternatively, \l{ANGLE} can be used, which provides
+ Open GL ES 2.0 by converting the calls to DirectX.
- To build Qt with Phonon on Windows, you require:
+ \section1 Libraries
\list
- \li Microsoft's DirectX Software Development Kit which can be
- downloaded
- \l{http://msdn2.microsoft.com/en-us/directx/aa937788.aspx}{here}, and
- \li Microsoft's Windows Server 2003 R2 Platform SDK which is available
- \l{http://www.microsoft.com/downloads/details.aspx?FamilyID=0baf2b35-c656-4969-ace8-e4c0c0716adb&DisplayLang=en}{here}.
+ \li \l{ICU}: Qt 5 can make use of the ICU library for
+ UNICODE and Globalization support (required for QtWebKit).
+ At compile time, the include and lib folders of the ICU installation must be appended to
+ the \c INCLUDE and \c LIB environment variables.
+ At run-time, the ICU DLLs need to be found. This can be achieved by copying
+ the DLLs to the application folder or adding the bin folder of
+ the ICU installation to the \c PATH environment variable.
+
+ \li \l{ANGLE}: This library converts
+ OpenGL ES 2.0 API calls to DirectX 9, removing the need to install
+ graphics drivers on the target machines.
+ \l{http://code.google.com/p/angleproject/wiki/DevSetup}{Building}
+ the library requires the installation of the
+ \l{Direct X SDK}.
+
+ Pass the command line options \c{-opengl es2 -angle <folder>} to \c configure
+ to use it.
+
+ \note When building for 64bit, de-activate the \c WarnAsError option
+ in every project file (as otherwise integer conversion warnings will
+ break the build).
\endlist
- \section1 QtWebKit Dependencies
+ \section1 Development tools
- QtWebKit depends on some extra development tools in addition to those required for the rest of Qt.
+ \list
+ \li Install a recent version of ActivePerl
+ and add the installation location to your PATH.
+ \note Please make sure the perl executable is found in the path before
+ the perl executable provided by msysgit, since the latter is outdated.
- \note These dependencies are only needed if you use a source version of Qt.
- They are not required when using a prebuilt library.
+ \li Install Python from \l{http://www.python.org/download/}{here}
+ and add the installation location to your PATH in order to be able
+ to build QtJsBackend and QtWebKit.
+
+ \li \l{jom} is a replacement for \c nmake which makes use of all CPU cores
+ and thus speeds up building.
+ \endlist
+
+ QtWebKit depends on some extra tools from the \l{GnuWin32 Project}
+ which are provided for your convenience in the \c gnuwin32/bin folder:
\list
- \li Install \l{http://www.activestate.com/Products/ActivePerl/}{ActiveState Perl}
- \li Install \l{http://www.python.org/download/}{Python 2.x}
- (and add the installation location to your PATH)
- \li In addition, you need these external GNU tools from the
- \l{http://gnuwin32.sourceforge.net/packages.html}{GnuWin32 Project}:
- \list
- \li \l{http://gnuwin32.sourceforge.net/downlinks/bison.php}{Bison}
- \li \l{http://gnuwin32.sourceforge.net/downlinks/gperf.php}{GPerf}
- \li \l{http://gnuwin32.sourceforge.net/downlinks/flex.php}{Flex}
- \li \l{http://gnuwin32.sourceforge.net/downlinks/libiconv.php}{LibIconv} (needed for bison)
- \endlist
+ \li \l{http://gnuwin32.sourceforge.net/downlinks/bison.php}{Bison}
+ \li \l{http://gnuwin32.sourceforge.net/downlinks/gperf.php}{GPerf}
+ \li \l{http://gnuwin32.sourceforge.net/downlinks/flex.php}{Flex}
+ \endlist
+
+ The folder should be added to the PATH.
+
+ \section1 SDKs and Compilers
+
+ \list
+ \li Windows SDK 7.1 with Visual Studio 2010 SP1 (recommended).
+ As of 16.3.2012, installing the SDK requires installing the following packages
+ in this order (see \c readme.html provided with the service pack):
+ \list
+ \li Install Visual Studio 2010
+ \li Install Windows SDK 7.1
+ \li Install Visual Studio 2010 SP1
+ \li Install Visual C++ 2010 SP1 Compiler Update for the Windows SDK 7.1
+ \endlist
+ \li Windows SDK 7 with Visual Studio 2008
+ \li MinGW or \l{TDM-GCC} with g++ version 4.6 or higher (not supported for all modules).
\endlist
- Please make sure that you install all the tools in a path without spaces in it.
+ Qt Phonon on Windows additionally requires the \l{Direct X SDK}.
- For the most up to date information about QtWebKit dependencies, please refer to the \l{http://trac.webkit.org/wiki/BuildingQtOnWindows}{QtWebKit wiki for Windows}
+ For the most up to date information about QtWebKit dependencies,
+ please refer to the \l{http://trac.webkit.org/wiki/BuildingQtOnWindows}{QtWebKit wiki for Windows}.
\sa {Known Issues}
*/
diff --git a/doc/src/platforms/platform-notes.qdoc b/doc/src/platforms/platform-notes.qdoc
index 2c2c3631..e052b000 100644
--- a/doc/src/platforms/platform-notes.qdoc
+++ b/doc/src/platforms/platform-notes.qdoc
@@ -385,12 +385,12 @@
\tableofcontents
- \section1 Windows Vista
+ \section1 Windows Vista, Windows 7, Windows 8
- At the time Qt %VERSION% was released, there were no known Vista-specific issues.
+ At the time Qt %VERSION% was released, there were no known issues on these
+ platforms.
- \target Windows NT
- \section1 Windows XP, Windows 2000 and Windows NT
+ \section1 Windows XP
\section2 Installation location
@@ -410,22 +410,8 @@
\section2 GCC (MinGW)
We have tested Qt with this compiler on Windows XP.
- The minimal version of MinGW supported is GCC 4.4.
-
- \note For users of the MinGW binary package: This package is now
- based on MinGW 4.4. The installer no longer offers to download
- MinGW for you, but rather offers to use a version of MinGW that
- you already have installed on your machine. You just tell the
- installer which directory MinGW is installed in. If you don't
- already have MinGW 4.4 installed, you can download a .zip archive
- from our \l{ftp://ftp.qt.nokia.com/misc/MinGW-gcc440_1.zip}{FTP
- site}. This archive provides fixes to MinGW and support for
- missing API, See the _patches directory in the archive for
- details.
-
- \note A MinGW installation is only needed to build against the
- binary package, not to run the pre-compiled binaries that are in
- the package.
+ The minimal version of MinGW
+ supported is GCC 4.6. For 64 bit builds, \l{TDM-GCC} can be used.
\section2 Intel C++ Compiler (Windows, Altix)
@@ -438,22 +424,19 @@
applications Version 8.1 Build 20050406 Package ID: l_cc_pc_8.1.030
\endlist
- We currently only test the Intel compiler on 32-bit Windows versions.
-
\section2 Visual Studio (Windows)
- We do most of our Windows development on Windows XP, using Microsoft
- Visual Studio .NET 2005 and Visual Studio 2008 (both the 32- and 64-bit
- versions).
+ We do most of our Windows development on Windows 7, using Microsoft
+ Visual Studio 2008, Visual Studio 2010 or Visual Studio 11 (mostly
+ 64bit).
+
+ We recommend using Visual Studio 2010 or higher as it supports some
+ C++11 features beneficial to performance and memory usage.
- Qt works with the Standard Edition, the Professional Edition and Team
- System Edition of Visual Studio 2005.
+ Qt works with all editions of Visual Studio.
- In order to use Qt with the Visual Studio 2005/2008 Express Edition you need
- to download and install the platform SDK. Due to limitations in the
- Express Edition it is not possible for us to install the Qt Visual
- Studio Integration. You will need to use our command line tools to
- build Qt applications with this edition.
+ In order to use Qt with the Visual Studio Express Editions
+ you need to download and install the Windows SDK.
The Visual C++ Linker doesn't understand filenames with spaces (as in
\c{C:\Program files\Qt\}) so you will have to move it to another place,
@@ -466,21 +449,9 @@
then you will need to recompile Qt with the flags set for the
application as well.
- If you're using Visual Studio .NET (2002) Standard Edition, you should be
- using the Qt binary package provided, and not the source package.
- As the Standard Edition does not optimize compiled code, your compiled
- version of Qt would perform suboptimally with respect to speed.
-
- With Visual Studio 2005 Service Pack 1 a bug was introduced which
- causes Qt not to compile, this has been fixed with a hotfix available
- from Microsoft. See this
- \l{http://qt.nokia.com/developer/faqs/faq.2006-12-18.3281869860}{Knowledge Base entry}
- for more information.
-
- There currently is a problem when compiling Qt with Visual Studio 2010 for 64-bit.
- Its optimizer causes trouble and generates code that crashes for the release builds.
- To avoid the crashes, You need to apply the hotfix in the following article
- http://support.microsoft.com/kb/2280741.
+ Visual Studio 2010 should be updated to Service Pack 1. Otherwise, a
+ problem when compiling Qt for 64-bit in release mode may occur (see
+ http://support.microsoft.com/kb/2280741).
*/
/*!
--
GitLab