feedc0de/qt-creator
1
0
Fork 0
forked from qt-creator/qt-creator
Code Pull Requests Activity

Doc: pull out the debugging section to a separate file

Browse Source 
Change-Id: Ifa96cc2a786bd39ecae1dee2731112a1688ef359
Reviewed-by: hjk <qthjk@ovi.com>
This commit is contained in:
Leena Miettinen
2012-05-29 14:02:17 +02:00
committed by hjk
parent 7e53c4a738
commit 28c6013904
2 changed files with 350 additions and 322 deletions
Download Patch File Download Diff File Expand all files Collapse all files

350
doc/src/debugger/creator-debugger-setup.qdoc Normal file
View File

@@ -0,0 +1,350 @@
/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2012 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (qt-info@nokia.com)
**
**
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
****************************************************************************/
// **********************************************************************
// 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
The main debugger settings are associated with the \l{glossary-tool-chain}
{tool chains} used to build your project.
To configure tool chains, select \gui{Tools > Options > Build and Run >
Tool Chains}. The view lists the tool chains that \QC detected
automatically. You can add tool chains.
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 (e.g.
when your system contains no, or an outdated version of GDB and you
want to use a locally installed replacement instead).
\note If you need to change parameters of an automatically detected
toolchain, you can \gui{Clone} the tool chain and change the
parameters in the clone. Make sure to select the cloned tool chain
in the build settings of your project.
\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
Mac OS, you must sign it and modify your tool chain settings.
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
GDB comes in two varieties with common roots. One is used on
Mac OS X and does not support Python as scripting language; the
other one is the version maintained by the Free Software Foundation
that can use Python as scripting language since version 7.0
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.
The minimal supported version is 7.2. Using GDB version 7.4
is highly recommended with \QC 2.5. For \QC 2.6 the minimal
supported version will be raised to GDB 7.4.
\section2 Supported CDB Versions
The CDB native debugger has similar funtionality to the non-Python GDB
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
\o Platform
\o Compiler
\o Native Debugger
\row
\o Linux
\o GCC, ICC
\o GDB
\row
\o Unix
\o GCC, ICC
\o GDB
\row
\o Mac OS X
\o GCC
\o Apple GDB, FSF GDB (experimental)
\row
\o Windows/MinGW
\o GCC
\o GDB
\row
\o Windows/MSVC
\o Microsoft Visual C++ Compiler
\o Debugging Tools for Windows/CDB
\row
\o Symbian
\o GCC
\o GDB
\row
\o Maemo, MeeGo
\o GCC
\o GDB
\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
\o PlainGdbAdapter debugs locally started GUI processes. It is
physically split into parts that are relevant only when Python is
available, parts relevant only when Python is not available, and
mixed code.
\o TermGdbAdapter debugs locally started processes that need a
console.
\o AttachGdbAdapter debugs local processes started outside \QC.
\o CoreGdbAdapter debugs core files generated from crashes.
\o RemoteGdbAdapter interacts with the GDB server running on Linux.
\o CodaGdbAdapter interacts with Symbian devices. The GDB protocol and
the GDB serial protocol are used between GDB and the adapter. The
target communication framework (TCF) protocol is used between the
adapter and the CODA debugging agent running on the device.
\endlist
\endomit
\section1 Installing Native Debuggers
Check the table below for the supported versions and other important
information about installing native debuggers.
\table
\header
\o Native Debugger
\o Notes
\row
\o GDB
\o On Linux and Windows, use the Python-enabled GDB versions that
are installed when you install \QC and Qt SDK. On Mac OS X,
use the GDB provided with Xcode.
For a custom \l{glossary-development-target}{target}, you can
build your own Python-enabled GDB. Follow the instructions in
\l{http://developer.qt.nokia.com/wiki/QtCreatorBuildGdb}
{Building GDB}.
You must use at least Python version 2.5, but we recommend that
you use version 2.6.
\row
\o Debugging tools for Windows
\o To use this engine, you must install the
\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
\o Debugging tools for Mac OS X
\o The Qt binary distribution contains both debug and release
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
tool chains. For more information, see
\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
\o Select \gui Tools > \gui Options > \gui Debugger > \gui CDB.
\o In the \gui {Symbol paths} field, open the \gui Insert menu
and select \gui{Symbol Server}.
\o Select a directory where you want to store the cached information
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
To use FSF GDB on Mac OS, you must sign it and add it to the \QC tool
chains.
\list 1
\o To create a key for signing FSF GDB, select \gui {Keychain Access >
Certificate Assistant > Create a Certificate}:
\list 1
\o In the \gui {Name} field, input \gui {fsfgdb} to replace
the existing content.
\o In the \gui {Certificate Type} field, select
\gui {Code Signing}.
\o Select the \gui {Let me override defaults} check box.
\o Select \gui Continue, and follow the instructions of the
wizard (use the default settings), until the \gui {Specify a
Location For The Certificate} dialog opens.
\o In the \gui Keychain field, select \gui System.
\o Select \gui {Keychain Access > System}, and locate the
certificate.
\o Double click the certificate to view certificate information.
\o In the \gui Trust section, select \gui {Always Trust} in the
\gui {When using this certificate} field, and then close
the dialog.
\endlist
\o To sign the binary, enter the following command in the terminal:
\code
codesign -f -s "fsfgdb" $INSTALL_LOCATION/fsfgdb
\endcode
\o In \QC, select \gui {Qt Creator > Preferences > Build & Run >
Tool Chains}, to add a tool chain that uses the debugger:
\list 1
\o Select a native tool chain (usually, a x86 64-bit tool chain)
and click \gui Clone to clone it.
\o In the \gui Debugger field, specify the path to FSF GDB
(\c $HOME/gdb72/bin/fsfgdb, but with an explicit value for
\c $HOME).
\endlist
\o To use the debugger, select the tool chain in the \gui {Tool chain}
field in the \gui {Build Settings} of the project.
\endlist
*/

322
doc/src/debugger/creator-debugger.qdoc
View File

@@ -360,328 +360,6 @@
*/
/*!
\contentspage index.html
\previouspage creator-debugging.html
\page creator-debugger-engines.html
\nextpage creator-debugger-operating-modes.html
\title Setting Up Debugger
The main debugger settings are associated with the tool chains used
to build your project.
To configure tool chains, select \gui{Tools > Options > Build and Run >
Tool Chains}. The view lists the tool chains that \QC detected automatically.
You can add tool chains.
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 (e.g.
when your system contains no, or an outdated version of GDB and you
want to use a locally installed replacement instead).
\note If you need to change parameters of an automatically detected
toolchain, you can \gui{Clone} the tool chain and change the
parameters in the clone. Make sure to select the cloned tool chain
in the build settings of your project.
\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
Mac OS, you must sign it and modify your tool chain settings.
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
GDB comes in two varieties with common roots. One is used on
Mac OS X and does not support Python as scripting language; the
other one is the version maintained by the Free Software Foundation
that can use Python as scripting language since version 7.0
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.
The minimal supported version is 7.2. Using GDB version 7.4
is highly recommended with \QC 2.5. For \QC 2.6 the minimal
supported version will be raised to GDB 7.4.
\section2 Supported CDB Versions
The CDB native debugger has similar funtionality to the non-Python GDB
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
\o Platform
\o Compiler
\o Native Debugger
\row
\o Linux
\o GCC, ICC
\o GDB
\row
\o Unix
\o GCC, ICC
\o GDB
\row
\o Mac OS X
\o GCC
\o Apple GDB, FSF GDB (experimental)
\row
\o Windows/MinGW
\o GCC
\o GDB
\row
\o Windows/MSVC
\o Microsoft Visual C++ Compiler
\o Debugging Tools for Windows/CDB
\row
\o Symbian
\o GCC
\o GDB
\row
\o Maemo, MeeGo
\o GCC
\o GDB
\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
\o PlainGdbAdapter debugs locally started GUI processes. It is
physically split into parts that are relevant only when Python is
available, parts relevant only when Python is not available, and
mixed code.
\o TermGdbAdapter debugs locally started processes that need a
console.
\o AttachGdbAdapter debugs local processes started outside \QC.
\o CoreGdbAdapter debugs core files generated from crashes.
\o RemoteGdbAdapter interacts with the GDB server running on Linux.
\o CodaGdbAdapter interacts with Symbian devices. The GDB protocol and
the GDB serial protocol are used between GDB and the adapter. The
target communication framework (TCF) protocol is used between the
adapter and the CODA debugging agent running on the device.
\endlist
\endomit
\section1 Installing Native Debuggers
Check the table below for the supported versions and other important
information about installing native debuggers.
\table
\header
\o Native Debugger
\o Notes
\row
\o GDB
\o On Linux and Windows, use the Python-enabled GDB versions that
are installed when you install \QC and Qt SDK. On Mac OS X,
use the GDB provided with Xcode.
For a custom target, you can build your own Python-enabled GDB.
Follow the instructions on
\l{http://developer.qt.nokia.com/wiki/QtCreatorBuildGdb}{Building GDB}.
You must use at least Python version 2.5, but we recommend that you
use version 2.6.
\row
\o Debugging tools for Windows
\o To use this engine, you must install the
\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
\o Debugging tools for Mac OS X
\o The Qt binary distribution contains both debug and release
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 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
tool chains. For more information, see
\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
\o Select \gui Tools > \gui{Options} > \gui Debugger > \gui CDB.
\o In the \gui {Symbol paths} field, open the \gui{Insert} menu
and select \gui{Symbol Server}.
\o Select a directory where you want to store the cached information
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
To use FSF GDB on Mac OS, you must sign it and add it to the \QC tool
chains.
\list 1
\o To create a key for signing FSF GDB, select \gui {Keychain Access >
Certificate Assistant > Create a Certificate}:
\list 1
\o In the \gui {Name} field, input \gui {fsfgdb} to replace
the existing content.
\o In the \gui {Certificate Type} field, select
\gui {Code Signing}.
\o Select the \gui {Let me override defaults} check box.
\o Select \gui Continue, and follow the instructions of the
wizard (use the default settings), until the \gui {Specify a
Location For The Certificate} dialog opens.
\o In the \gui Keychain field, select \gui System.
\o Select \gui {Keychain Access > System}, and locate the
certificate.
\o Double click the certificate to view certificate information.
\o In the \gui Trust section, select \gui {Always Trust} in the
\gui {When using this certificate} field, and then close
the dialog.
\endlist
\o To sign the binary, enter the following command in the terminal:
\code
codesign -f -s "fsfgdb" $INSTALL_LOCATION/fsfgdb
\endcode
\o In \QC, select \gui {Qt Creator > Preferences > Build & Run >
Tool Chains}, to
add a tool chain that uses the debugger:
\list 1
\o Select a native tool chain (usually, a x86 64-bit tool chain)
and click \gui Clone to clone it.
\o In the \gui Debugger field, specify the path to FSF GDB
(\c $HOME/gdb72/bin/fsfgdb, but with an explicit value for
\c $HOME).
\endlist
\o To use the debugger, select the tool chain in the \gui {Tool chain}
field in the \gui {Build Settings} of the project.
\endlist
*/
/*!
\contentspage index.html
\previouspage creator-debugger-operating-modes.html