qtcreator-faq.qdoc 13.9 KB
Newer Older
Leena Miettinen's avatar
Leena Miettinen committed
1
2
/****************************************************************************
**
Eike Ziller's avatar
Eike Ziller committed
3
4
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing
Leena Miettinen's avatar
Leena Miettinen committed
5
**
hjk's avatar
hjk committed
6
** This file is part of Qt Creator
Leena Miettinen's avatar
Leena Miettinen committed
7
8
9
10
11
12
13
14
15
16
17
18
**
**
** 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.
**
**
****************************************************************************/

Leena Miettinen's avatar
Leena Miettinen committed
19
/*!
20
    \contentspage {Qt Creator Manual}
21
    \previouspage creator-help.html
Leena Miettinen's avatar
Leena Miettinen committed
22
    \page creator-faq.html
23
    \nextpage creator-tips.html
Leena Miettinen's avatar
Leena Miettinen committed
24
25
26

    \title FAQ

27
28
    This section contains answers to some frequently asked questions about \QC.
    You might also find answers to your questions in the
Leena Miettinen's avatar
Leena Miettinen committed
29
30
31
32
33
34
    \l{Known Issues} and \l{Tips and Tricks} sections, or the Troubleshooting
    sections for a special area, such as
    \l{Troubleshooting Debugger}{debugging}.

    \section1 General Questions

35
    \b {\QC only shows a blank window, a dialog complaining about missing OpenGL support, or crashes on startup. What's going wrong?}
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

    Some parts of \QC use Qt Quick 2, which relies on OpenGL API for
    drawing. The most prominent use of Qt Quick 2 is in the Welcome mode, but it's
    also used for the \QMLD, and the QML Profiler.

    Unfortunately the use of OpenGL can cause problems, especially in remote setups
    and with outdated drivers. You can quickly check whether this is your problem by:

    \list

      \li Launching \QC with Welcome mode disabled ( \c{-noload Welcome} on
          command line).

      \li Checking the console or the Windows debugger log for OpenGL-related error messages.

    \endlist

    The fixes and workarounds differ, depending on your setup. As a last resort you
    can disable the affected plugins.

    \e{Virtual Machines}

58
59
60
    Try to enable \e{3D acceleration} in your virtual machine's settings. For VirtualBox,
    also make sure you have installed the Guest Addons, including experimental
    \e{Direct3D support}.
61
62
63
64
65
66
67
68
69
70
71

    \e{Windows}

    Check whether \QC has been compiled with OpenGL/Desktop, or ANGLE as
    a backend. The official binaries are always built with ANGLE (a library that
    maps OpenGL ES API to DirectX).

    \list

      \li ANGLE backend: This requires a Windows version newer than Windows XP. If you
          have problems, try updating your graphics drivers or update your
72
73
          DirectX version. Run \c dxdiag.exe to check whether \e{Direct3D Acceleration}
          is indeed enabled.
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

      \li OpenGL backend: Make sure your graphics driver supports OpenGL 2.1 or newer.
          Try to update your graphics driver.

    \endlist

    \e{Unix}

    Run \c glxgears for a quick check whether OpenGL works in general. Check output of
    \c glxinfo to get more details like the OpenGL driver and renderer (search for 'OpenGL'
    in the application's output).

    If you are using the Mesa driver, you can force OpenGL to be rendered in software
    by setting the \c LIBGL_ALWAYS_SOFTWARE environment variable.

    \e{Disabling plugins}

    You can disable the \QC plugins, at the expense of losing functionality:

    \list

      \li Launch \QC from command line, with
          \c {-noload Welcome -noload QmlProfiler -noload QuickDesigner} arguments.

98
      \li Disable the plugins permanently by selecting \uicontrol Help > \uicontrol{About Plugins}.
99
100
101

    \endlist

102
    \b {How do I reset all \QC settings?}
Leena Miettinen's avatar
Leena Miettinen committed
103

104
    \QC creates the following files and directories:
Leena Miettinen's avatar
Leena Miettinen committed
105
106
107

    \list

108
        \li QtCreator.db
Leena Miettinen's avatar
Leena Miettinen committed
109

110
        \li QtCreator.ini
Leena Miettinen's avatar
Leena Miettinen committed
111

112
        \li qtversion.xml
Leena Miettinen's avatar
Leena Miettinen committed
113

114
        \li toolChains.xml
Leena Miettinen's avatar
Leena Miettinen committed
115

116
        \li qtcreator
Leena Miettinen's avatar
Leena Miettinen committed
117

118
        \li qtc-qmldump
119

Leena Miettinen's avatar
Leena Miettinen committed
120
121
    \endlist

122
    The location depends on the platform. On Linux and other Unix platforms, the files
123
    are located in \c {~/.config/QtProject} and \c {~/.local/share/data/QtProject/qtcreator}.
124

125
    On OS X, the files are located in \c {~/.config/QtProject} and
126
    \c {~/Library/Application Support/QtProject/Qt Creator}.
Leena Miettinen's avatar
Leena Miettinen committed
127
128

    On Windows XP, the files are located in
129
130
    \c {%SystemDrive%\Documents and Settings\%USERNAME%\Application Data\QtProject} and
    \c {%SystemDrive%\Documents and Settings\%USERNAME%\Local Settings\Application Data\QtProject}.
131
132

    On Windows Vista and Windows 7, the files are located in
133
134
    \c {%SystemDrive%\Users\%USERNAME%\AppData\Roaming\QtProject} and
    \c {%SystemDrive%\Users\%USERNAME%\AppData\Local\QtProject}.
Leena Miettinen's avatar
Leena Miettinen committed
135

136
    \b {\QC comes with MinGW, should I use this version with Qt?}
Leena Miettinen's avatar
Leena Miettinen committed
137
138
139

    Use the version that was built against the Qt version.

140
    \b {\QC does not find a helper application, such as Git or a
Leena Miettinen's avatar
Leena Miettinen committed
141
142
    compiler. What should I do?}

143
    Make sure that the application is in your system PATH when starting \QC.
144
    Also select \uicontrol {Tools > Options} to check the settings specified
Leena Miettinen's avatar
Leena Miettinen committed
145
146
147
    for the application. Many plugins specify either the path to the tool they
    need or the environment they run in.

148
    This is especially relevant for the OS X where \c {/usr/local/bin} might
149
    not be in the path when \QC is started.
Leena Miettinen's avatar
Leena Miettinen committed
150

151
    \b {How do I change the interface language for \QC?}
Leena Miettinen's avatar
Leena Miettinen committed
152

153
    \QC has been localized into several languages. If the system
Leena Miettinen's avatar
Leena Miettinen committed
154
    language is one of the supported languages, it is automatically selected.
155
156
    To change the language, select \uicontrol {Tools > Options > Environment} and
    select a language in the \uicontrol Language field. The change takes effect after
157
    you restart \QC.
Leena Miettinen's avatar
Leena Miettinen committed
158

159
    \b {Has a reported issue been addressed?}
Leena Miettinen's avatar
Leena Miettinen committed
160
161

    You can look up any issue in the
Eike Ziller's avatar
Eike Ziller committed
162
    \l{https://bugreports.qt.io/}{Qt bug tracker}.
Leena Miettinen's avatar
Leena Miettinen committed
163

164
    \include widgets/creator-faq-qtdesigner.qdocinc
Leena Miettinen's avatar
Leena Miettinen committed
165
166
167

    \section1 Help Questions

168
    \b {The Qt API Reference Documentation is missing and context help does
Leena Miettinen's avatar
Leena Miettinen committed
169
170
    not find topics. What can I do?}

171
    \QC comes fully integrated with Qt documentation and examples using
Leena Miettinen's avatar
Leena Miettinen committed
172
    the Qt Help plugin. The integrated Qt Reference Documentation is available
173
    for Qt 4.4 and later. \QC and other Qt deliverables contain
Leena Miettinen's avatar
Leena Miettinen committed
174
    documentation as .qch files. All the documentation is accessible in the
175
    \uicontrol Help mode.
Leena Miettinen's avatar
Leena Miettinen committed
176
177

    To view the documentation that is available and to add documentation,
178
    select \uicontrol {Tools > Options > Help > Documentation}. For more
Leena Miettinen's avatar
Leena Miettinen committed
179
180
181
182
183
184
185
    information, see \l{Adding External Documentation}.

    \section1 Debugger Questions

    For information on troubleshooting debugger, see
    \l{Troubleshooting Debugger}.

186
    \b {If I have a choice of GDB versions, which should I use?}
Leena Miettinen's avatar
Leena Miettinen committed
187
188

    On Linux and Windows, use the Python-enabled GDB versions that are
189
    installed when you install \QC and \QSDK. On OS X, GDB is no longer
190
191
    officially supported. To build your own Python-enabled GDB, follow the
    instructions in
192
    \l{https://wiki.qt.io/QtCreator_Build_Gdb}{Building GDB}.
Leena Miettinen's avatar
Leena Miettinen committed
193

hjk's avatar
hjk committed
194
    You must use Python version 2.6 or 2.7.
Leena Miettinen's avatar
Leena Miettinen committed
195
196
197

    For more information on setting up debugger, see \l{Setting Up Debugger}.

198
    \b {How do I generate a core file in \QC?}
199
200

    To trigger the GDB command that generates a core file while debugging,
201
    select \uicontrol {Window > Views > Debugger Log}. In the \uicontrol Command field,
202
203
204
205
    type \c gcore and press \key Enter. The core file is created in the
    current working directory. You can specify another location for the file,
    including a relative or absolute path, as an argument of the command.

206
207
    To generate a temporary core file, select \uicontrol {Create Snapshot} in the
    context menu in the \uicontrol Snapshot view. The core file is deleted when you
208
209
    stop debugging.

Leena Miettinen's avatar
Leena Miettinen committed
210
211
    \section1 Compiler Questions

212
    \b {How can I make use of my multi-core CPU with \QC?}
Leena Miettinen's avatar
Leena Miettinen committed
213

214
215
    On Linux and OS X, go to \uicontrol Project mode, select your configuration
    in the \uicontrol {Build Settings}, locate the \uicontrol {Build Steps}, and add the
Leena Miettinen's avatar
Leena Miettinen committed
216
217
218
219
220
    following value, where \c{<num>} is the amount of cores in your CPU:
    \c{-j <num>}

    On Windows, nmake does not support the \c{-j} parameter. Instead, we
    provide a drop-in replacement called jom. You can download a precompiled
221
    version of jom from \l{https://download.qt.io/official_releases/jom/}{Qt Downloads}.
222
    Put jom.exe in a location in the %PATH%. Go to the \uicontrol {Build Settings}
Leena Miettinen's avatar
Leena Miettinen committed
223
224
    and set jom.exe as the make command.

Leena Miettinen's avatar
Leena Miettinen committed
225
    \note Unlike GNU make, jom automatically detects your cores and spawns as
Leena Miettinen's avatar
Leena Miettinen committed
226
227
228
    many parallel processes as your CPU has cores. You can override this
    behavior by using the \c{-j} parameter as described above.

229
    \section1 Qt Installation Questions
Leena Miettinen's avatar
Leena Miettinen committed
230

231
232
    \b {I cannot use QSslSocket with the Qt I installed from binary packages.
        What should I do?}
Leena Miettinen's avatar
Leena Miettinen committed
233

234
    The Qt in the binary packages is built with QT_NO_OPENSSL defined. Rebuilding it
Leena Miettinen's avatar
Leena Miettinen committed
235
     is possible. For more information, see
hjk's avatar
hjk committed
236
     \l{http://www.qtcentre.org/threads/19222-Qssl}.
Leena Miettinen's avatar
Leena Miettinen committed
237

238
    \b {Which development packages from the distribution are needed on
Leena Miettinen's avatar
Leena Miettinen committed
239
240
241
242
243
244
245
246
247
248
249
250
    Ubuntu or Debian?}

    \code
    sudo apt-get install libglib2.0-dev libSM-dev libxrender-dev libfontconfig1-dev libxext-dev
    \endcode

    If you use QtOpenGL, you also need:

    \code
    sudo apt-get install libgl-dev libglu-dev
    \endcode

Sergio Ahumada's avatar
Sergio Ahumada committed
251
    \section1 Platform Related Questions
Leena Miettinen's avatar
Leena Miettinen committed
252

253
    \b {Where is application output shown in \QC?}
254

255
    \b {On Unix (Linux and OS X):} \c qDebug() and related functions use
256
    the standard output and error output. When you run or debug the
257
    application, you can view the output in the \uicontrol{Application Output} pane.
258

259
    For console applications that require input, select \uicontrol {Projects > Run
260
261
    Settings > Run in terminal}.

262
    \b {On Windows:} Output is displayed differently for \e{console
263
264
265
266
267
268
269
    applications} and \e{GUI applications}.

    The setting \c {CONFIG += console} in the .pro file specifies that the
    application is built as a console application using some other runtime.
    When you run a console application, you can view the output in the console
    window of the calling application. If the
    calling application is a GUI application (for example, a release-built
270
    version of \QC), a new console window is opened.  For this
271
272
273
    type of application, \c qDebug() and related functions use standard output
    and error output.

274
    We recommend that you select \uicontrol {Projects > Run Settings > Run in
275
276
277
278
    terminal} for console applications.

    For GUI applications, \c qDebug() and related functions use the Windows API
    function \c OutputDebugString(). The output is displayed in the
279
    \uicontrol{Application Output} pane. However, only one output pane tab may be
280
281
282
283
284
    open at a time or the output is not displayed correctly. You can use an
    external debug output viewer, such as the
    \l{http://technet.microsoft.com/en-us/sysinternals/bb896647}{DebugView for Windows}
    to display output from GUI applications.

Leena Miettinen's avatar
Leena Miettinen committed
285
286
    \section1 Questions about New Features

287
    \b {Will a requested feature be implemented?}
Leena Miettinen's avatar
Leena Miettinen committed
288
289
290

    If it is a scheduled feature, you can see this in the task tracker. If a
    feature already has been implemented, it is mentioned in the
291
    \l{https://code.qt.io/cgit/qt-creator/qt-creator.git/tree/dist}{changes file}
Leena Miettinen's avatar
Leena Miettinen committed
292
293
    for the upcoming release.

294
    \b {Why does \QC not use tabs for editors?}
Leena Miettinen's avatar
Leena Miettinen committed
295
296
297
298
299
300

    This question comes up from time to time, so we have considered it
    carefully. Here are our main reasons for not using tabs:

    \list

301
        \li Tabs do not scale. They work fine if you have 5 to 6 editors open,
Leena Miettinen's avatar
Leena Miettinen committed
302
303
304
            they become cumbersome with 10, and if you need more horizontal
            space than the tab bar, the interface does not work at all.

305
        \li Tabs do not adapt to your working set.
Leena Miettinen's avatar
Leena Miettinen committed
306

307
        \li The common solution is to give the user the ability to reorder
Leena Miettinen's avatar
Leena Miettinen committed
308
309
            tabs. Now user has to manage tabs instead of writing code.

310
        \li Tabs force you to limit the amount of open editors, because
Leena Miettinen's avatar
Leena Miettinen committed
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
            otherwise you get confused.

    \endlist

    Consider the following use case: \e {Developers want to switch editors.}

    In fact, developers do not want to switch editors, but might have to do so
    to accomplish their tasks. We need to figure out what the tasks are to
    provide developers with better ways to navigate while performing the tasks.

    One common factor in many use cases is switching editors while working on a
    set of open files. While working on files A and B, users sometimes need to
    look at file C. They can press \key Ctrl+Tab to move between the files and
    have the files open in the correct editor according to file type. The list
    is sorted by last used.

    Typically, users also work on multiple classes or functions that are
    related, even though they are defined or declared in different files.
329
    \QC provides two shortcuts for that: \key F2 to follow the symbol
Leena Miettinen's avatar
Leena Miettinen committed
330
331
332
333
334
335
    and \key Ctrl+Shift+U to find usages.

    In addition, developers can:

    \list

336
        \li Press \key F4 to switch between header and source.
Leena Miettinen's avatar
Leena Miettinen committed
337

338
        \li Press \key Alt+Left to move backwards in the navigation history.
Leena Miettinen's avatar
Leena Miettinen committed
339

340
        \li Use the locator (Ctrl+K) to simply tell \QC where to go.
Leena Miettinen's avatar
Leena Miettinen committed
341
342
343
344
345

    \endlist

    The locator can be used to open files, but opening files is also just a
    step on the way to accomplish a task. For example, consider the following
346
    use case: \e {Fix AFunction in SomeClass which comes from
Leena Miettinen's avatar
Leena Miettinen committed
347
348
349
    someclass.cpp/someclass.h}.

    With a tabbed user interface, developers would search for someclass.cpp in
350
351
    the tab bar, and then search for \c {::AFunction}, only to find out that the
    function is not located in that file. They would then search for someclass.h
Leena Miettinen's avatar
Leena Miettinen committed
352
353
354
    in the tab bar, find our that the function is inline, fix the problem, and
    forget where they came from.

355
356
    With \QC, developers can type \c {Ctrl+K m AFun} to find the function.
    Typically, they only need to type 3 to 4 characters of the function name.
Leena Miettinen's avatar
Leena Miettinen committed
357
358
359
360
361
362
363
    They can then fix the problem and press \key Alt+Back to go back to where
    they were.

    Other locator filters include \c c for classes, \c : for all symbols, and
    (thanks to a community contribution) \c . for symbols in the current file.

*/