// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page creator-faq.html
    \previouspage creator-reference.html

    \ingroup creator-reference

    \title FAQ

    \brief Answers to some frequently asked questions about \QC.

    You might also find answers to your questions in the
    \l{Known Issues} and \l{How To} sections, or the Troubleshooting
    sections for a special area, such as
    \l{Troubleshooting Debugger}{debugging}.

    \section1 General Questions

    \b {\QC comes with \MinGW, should I use this version with Qt?}

    Use the version that was built against the Qt version.

    \b {\QC does not find a helper application, such as Git, Ninja, or a
    compiler. What should I do?}

    Make sure that the application is in your system PATH when starting \QC.
    Also select \preferences 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.

    You can also specify the environment for finding and running tools globally
    or for a particular project or kit, as described in
    \l{Edit environment settings}.

    This is especially relevant when you start \QC from your desktop
    and not from a terminal application, like from Finder, Dock, or
    Spotlight on \macos, or from Dock, Dash, or the Activities overview on
    Gnome. In that case, the started application does not inherit the
    environment that you set up for your shell (that your terminal application
    uses), but instead from \c launchd (\macos) or \c gnome-shell (Gnome).
    That means that paths that you have set up for your terminal, such as
    \c{/usr/local/bin} or \c{/opt/homebrew/bin} for Homebrew on \macos, are not
    automatically available to \QC if you started it from your desktop.

    \b {Has a reported issue been addressed?}

    You can look up any issue in the
    \l{https://bugreports.qt.io/}{Qt Project Bug Tracker}.

    \include widgets/creator-faq-qtdesigner.qdocinc qt designer faq

    \section1 QML and Qt Quick Questions

    \b {Why is there a red line below my QML import, even though I have the module?}

    By default, \QC looks in the QML import path of Qt for QML modules.
    Sometimes, it does not get it right and you need to tell it where the
    modules are. When using qmake as the build system, specify the
    \c{QML_IMPORT_PATH} in the \c{.pro} file of your application. When
    using CMake, add the \c set command to the \c CMakeLists.txt file.

    This also enables code completion of QML code and removes error messages.

    The following example illustrates how to specify the import path for qmake
    projects so that it works when switching between build and run \l{Kits}{kits}
    for different target platforms:

    \code
    TEMPNAME = $${QMAKE_QMAKE}
    MY_QTPATH = $$dirname(TEMPNAME)
    QML_IMPORT_PATH += $$MY_QTPATH/../qml
    message("my QML Import Path: "$$QML_IMPORT_PATH)
    \endcode

    For more information about how to set the import path for CMake projects,
    see \l {Importing QML Modules}.

    \b {What should I do when \QC complains about missing OpenGL support?}

    Some parts of \QC, such as QML Profiler, use Qt Quick 2, which
    relies on OpenGL API for drawing. Unfortunately, the use of OpenGL can cause
    problems, especially in remote setups and with outdated drivers. In these
    cases, \QC displays OpenGL-related error messages on the console or records
    them in the Windows debugger log.

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

    \e{Virtual Machines}

    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}.

    \e{Windows}

    By default Qt Quick uses Direct3D 11. If you have problems, try updating
    your graphics drivers or update your DirectX version. Run \c dxdiag.exe to
    check whether \e{Direct3D Acceleration} is indeed enabled.

    You can also try setting the \c QSG_RHI_BACKEND environment variable to
    \c vulkan or \c opengl. See \l {Qt for Windows - Graphics Acceleration}
    for details.

    \e{Unix}

    Run \c glxgears for a quick check whether OpenGL works in general. Check the
    output of \c glxinfo to get more details like the OpenGL driver and renderer
    (search for \e 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 the
          \c {-noload QmlProfiler -noload QmlDesigner} arguments.

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

    \endlist

    \section1 Help Questions

    \b {The Qt API Reference Documentation is missing and context help does
    not find topics. What can I do?}

    Install a Qt version and Qt documentation with \l{Get and Install Qt}{\QOI}.

    To view the installed documentation (.qch files) and to add documentation,
    go to \preferences > \uicontrol Help >
    \uicontrol Documentation. For more information, see
    \l{Add external documentation}.

    \section1 Debugger Questions

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

    \b {If I have a choice of GDB versions, which should I use?}

    On Linux and Windows, use the Python-enabled GDB versions that are
    installed when you install \QC and \QSDK. On \macos, GDB is no longer
    officially supported. To build your own Python-enabled GDB, follow the
    instructions in
    \l{https://wiki.qt.io/QtCreator_Build_Gdb}{Building GDB}.

    You must use Python version 2.6 or 2.7.

    For more information, see \l{Supported Debuggers}.

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

    To trigger the GDB command that generates a core file while debugging,
    go to \uicontrol View > \uicontrol Views > \l {Debugger Log}.
    In the \uicontrol Command field, enter \c gcore and select \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.

    \omit
    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
    stop debugging.
    \endomit

    \section1 Compiler Questions

    \b {How can I make use of my multi-core CPU with \QC?}

    On Linux and \macos, go to \uicontrol Projects mode, select your configuration
    in the \uicontrol {Build Settings}, locate the \uicontrol {Build Steps}, and add the
    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, you can use
    \e jom. You can download a precompiled
    version of jom from \l{https://download.qt.io/official_releases/jom/}{Qt Downloads}.
    Put \c jom.exe in a location in the %PATH%. Go to the \uicontrol {Build Settings}
    and set \c jom.exe as the make command.

    \note Unlike GNU make, jom automatically detects your cores and spawns as
    many parallel processes as your CPU has cores. You can override this
    behavior by using the \c{-j} parameter as described above.

    \section1 Qt Installation Questions

    \b {I cannot use QSslSocket with the Qt I installed from binary packages.
        What should I do?}

    The Qt in the binary packages is built with QT_NO_OPENSSL defined. Rebuilding it
     is possible. For more information, see
     \l{http://www.qtcentre.org/threads/19222-Qssl}.

    \b {Which development packages from the distribution are needed on
    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

    \section1 Platform Related Questions

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

    \b {On Unix (Linux and \macos):} \c qDebug() and related functions use
    the standard output and error output. When you run or debug the
    application, you can view the output in \l{Application Output}.

    For console applications that require input, select \uicontrol Projects >
    \uicontrol {Run Settings} > \uicontrol {Run in terminal}. To specify the
    terminal to use, select \preferences >
    \uicontrol Environment > \uicontrol System. To use an \l{Terminal}
    {internal terminal}, select \preferences
    > \uicontrol Terminal > \uicontrol {Use internal terminal}.

    \b {On Windows:} Output is displayed differently for \e{console
    applications} and \e{GUI applications}.

    For qmake projects, the \c {CONFIG += console} setting in the \c .pro file
    specifies that the application is built as a console application using
    some other runtime.

    This is the standard behavior for CMake projects. To create a GUI
    application on Windows or an application bundle on \macos, you must
    specify the \c WIN32 or \c MACOSX_BUNDLE property for the
    \l{https://doc.qt.io/qt-6/qt-add-executable.html}{qt_add_executable}
    command in the \c CMakeLists.txt file.

    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
    version of \QC), a new console window is opened. For this
    type of application, \c qDebug() and related functions use standard output
    and error output.

    We recommend that you select \uicontrol Projects > \uicontrol {Run Settings} >
    \uicontrol {Run in terminal} for console applications.

    For GUI applications, \c qDebug() and related functions use the Windows API
    function \c OutputDebugString(). The output is displayed in
    \uicontrol{Application Output}. However, \QC can show output from only one
    source at the time for it to be displayed correctly. You can use an
    external debug output viewer, such as the
    \l{https://technet.microsoft.com/en-us/sysinternals/bb896647}
    {DebugView for Windows} to display output from GUI applications.

    \section1 Questions about New Features

    \b {Will a requested feature be implemented?}

    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
    \l{https://code.qt.io/cgit/qt-creator/qt-creator.git/tree/dist}{changes file}
    for the upcoming release.

    \b {Why does \QC not use tabs for editors by default?}

    Here are our main reasons for not using tabs by default:

    \list

        \li Tabs do not scale. They work fine if you have 5 to 6 editors open,
            they become cumbersome with 10, and if you need more horizontal
            space than the tab bar, the interface does not work at all.

        \li Tabs do not adapt to your working set.

        \li The common solution is to give the user the ability to reorder
            tabs. Now the user has to manage tabs instead of writing code.

        \li Tabs force you to limit the amount of open editors because
            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
    offer developers 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 select \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.
    \QC offers two shortcuts for that: \key F2 to follow the symbol under
    cursor and \key Ctrl+Shift+U to find references to it.

    In addition, developers can:

    \list

        \li Select \key F4 to switch between header and source.

        \li Select \key Alt+Left to move backwards in the navigation history.

        \li Use the locator (Ctrl+K) to simply tell \QC where to go.

    \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
    use case: \e {Fix AFunction in SomeClass which comes from
    someclass.cpp/someclass.h}.

    With a tabbed user interface, developers would search for \c someclass.cpp in
    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 \c someclass.h
    in the tab bar, find our that the function is inline, fix the problem, and
    forget where they came from.

    With \QC, developers can enter \c {Ctrl+K m AFun} to find the function.
    Typically, they only need to enter 3 to 4 characters of the function name.
    They can then fix the problem and select \key Alt+Back to go back to where
    they were.

    Other locator filters include \c c for classes, \c : for all symbols, and
    \c . for symbols in the current file.

    Another way to switch between open documents is to select the document in
    the \uicontrol {Open Documents} view.

    If you still want to use tabs in editors, go to \preferences >
    \uicontrol Environment > \uicontrol Interface, and then select
    \uicontrol {Use tabbed editors}.
*/
