diff --git a/doc/src/debugger/creator-debugger-setup.qdoc b/doc/src/debugger/creator-debugger-setup.qdoc new file mode 100644 index 00000000000..ef93d63f82a --- /dev/null +++ b/doc/src/debugger/creator-debugger-setup.qdoc @@ -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 + +*/ diff --git a/doc/src/debugger/creator-debugger.qdoc b/doc/src/debugger/creator-debugger.qdoc index 3caec8d5568..7c5b7d495ad 100644 --- a/doc/src/debugger/creator-debugger.qdoc +++ b/doc/src/debugger/creator-debugger.qdoc @@ -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