creator-debugger-setup.qdoc 14.3 KB
Newer Older
1
2
/****************************************************************************
**
3
4
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
5
**
6
** This file is part of the Qt Creator documentation.
7
**
8
9
10
11
12
13
14
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
15
**
16
** GNU Free Documentation License Usage
17
18
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
19
20
21
22
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
23
24
25
26
27
28
29
30
31
32
33
**
****************************************************************************/

// **********************************************************************
// 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.
// **********************************************************************


/*!
34
    \contentspage {Qt Creator Manual}
35
36
37
38
39
40
    \previouspage creator-debugging.html
    \page creator-debugger-engines.html
    \nextpage creator-debugger-operating-modes.html

    \title Setting Up Debugger

41
    The main debugger settings are associated with the
Tobias Hunger's avatar
Tobias Hunger committed
42
43
44
45
46
47
48
49
50
51
52
    \l{glossary-buildandrun-kit}{kit} you build and run your project with. To
    specify the debugger and compiler to use for each kit, select
    \uicontrol Tools > \uicontrol Options > \uicontrol {Build and Run} >
    \uicontrol Kits.

    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 yourself) or because the installed
    version is not supported (for example, when your system contains no, or an
    outdated version of GDB and you want to use a locally installed replacement
    instead).
53

54
    \note If you need to change the debugger to use for an automatically
55
    detected \l{glossary-buildandrun-kit}{kit}, you can \uicontrol Clone the
Tobias Hunger's avatar
Tobias Hunger committed
56
57
    kit and change the parameters in the clone. Make sure to select the cloned
    kit for your project.
58

59
    If the debugger you want to use is not automatically detected, select
60
    \uicontrol Tools > \uicontrol Options > \uicontrol {Build & Run} >
Tobias Hunger's avatar
Tobias Hunger committed
61
    \uicontrol Debuggers > \uicontrol Add to add it.
62

Tobias Hunger's avatar
Tobias Hunger committed
63
64
    \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
65
    debugger. For more information, see \l{Setting CDB Paths on Windows}.
66

Tobias Hunger's avatar
Tobias Hunger committed
67
68
    \note To use the Free Software Foundation (FSF) version of GDB on OS X, you
    must sign it and modify your \l{glossary-buildandrun-kit}{kit} settings.
69

Tobias Hunger's avatar
Tobias Hunger committed
70
71
72
    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.
73

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

77
78
    \section1 Supported Native Debugger Versions

Tobias Hunger's avatar
Tobias Hunger committed
79
80
81
82
83
84
    Qt Creator supports 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. On OS X, the LLDB debugger can be used. Basic
    support for LLDB is also available on Linux, but it is restricted by LLDB's
    capabilities there, and considered experimental.
85

86
87
88
89
90
91
92
93
94
95
    The following table summarizes the support for debugging C++ code:

    \table
        \header
            \li Platform
            \li Compiler
            \li Native Debugger
        \row
            \li Linux
            \li GCC, ICC
hjk's avatar
hjk committed
96
            \li GDB, LLDB (experimental)
97
98
99
100
101
        \row
            \li Unix
            \li GCC, ICC
            \li GDB
        \row
102
            \li OS X
103
            \li GCC, Clang
104
            \li LLDB, FSF GDB (experimental)
105
106
107
108
109
110
111
112
113
114
        \row
            \li Windows/MinGW
            \li GCC
            \li GDB
        \row
            \li Windows/MSVC
            \li Microsoft Visual C++ Compiler
            \li Debugging Tools for Windows/CDB
    \endtable

115
116
    \section2 Supported GDB Versions

Tobias Hunger's avatar
Tobias Hunger committed
117
118
    Starting with version 3.1, \QC requires the Python scripting extension. GDB
    builds without Python scripting are not supported anymore and will not work.
hjk's avatar
hjk committed
119
    The minimum supported version is GDB 7.5 using Python version 2.7, or 3.3,
Tobias Hunger's avatar
Tobias Hunger committed
120
    or newer.
121

hjk's avatar
hjk committed
122
    For remote debugging using GDB and GDB server, the minimum supported version
Tobias Hunger's avatar
Tobias Hunger committed
123
    of GDB server on the target device is 7.0.
124

125
126
    \section2 Supported CDB Versions

Tobias Hunger's avatar
Tobias Hunger committed
127
128
    All versions of CDB targeting platforms supported by Qt are supported by
    \QC.
129

130
    \section2 Supported LLDB Versions
131

Tobias Hunger's avatar
Tobias Hunger committed
132
133
134
135
    The LLDB native debugger has similar functionality to the GDB debugger. LLDB
    is the default debugger in Xcode on OS X for supporting C++ on the desktop.
    LLDB is typically used with the Clang compiler (even though you can use it
    with GCC, too).
136

hjk's avatar
hjk committed
137
138
139
140
    On OS X you can use the LLDB version delivered with Xcode or build from source.
    The minimum supported version is LLDB 320.4.

    On Linux, the minimum supported version is LLDB 3.7.
141
142
143
144
145
146
147
148
149
150
151
152
153

    \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

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

Tobias Hunger's avatar
Tobias Hunger committed
159
        \li TermGdbAdapter debugs locally started processes that need a console.
160

161
        \li AttachGdbAdapter debugs local processes started outside \QC.
162

163
        \li CoreGdbAdapter debugs core files generated from crashes.
164

165
        \li RemoteGdbAdapter interacts with the GDB server running on Linux.
166
167
168
169
170
171
172
173
174
175
176
177

    \endlist

    \endomit

    \section1 Installing Native Debuggers

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

    \table
        \header
178
179
            \li Native Debugger
            \li Notes
180
        \row
181
            \li GDB
Tobias Hunger's avatar
Tobias Hunger committed
182
183
184
185
186
187
188
            \li On Windows, use the Python-enabled GDB versions that is bundled
                with the Qt package or comes with recent versions of MinGW. On
                most Linux distributions the GDB builds shipped with the system
                are sufficient. You can also build your own. Follow the
                instructions in \l{http://wiki.qt.io/QtCreator_Build_Gdb}
                {Building GDB}. Builds of GDB shipped with Xcode on OS X are no
                longer supported.
189
190

        \row
191
            \li Debugging tools for Windows
192
            \li To use the CDB debugger, you must install the
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
                \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
211
                \l{Setting CDB Paths on Windows}.
212
213

       \row
214
            \li Debugging tools for OS X
215
            \li The Qt binary distribution contains both debug and release
216
217
218
219
220
                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.

Tobias Hunger's avatar
Tobias Hunger committed
221
222
                If you use a qmake based project in \QC,  you can set a flag in
                your \l{glossary-run-config}{run configuration}, in
223
224
                \uicontrol Projects mode. In the run configuration, select
                \uicontrol{Use debug version of frameworks}.
225

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

230
231
       \row
            \li LLDB
hjk's avatar
hjk committed
232
            \li We recommend using the LLDB version that is delivered with Xcode 5.
233
234
    \endtable

235
236
237
238
239
240
241
242
    \section1 Mapping Source Paths

    To enable the debugger to step into the code and display the source code
    when using a copy of the source tree at a location different from the one
    at which the libraries where built, map the source paths to target paths:

    \list 1

Tobias Hunger's avatar
Tobias Hunger committed
243
244
        \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Debugger >
            \uicontrol General > \uicontrol Add.
245

Tobias Hunger's avatar
Tobias Hunger committed
246
247
        \li In the \uicontrol {Source path} field, specify the source path in
            the debug information of the executable as reported by the debugger.
248

Tobias Hunger's avatar
Tobias Hunger committed
249
250
        \li In the \uicontrol {Target path} field, specify the actual location
            of the source tree on the local machine.
251
252
253

    \endlist

254
    \section1 Setting CDB Paths on Windows
255
256

    To obtain debugging information for the operating system libraries for
Tobias Hunger's avatar
Tobias Hunger committed
257
258
    debugging Windows applications, add the Symbol Server provided by Microsoft
    to the symbol search path of the debugger:
259
260
261

    \list 1

262
        \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Debugger >
263
            \uicontrol {CDB Paths}.
264

265
            \image qtcreator-debugger-cdb-paths.png
266

267
268
269
        \li In the \uicontrol {Symbol Paths} group, select \uicontrol Insert.

        \li Select the directory where you want to store the cached information.
270
271
272
273

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

274
275
        \li Select \uicontrol OK.

276
277
278
279
280
    \endlist

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

281
282
283
284
    To use the Source Server infrastructure for fetching missing source files
    directly from version control or the web, enter the following string in
    the \uicontrol {Source Paths} field: \c srv*.

285
    \section1 Setting up FSF GDB for OS X
286

287
    To use FSF GDB on OS X, you must sign it and add it to the \QC
288
    \l{glossary-buildandrun-kit}{kits}.
289
290
291

    \list 1

292
293
294
        \li To create a key for signing FSF GDB, select
            \uicontrol {Keychain Access} > \uicontrol {Certificate Assistant} >
            \uicontrol {Create a Certificate}:
295
296
297

        \list 1

298
            \li In the \uicontrol Name field, input \uicontrol fsfgdb to
Tobias Hunger's avatar
Tobias Hunger committed
299
                replace the existing content.
300

301
302
            \li In the \uicontrol {Certificate Type} field, select
                \uicontrol {Code Signing}.
303

304
            \li Select the \uicontrol {Let me override defaults} check box.
305

306
            \li Select \uicontrol Continue, and follow the instructions of the
Tobias Hunger's avatar
Tobias Hunger committed
307
308
309
                wizard (use the default settings), until the
                \uicontrol {Specify a Location For The Certificate} dialog
                opens.
310

311
            \li In the \uicontrol Keychain field, select \uicontrol System.
312

313
314
            \li Select \uicontrol {Keychain Access} > \uicontrol System, and
                locate the certificate.
315

316
            \li Double click the certificate to view certificate information.
317

Tobias Hunger's avatar
Tobias Hunger committed
318
319
            \li In the \uicontrol Trust section, select
                \uicontrol {Always Trust} in the
320
                \uicontrol {When using this certificate} field, and then close
321
322
323
324
                the dialog.

        \endlist

325
        \li To sign the binary, enter the following command in the terminal:
326
327
328
329
330

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

331
332
333
        \li In \QC, select \uicontrol {Qt Creator} > \uicontrol Preferences >
            \uicontrol {Build & Run} > \uicontrol Kits > \uicontrol Add to
            create a kit that uses FSF GDB.
334

335
            \li In the \uicontrol Debugger field, specify the path to FSF GDB
336
337
338
                (\c $HOME/gdb72/bin/fsfgdb, but with an explicit value for
                \c $HOME).

339
        \li To use the debugger, add the kit in the \uicontrol {Build Settings}
340
            of the project.
341
342
343

    \endlist

344
345
346
347
348
349
350
    \section1 Setting Up Experimental LLDB Support

    To use the experimental interface to LLDB, you must set up a kit that uses
    the LLDB engine and select the kit for your project:

    \list 1

351
352
        \li Select \uicontrol Tools > \uicontrol Options >
            \uicontrol {Build & Run} > \uicontrol Kits.
353
354

        \li Select an automatically created kit in the list, and then select
355
            \uicontrol Clone to create a copy of the kit.
356

357
358
359
360
361
        \li In the \uicontrol Debugger field, select an LLDB Engine. If an LLDB
            Engine is not listed, select \uicontrol Manage to add it in
            \uicontrol Tools > \uicontrol Options > \uicontrol {Build & Run} >
            \uicontrol Debuggers. For more information, see
            \l {Adding Debuggers}.
362

363
        \li To use the debugger, add the kit in the \uicontrol {Build Settings}
364
365
366
367
            of the project.

    \endlist

368
*/