pluginhowto: update example code
[qt-creator:qt-creator-instrumentation.git] / README
1 Qt Creator
2 ==========
3 Qt Creator is a cross-platform C++ IDE for development with the Qt framework.
4
5 Supported Platforms
6 ===================
7 The binary packages support the following platforms:
8
9 Windows 7, Windows XP SP2, Windows Vista
10 (K)Ubuntu Linux 8.04 (32-bit and 64-bit) or later
11 Mac OS 10.5 or later
12
13 Building the sources requires Qt 4.7.1 or later.
14
15 Compiling Qt Creator
16 ====================
17 Prerequisites:
18    * Qt 4.7.1
19    * On Windows:
20      -  ActiveState Active Perl (version 5.8.9 for Symbian development)
21      -  MinGW 4.4 or later, Visual Studio 2008 or later
22      -  jom
23      The Qt SDK provides you with most of the required software.
24    * On Mac: XCode 2.5 or later, compiling on 10.4 requires setting the
25      environment variable QTC_TIGER_COMPAT before running qmake
26
27 We recommend that you build Qt Creator not in the source directory, but in a
28 separate directory. To do that, use the following commands:
29
30 mkdir $BUILD_DIRECTORY
31 cd $BUILD_DIRECTORY
32 qmake $SOURCE_DIRECTORY/qtcreator.pro
33 make (or mingw32-make or nmake or jom, depending on your platform)
34
35 Compiling Qt Quick Designer
36 ---------------------------
37
38 Qt Quick Designer (QmlDesigner plugin) depends on "private" headers from Qt
39 4.7.1, specifically from the QtDeclarative module. These private headers always
40 end with an "_p.h". Nokia does not promise to keep these files or APIs binary
41 or source compatible between releases. This means that when compiled, the
42 plugin has a dependency to the exact Qt version it was compiled with. Running
43 Qt Creator with the plugin against updated Qt libraries (also for patch
44 releases) might lead to link time failures, or even crashes.
45
46 If you want to disable the plugin, you can pass "QT_PRIVATE_HEADERS=" to qmake:
47
48   qmake "QT_PRIVATE_HEADERS=" $SOURCE_DIRECTORY/qtcreator.pro
49
50 The plugin is not compiled if the private header files are not found. This
51 might be the case when you use a Qt version from your distribution, or
52 installed a self-compiled Qt to a separate directory via 'make install'. You
53 can fix this by either re-building your Qt with the "-developer-build"
54 configure option, or by passing the include directory in the source directory
55 to qmake. For example:
56
57   qmake "QT_PRIVATE_HEADERS=$$QT_SOURCE_TREE/include" $SOURCE_DIRECTORY/qtcreator.pro
58
59
60 Compiling Qt and Qt Creator on Windows
61 --------------------------------------
62
63 This section provides step by step instructions for compiling the latest
64 versions of Qt and Qt Creator on Windows. Alternatively, to avoid having to
65 compile Qt yourself, you can use one of the versions of Qt shipped with the Qt
66 SDK (release builds of Qt using MinGW and Visual C++ 2008).
67
68    1.  Decide which compiler to use: MinGW or Microsoft Visual Studio. If you
69        plan to contribute to Qt Creator, you should compile your changes with
70        both compilers.
71
72    2.  Install msysGit from http://code.google.com/p/msysgit/. If you plan to
73        use the MinGW compiler suite, do not choose to put git in the
74        default path of Windows command prompts. For more information, see
75        step 9.
76
77    3.  Create a working directory under which to check out Qt and Qt Creator,
78        for example, c:\work. If you plan to use MinGW and Microsoft Visual
79        Studio simultaneously or mix different Qt versions, we recommend
80        creating a directory structure which reflects that. For example:
81        C:\work\qt4.7.1-vs10, C:\work\qt4.7.2-mingw.
82
83    4.  Download and install Perl from http://www.activestate.com/activeperl
84        and check that perl.exe is added to the path.
85
86    5.  In the working directory, check out the respective branch of Qt
87        (we recommend 4.7; see http://qt.gitorious.org/qt).
88
89    6.  Check out Qt Creator (master branch, see
90        http://qt.gitorious.org/qt-creator).
91        You should now have the directories qt and creator under your working
92        directory.
93
94    7.  Install a compiler:
95        - For MinGW (4.4 onwards), see http://www.mingw.org/. Note that gcc 4.5
96          produces insufficient debugging information, and therefore, we
97          recommend that you use gcc 4.4 for debugging.
98
99        - For Microsoft Visual C++, install the Windows SDK and the "Debugging
100          Tools for Windows" from the SDK image. We strongly recommend using the
101          64-bit version and 64-bit compilers on 64-bit systems.
102
103          When using Visual C++ 2010, you must apply a hotfix that is available
104          from http://support.microsoft.com/kb/2280741
105          (See http://bugreports.qt.nokia.com/browse/QTBUG-11445).
106
107          For the Visual C++ compilers, it is recommended to use the tool 'jom'.
108          It is a replacement for nmake that utilizes all CPU cores and thus
109          speeds up compilation significantly. Download it from
110          ftp://ftp.qt.nokia.com/jom/ and add the executable to the path.
111
112    8.  For convenience, we recommend creating shell prompts with the correct
113        environment. This can be done by creating a .bat-file
114        (such as, <working_directory>\qtvars.bat) that contains the environment
115        variable settings.
116        A .bat-file for MinGW looks like:
117
118          set QTDIR=<working_directory>\qt
119          set PATH=%QTDIR%\bin;<path_to_mingw>\bin;<working_directory>\creator\bin;%PATH%
120          set QMAKESPEC=win32-g++
121
122        For the Visual C++ compilers, call the .bat file that sets up the
123        environment for the compiler (provided by the Windows SDK or the
124        compiler):
125
126          CALL "C:\Program Files (x86)\MSVC10\VC\vcvarsall.bat" amd64
127          set QTDIR=<working_directory>\qt
128          set PATH=%QTDIR%\bin;<working_directory>\creator\bin;%PATH%
129          set QMAKESPEC=win32-msvc2010
130
131        You can create desktop links to the bat files using the working
132        directory and specifying
133
134        %SystemRoot%\system32\cmd.exe /E:ON /V:ON  /k <working_directory>\qtvars.bat
135
136    9.  When using MinGW, open the shell prompt and enter:
137
138        sh.exe
139
140        That should result in a 'sh is not recognized as internal or external
141        command...' error. If a sh.exe is found, the compile process will fail.
142        You have to remove it from the path.
143
144   10.  You are now ready to configure and build Qt and Qt Creator.
145        To use MinGW, open the the shell prompt and enter:
146
147          cd qt
148          configure -debug && mingw32-make -s
149          cd ..\creator
150          qmake && mingw32-make -s
151
152        To use the Visual C++ compilers, enter:
153
154          cd qt
155          configure -debug && jom
156          cd ..\creator
157          qmake && jom
158
159    11. To launch Qt Creator, enter:
160        qtcreator
161
162    12. When using  Visual C++ with the "Debugging Tools for Windows" installed,
163        the extension library qtcreatorcdbext.dll to be loaded into the
164        Windows console debugger (cdb.exe) should have been built under
165        lib\qtcreatorcdbext32 or lib\qtcreatorcdbext64.
166        When using a 32 bit-build of Qt Creator with the 64 bit version of the
167        "Debugging Tools for Windows" the library should also be built with
168        a 64 bit compiler (rebuild src\libs\qtcreatorcdbext using a 64 bit
169        compiler).
170
171 Note that unlike on Unix, you cannot overwrite executables that are running.
172 Thus, if you want to work on Qt Creator using Qt Creator, you need a
173 separate build of it. We recommend using a separate, release-built version
174 of Qt and Qt Creator to work on a debug-built version of Qt and Qt Creator
175 or using shadow builds.
176
177 Third-party Components
178 ======================
179 Qt Creator includes the following third-party components,
180 we thank the authors who made this possible:
181
182 * Open Source front-end for C++ (license MIT), enhanced for use in Qt Creator
183
184   Roberto Raggi <roberto.raggi@gmail.com>
185
186   QtCreator/src/shared/cplusplus
187
188   Copyright 2005 Roberto Raggi <roberto@kdevelop.org>
189
190   Permission to use, copy, modify, distribute, and sell this software and its
191   documentation for any purpose is hereby granted without fee, provided that
192   the above copyright notice appear in all copies and that both that
193   copyright notice and this permission notice appear in supporting
194   documentation.
195
196   The above copyright notice and this permission notice shall be included in
197   all copies or substantial portions of the Software.
198
199   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
200   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
201   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
202   KDEVELOP TEAM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
203   AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
204   CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
205
206
207 * Botan, a C++ crypto library. Version 1.8.8
208
209   Copyright (C) 1999-2004 The Botan Project. All rights reserved.
210   Copyright (C) 1999-2009 Jack Lloyd
211   2001 Peter J Jones
212   2004-2007 Justin Karneges
213   2005 Matthew Gregan
214   2005-2006 Matt Johnston
215   2006 Luca Piccarreta
216   2007 Yves Jerschow
217   2007-2008 FlexSecure GmbH
218   2007-2008 Technische Universitat Darmstadt
219   2007-2008 Falko Strenzke
220   2007-2008 Martin Doering
221   2007 Manuel Hartl
222   2007 Christoph Ludwig
223   2007 Patrick Sona
224   All rights reserved.
225
226   Redistribution and use in source and binary forms, with or without
227   modification, are permitted provided that the following conditions are met:
228
229   1. Redistributions of source code must retain the above copyright notice,
230   this list of conditions, and the following disclaimer.
231
232   2. Redistributions in binary form must reproduce the above copyright notice,
233   this list of conditions, and the following disclaimer in the documentation
234   and/or other materials provided with the distribution.
235
236   THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) "AS IS" AND ANY EXPRESS OR IMPLIED
237   WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
238   MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE DISCLAIMED. IN NO
239   EVENT SHALL THE AUTHOR(S) OR CONTRIBUTOR(S) BE LIABLE FOR ANY DIRECT,
240   INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
241   (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
242   LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
243   ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
244   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
245   SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
246
247   The source code of Botan C++ crypto library can be found in
248   QtCreator/src/libs/3rdparty
249
250
251 * NetSieben SSH Library is a Secure Shell client library for C++. Version 1.3.2
252
253   Commercial License: For organizations who do not want to release the source
254   code for their applications as open source/ free software; in other words
255   they do not want to comply with the GNU General Public License (GPL) or Q
256   Public License.
257
258   Non Commercial / Open Source License: NetSieben believes in contributing back
259   to the open source community, thus it has released the SSH Library under Q
260   Public License as it is defined by Trolltech AS of Norway. The Open Source
261   License allows the user to use software under an open source / free software
262   license, and distribute it freely. The software can be used at no charge with
263   the condition that if the user uses the SSH Library in an application they
264   wish to redistribute, then the complete source code for your application must
265   be available and freely redistributable under reasonable conditions. For more
266   information on the used QPL License see:
267   QtCreator/src/libs/3rdparty/net7ssh/LICENSE.QPL
268
269   The source code of NetSieben Secure Shell C++ Library can be found in
270   QtCreator/src/libs/3rdparty.
271
272
273 * ClassView and ImageViewer plugins
274
275   Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
276
277   All rights reserved.
278   Copyright (c) 2010 Denis Mingulov.
279
280   Contact: Nokia Corporation (info@qt.nokia.com)
281
282   This file is part of Qt Creator.
283
284   You may use this file under the terms of the BSD license as follows:
285
286   "Redistribution and use in source and binary forms, with or without
287   modification, are permitted provided that the following conditions are
288   met:
289     * Redistributions of source code must retain the above copyright
290       notice, this list of conditions and the following disclaimer.
291     * Redistributions in binary form must reproduce the above copyright
292       notice, this list of conditions and the following disclaimer in
293       the documentation and/or other materials provided with the
294       distribution.
295     * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
296       the names of its contributors may be used to endorse or promote
297       products derived from this software without specific prior written
298       permission.
299
300   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
301   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
302   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
303   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
304   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
305   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
306   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
307   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
308   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
309   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
310   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
311
312
313