creator-debugger-setup.qdoc 12.4 KB
Newer Older
1
2
/****************************************************************************
**
3
** Copyright (c) 2013 Digia Plc and/or its subsidiary(-ies).
hjk's avatar
hjk committed
4
** Contact: http://www.qt-project.org/legal
5
**
hjk's avatar
hjk committed
6
** This file is part of Qt Creator
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
**
**
** GNU Free Documentation License
**
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
**
****************************************************************************/

// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************


/*!
    \contentspage index.html
    \previouspage creator-debugging.html
    \page creator-debugger-engines.html
    \nextpage creator-debugger-operating-modes.html

    \title Setting Up Debugger

34
35
36
37
    The main debugger settings are associated with the
    \l{glossary-buildandrun-kit}{kit} you build and run your project with. To specify the
    debugger and compiler to use for each kit, select \gui Tools >
    \gui Options > \gui {Build and Run} > \gui Kits.
38
39
40
41

    You need to set up the debugger only if the automatic setup
    fails, because the native debugger is missing (as is usually the
    case for the CDB debugger on Windows, which you always must install
42
    yourself) or because the installed version is not supported (for example,
43
44
45
    when your system contains no, or an outdated version of GDB and you
    want to use a locally installed replacement instead).

46
    \note If you need to change the debugger to use for an automatically
47
48
49
    detected \l{glossary-buildandrun-kit}{kit},
    you can \gui{Clone} the kit and change the parameters in
    the clone. Make sure to select the cloned kit for your project.
50
51
52
53
54
55
56

    \note To use the debugging tools for Windows, you must install them
    and add the Symbol Server provided by Microsoft to the symbol search
    path of the debugger. For more information, see \l{Setting the Symbol
    Server in Windows}.

    \note To use the Free Software Foundation (FSF) version of GDB on
57
    Mac OS, you must sign it and modify your \l{glossary-buildandrun-kit}{kit} settings.
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

    This section explains the options you have for debugging C++ code
    and provides installation notes for the supported native debuggers.
    It also applies for code in other compiled languages such as C,
    FORTRAN, Ada.

    \section1 Supported Native Debugger Versions

    Qt Creator supports essentially two native debuggers when working with
    compiled code. On most supported platforms, the GNU Symbolic Debugger
    GDB can be used. On Microsoft Windows, when using the Microsoft tool chain
    the Microsoft Console Debugger CDB, is needed. There is also an
    incomplete experimental interface to LLDB on Mac OS and Linux available
    when building \QC from source.

    \section2 Supported GDB Versions

hjk's avatar
hjk committed
75
76
77
78
79
80
81
82
83
    GDB comes in two varieties with common roots.

    One is used on Mac OS X and does not support Python as scripting language.
    The minimal supported versions in is GDB 6.3.50-20050815, build 1469.

    The second is maintained by the Free Software Foundation, and can
    use Python as scripting language. The minimal supported version
    in this case is FSF GDB 7.4.1, using Python version 2.6 or 2.7.
    Note that Python 3.x is not supported by GDB.
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

    The Python enabled versions are very convenient to interface,
    and much of \QC's advanced data display options depend on the
    availability of Python scripting. Since Python enabled versions
    of GDB are bundled with all recent Linux versions, active
    support for non-Python builds has been dropped for platforms
    other than Mac OS X.

    The non-Python versions use the compiled version of the debugging
    helpers, that you must enable separately. For more information, see
    \l{Debugging Helpers Based on C++}.

    The Python version uses a script version of the debugging helpers
    that does not need any special setup.

    FSF GDB can also be compiled for Mac OS, but the build is currently
    unstable, and thererefore, this is not recommended.

    \section2 Supported CDB Versions

Sergio Ahumada's avatar
Sergio Ahumada committed
104
    The CDB native debugger has similar functionality to the non-Python GDB
105
106
107
108
109
110
111
    debugger engine. Specifically, it also uses compiled C++ code for the
    debugging helper library.

    The following table summarizes the support for debugging C++ code:

    \table
        \header
112
113
114
            \li Platform
            \li Compiler
            \li Native Debugger
115
        \row
116
117
118
            \li Linux
            \li GCC, ICC
            \li GDB
119
        \row
120
121
122
            \li Unix
            \li GCC, ICC
            \li GDB
123
        \row
124
125
126
            \li Mac OS X
            \li GCC
            \li Apple GDB, FSF GDB (experimental)
127
        \row
128
129
130
            \li Windows/MinGW
            \li GCC
            \li GDB
131
        \row
132
133
134
            \li Windows/MSVC
            \li Microsoft Visual C++ Compiler
            \li Debugging Tools for Windows/CDB
135
        \row
136
137
138
            \li Maemo, MeeGo
            \li GCC
            \li GDB
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
    \endtable

    For more information on the debugger modes, see
    \l{Launching the Debugger in Different Modes}.

    \omit

    \section2 GDB Adapter Modes

    [Advanced Topic]

    The GDB native debugger used internally by the debugger plugin runs in
    different adapter modes to cope with the variety of supported platforms and
    environments. All GDB adapters inherit from  AbstractGdbAdapter:

    \list

156
        \li PlainGdbAdapter debugs locally started GUI processes. It is
157
158
159
160
            physically split into parts that are relevant only when Python is
            available, parts relevant only when Python is not available, and
            mixed code.

161
        \li TermGdbAdapter debugs locally started processes that need a
162
163
            console.

164
        \li AttachGdbAdapter debugs local processes started outside \QC.
165

166
        \li CoreGdbAdapter debugs core files generated from crashes.
167

168
        \li RemoteGdbAdapter interacts with the GDB server running on Linux.
169
170
171
172
173
174
175
176
177
178
179
180

    \endlist

    \endomit

    \section1 Installing Native Debuggers

    Check the table below for the supported versions and other important
    information about installing native debuggers.

    \table
        \header
181
182
            \li Native Debugger
            \li Notes
183
        \row
184
185
            \li GDB
            \li On Linux and Windows, use the Python-enabled GDB versions that
186
187
                are installed when you install \QC and Qt SDK. On Mac OS X,
                use the GDB provided with Xcode.
188
                You can also build your own Python-enabled GDB. Follow the instructions in
189
                \l{http://qt-project.org/wiki/QtCreatorBuildGdb}
190
191
192
                {Building GDB}.

        \row
193
194
            \li Debugging tools for Windows
            \li To use this engine, you must install the
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
                \e{Debugging tools for Windows}. You can download them from
                \l{http://msdn.microsoft.com/en-us/windows/hardware/gg463009/}
                {Download and Install Debugging Tools for Windows}.

                \note Visual Studio does not include the Debugging tools needed,
                and therefore, you must install them separately.

                The pre-built \QSDK for Windows makes use of the library if it
                is present on the system. When manually building \QC using
                the Microsoft Visual C++ Compiler, the build process checks for
                the required files in
                \c{"%ProgramFiles%\Debugging Tools for Windows"}.

                It is highly recommended that you add the Symbol Server provided
                by Microsoft to the symbol search path of the debugger. The
                Symbol Server provides you with debugging informaton for the
                operating system libraries for debugging Windows applications.
                For more information, see
                \l{Setting the Symbol Server in Windows}.

       \row
216
217
            \li Debugging tools for Mac OS X
            \li The Qt binary distribution contains both debug and release
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
                variants of the libraries. But you have to explicitly tell the
                runtime linker that you want to use the debug libraries even if
                your application is compiled as debug, as release is the default
                library.

                If you use a qmake based project in \QC,  you can set a
                flag in your \l{glossary-run-config}{run configuration}, in
                \gui Projects mode. In the run configuration, select
                \gui{Use debug version of frameworks}.

                For more detailed information about debugging on the Mac OS X,
                see: \l{http://developer.apple.com/library/mac/#technotes/tn2124/_index.html#//apple_ref/doc/uid/DTS10003391}
                {Mac OS X Debugging Magic}.

                You can download an experimental version of FSF GDB that
                supports Python from
                \l{ftp://ftp.qt.nokia.com/misc/gdb/7.2/gdb72_mac_platform.tar.bz2}.
                To use FSF GDB on Mac OS, you must sign it and add it to the \QC
236
                \l{glossary-buildandrun-kit}{kits}. For more information, see
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
                \l{Setting up FSF GDB for Mac OS}.

              \note The Mac OS X Snow Leopard (10.6) has a bug that might cause the
              application to crash. For a workaround, see:
              \l{https://bugreports.qt-project.org/browse/QTBUG-4962}{QTBUG-4962}.

    \endtable

    \section1 Setting the Symbol Server in Windows

    To obtain debugging information for the operating system libraries for
    debugging Windows applications, add the Symbol Server provided
    by Microsoft to the symbol search path of the debugger:

    \list 1

253
        \li Select \gui Tools > \gui Options > \gui Debugger > \gui CDB.
254

255
        \li In the \gui {Symbol paths} field, open the \gui Insert menu
256
257
            and select \gui{Symbol Server}.

258
        \li Select a directory where you want to store the cached information
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
            and click \gui OK.

            Use a subfolder in a temporary directory, such as
            \c {C:\temp\symbolcache}.

    \endlist

    \note Populating the cache might take a long time on a slow network
    connection.

    \note The first time you start debugging by using the Debugging tools for
    Windows, \QC prompts you to add the Symbol Server.

    \section1 Setting up FSF GDB for Mac OS

274
275
    To use FSF GDB on Mac OS, you must sign it and add it to the \QC
    \l{glossary-buildandrun-kit}{kits}.
276
277
278

    \list 1

279
        \li To create a key for signing FSF GDB, select \gui {Keychain Access >
280
281
282
283
            Certificate Assistant > Create a Certificate}:

        \list 1

284
            \li In the \gui {Name} field, input \gui {fsfgdb} to replace
285
286
                the existing content.

287
            \li In the \gui {Certificate Type} field, select
288
289
                \gui {Code Signing}.

290
            \li Select the \gui {Let me override defaults} check box.
291

292
            \li Select \gui Continue, and follow the instructions of the
293
294
295
                wizard (use the default settings), until the \gui {Specify a
                Location For The Certificate} dialog opens.

296
            \li In the \gui Keychain field, select \gui System.
297

298
            \li Select \gui {Keychain Access > System}, and locate the
299
300
                certificate.

301
            \li Double click the certificate to view certificate information.
302

303
            \li In the \gui Trust section, select \gui {Always Trust} in the
304
305
306
307
308
                \gui {When using this certificate} field, and then close
                the dialog.

        \endlist

309
        \li To sign the binary, enter the following command in the terminal:
310
311
312
313
314

            \code
            codesign -f -s "fsfgdb" $INSTALL_LOCATION/fsfgdb
            \endcode

315
        \li In \QC, select \gui {Qt Creator > Preferences > Build & Run >
316
            Kits} > \gui Add to create a kit that uses FSF GDB.
317

318
            \li In the \gui Debugger field, specify the path to FSF GDB
319
320
321
                (\c $HOME/gdb72/bin/fsfgdb, but with an explicit value for
                \c $HOME).

322
        \li To use the debugger, add the kit in the \gui {Build Settings}
323
            of the project.
324
325
326
327

    \endlist

*/