Commit fb69ae25 authored by Leena Miettinen's avatar Leena Miettinen
Browse files

Doc: troubleshooting info for debugging

From the FAQ on the Qt development wiki.

Reviewed-by: Pawel Polanski
parent 353b13c4
......@@ -7960,7 +7960,7 @@
\contentspage index.html
\previouspage creator-debugging-helpers.html
\page creator-debugging-qml.html
\nextpage creator-maemo-emulator.html
\nextpage creator-troubleshooting-debugging.html
\title Debugging Qt Quick Projects
......@@ -9222,7 +9222,7 @@
\contentspage index.html
\previouspage creator-debugging-qml.html
\previouspage creator-troubleshooting-debugging.html
\page creator-maemo-emulator.html
\nextpage creator-deployment.html
......@@ -10790,201 +10790,67 @@
\contentspage index.html
\previouspage creator-task-lists.html
\page creator-faq.html
\nextpage creator-help.html
\title FAQ
This section lists some frequently asked questions about Qt Creator and
answers to them.
\section1 General
\section2 How do I reset all Qt Creator settings?
Qt Creator creates two files and a directory: \c QtCreator.db,
\c QtCreator.ini, and \c qtcreator. The location depends on the platform.
On Linux, Unix, and Mac OS, the files are located in \c {~/.config/Nokia},
on Windows XP in
\c {<drive>:\Documents and Settings\<username>\Application Data\Nokia}, and
on Windows Vista and Windows 7 in
\c {<drive>:\Users\<username>\AppData\Roaming\Nokia}. For all versions,
try this path: \c {APPDATA\Nokia}.
\section2 Qt Creator comes with MinGW, should I use this version with Qt?
Until Qt both Qt and Qt Creator have been shipping with a MinGW version which uses MinGW 3.4. Starting with the 1.2.90 Tech Preview, Qt Creator ships with a more recent MinGW GCC 4.4, which Qt 4.6 final will also be using. GCC 3.4 and GCC 4.4 are not binary compatible. So if you try to use Qt 4.6 beta and before with Qt Creator 1.2.90 and older, tell Qt Creator to use the MinGW from Qt by setting “MinGw location” to the according MinGW directory in Tools –> Options –> Qt4 –> Qt Versions.
\section2 Qt Creator does not find a helper application, such as git or a compiler.
Make sure the application is in your system PATH when starting Qt Creator.
Also select \gui {Tools > Options} to check the settings specified for the
application. Many plugins specify either the path to the tool they need or
the environment they run in.
This is especially relevant for the Mac OS where \c {/usr/local/bin} might
not be in the path when Qt Creator is started.
\section2 How do I change the language for Qt Creator?
Qt Creator has been localized into several languages. If the system
language is one of the supported languages, it is automatically selected.
To change the language, select \gui {Tools > Options > Environment} and
select a language in the \gui Language field. The change takes effect after
you restart Qt Creator.
\section1 Qt Designer
\section2 Custom widgets not loaded in Design mode even though it works in standalone \QD.
\QD fetches plugins from standard locations and loads the plugins that
match its build key. The locations are different for standalone and
integrated \QD.
For more information, see \l{Adding Qt Designer Plugins}.
\section1 Help
\section2 The Qt Reference Documentation missing and context help cannot find topics.
Qt Creator comes fully integrated with Qt documentation and
examples using the Qt Help plugin.
\note The integrated Qt Reference Documentation is only available for Qt
4.4 and later.
Qt Creator, \QSDK, and other Qt deliverables contain documentation
as .qch files. All the documentation is accessible in the \gui Help mode.
To view the documentation that is available and to add documentation,
select \gui {Tools > Options... > Help > Documentation}.
For more information, see \l{Adding External Documentation}.
\section1 Debugger
\section2 The debugger does not work.
First, make sure you use at least version 1.2.1. Several debugger related bug fixed in this version. Then, there is a “Debugger View” (under “Debug –> Views –> Debugger”).
Note: Up to Qt Creator 1.2, the view was called “Gdb View”. The contents of the pane on the right hand side is most helpful. It is advised to attach it to any debugger related report on the mailing list ( or to put it on [] before asking people on IRC (#qt-creator at FreeNode).
\section2 Does debugging on Mac need some special setup?
If you want to debug into frameworks, such as Qt code, you need to set
\c{?1 DYLD_IMAGE_SUFFIX=_debug}
(there is an option for that in the Qt4 run configuration). Also XCode 3.x is preferred.
\section2 The built-in debugger is slow during startup and runtime, especially on Windows.
The debugger which ships with Creator in the Qt SDK on Windows is GDB from MinGW. Unfortunately, GDB is quite slow on Windows in general. Qt Creator interacts with GDB and adds custom dumpers for Qt types, and is thus not the problem of the slowness. Note that Creator can be used with MSVC on Windows, too – even for debugging.
\section2 How do I enable the debugging helpers for Qt’s bootstrapped applications (moc, qmake, etc)
The bootstrapped applications are built in a way that is incompatible with
the default build of the debugging helpers. To work around this, add
gdbmacros.cpp to the compiled sources in the application Makefile.
\previouspage creator-debugging-qml.html
\page creator-troubleshooting-debugging.html
\nextpage creator-maemo-emulator.html
Choose \gui {Tools > Options > Debugger > Debugging Helper > Use debugging
helper from custom location}, and specify an invalid location, such as
\title Troubleshooting Debugger
For more information, see \l{Using Debugging Helpers}.
This section lists some typical problems that you might encounter while
debugging and solutions for them.
\section2 The debugger does not hit my breakpoints
\section1 Debugger Does Not Hit Breakpoints
You might have created a release build that does not contain debug
information. A gcc debug build should have the “-g” option on the compiler command line. Check that this option is present in the “Compile output” pane (Alt-4). If not, adjust your build settings in the “Project” tab.
When using the Locals & Watches window to inspect a pointer variable, expanding the variable’s tree item shows another tree item level instead of directly showing the members of the pointer variable. That’s ugly.
There’s a “Dereference pointers automatically” item in the Locals and Watchers context menu.
\section2 If I have a choice of gdb versions, which should I use?
Use the gdb version delivered with Qt Creator or Qt SDK. Except for Mac OS,
?1 sudo dpkg -i gdb_6.8-3ubuntu2_[arch].deb
\section2 The debugger tells me <not in scope> for some variables that are definitely in scope. What happened?
The message is created by the debugging helpers. Qt Creator posts an expression to the gdb command line to invoke the debugging helpers, including the address of the object to examine. In some cases this address is modified by gdb before actually calling the helper function. It is unclear why and when this happens, but if it happens, the debugging helpers operate on wrong data and come to wrong conclusions, the most likely outcome is that it will find garbage and declare the variable as <not in scope>.
\section2 What’s up with Python in the debugger?
Qt Creator is able to take advantage of using gdb builds that enable python scripting. It is currently only used for creating the contents of the Locals and Watcher view, but we might use it for stack display later. Using python scripting has three major advantages for us:
information. A GNU Compiler Collection (GCC) debug build has the \c {-g}
option on the compiler command line. Check that this option is present in
the \gui {Compile Output} pane. If it is not, adjust your build settings
in the \gui {Projects} mode.
There is no need to inject code (“Debugging helpers”) into the debugged process to “nicely display”, say, QStringList or std::map contents. The code injection was a constant source of trouble and introduced extra stress on the debugged process, something one usually does not want when debugging.
It is now easily possible to extend the “Debugging helpers” to other types. No compilation required, just a few lines of python.
Python scripting vastly reduces the communication overhead compared to the previous “pure MI” based solution.
So while in theory all is fine now, in practice there are some obstacles:
\section1 Debugger Does Not Work
There is no python-enabled gdb for Mac. Mac will have to continue injection with C++ based debugging helpers.
On the Symbian platform and the AppTRK tool used artificially restricts gdb’s ability to talk to the device, so extracting e.g. QObject properties is not possible.
There is no gdb to talk to MSVC compiled applications on Windows. So “nice display” only works in a limited fashion using injection of C++ based Debugging helpers and cdb.
Also, the official gdb 7.0 release will not work as it crashes quite often due to []
Official gdb 7.0.1 works, but requires a few nasty workarounds on the Creator side as it does not have all the python features Qt Creators would like to use. Find updated sources for Ubuntu 9.10 (Karmic) by adding the following to your /etc/apt/sources.list:
?123 deb karmic main deb-src karmic main
To use Qt Creator’s new python based gdb integration you need
gdb 7.0.1 or later – or –
self-compiled gdb from Archer:
Python 2.5 or later (Kubuntu: python2.6-dev)
A gdb from Archer:
Checkout the sources:
?123 git clone git:// cd archer git checkout -b archer-tromey-python origin/archer-tromey-python
Build it:
?12 ./configure —with-python —disable-werror make
Your new gdb will emerge as gdb/gdb
Point Creator’s gdb path (Options –> Debugger –> Gdb –> Gdb Location) to your Python-enabled gdb or use the QTC_DEBUGGER_PATH environment variable
Start debugging as usual.
Go to the Debugger –> Views –> Debugger view to check if everything is ok. Close to the beginning there is a command ‘help bb’ issued, check whether it returns with a ‘done’ or an ‘error’ reply.
\section2 Are there prebuilt gdb binaries you recommend?
For Linux/x86: []
For Linux/x86_64: []
Why is stepping into functions in shared libraries so slow on Linux?
There was a gdb bug ( []) which has been fixed by now. It has also been suggested that
?1 sudo apt-get install libc6-dbg
If the debugger does not work properly, try the following:
\list 1
solves the problem on Ubuntu machines.
\o Make sure you use at least Qt Creator 2.1.
\section1 Code Editor
\o In the \gui Debug mode, select \gui {Windows > Views > Debugger
Log} to open the \gui {Debugger Log} view. Browse the contents of
the pane on the right hand side to find out what went wrong.
Always attach the contents of the pane to debugger-related
questions to the Qt Creator mailing list (
or paste them to
\l{}{} before
asking questions in the IRC (on the #qt-creator channel at
How can I get code-completion to work on the standard headers and phonon?
That does work only with builds from March 31 2009 or newer.
\section1 Directly Displaying Pointer Variable Members
\section1 Compilation
When you use the \gui {Locals and Watchers} view to inspect a pointer
variable and expand the variable tree item, another tree item level
is displayed. To directly display the members of the pointer variable,
select \gui {Dereference Pointers Automatically} in the context menu in the
\gui {Locals and Watchers} view.
How can I make use of my multi-core CPU with Qt Creator?
\section1 Built-in Debugger Is Slow During Startup and Runtime
On Linux and Mac OS X, go to Project Mode, select your configuration in the build settings tab, locate the Build Steps entry and add -j <num> where <num> is the amount of cores in your CPU.
The Qt Creator for Windows installation packages install gdb from MinGW.
Unfortunately, gdb is quite slow on Windows. Qt Creator does not cause
this, as it interacts with gdb and adds custom dumpers for Qt types.
On Windows, nmake does not support the -j parameter. Instead, we provide a drop-in replacement called jom. You can download a precompiled version of jom from the Qt FTP. Put jom.exe in a location in PATH. Go to the location described above and set jom.exe as the make command. Note: Unlike GNU make, jom will automatically detect your cores and will spawn as many parallel processes as your CPU has cores. You can override this behavior by using the -j parameter as described above.
\note You can use Qt Creator with MSVC on Windows for debugging.
\section1 Debugger Displays <not in scope> Message
The message is created by the debugging helpers. Qt Creator posts an
expression to the gdb command line to invoke the debugging helpers.
The expression includes the address of the object to examine. This
address might be modified by gdb before the helper function is called. It
is unclear why and when this happens, but if it happens, the debugging
helpers operate on wrong data and come to wrong conclusions. Most likely,
they find garbage and declare the variable to be <not in scope>.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment