creator-clang-codemodel.qdoc 6.89 KB
Newer Older
1 2
/****************************************************************************
**
3 4
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
5
**
6
** This file is part of the Qt Creator documentation.
7
**
8 9 10 11 12 13 14
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
15
**
16
** GNU Free Documentation License Usage
17 18
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
19 20 21 22
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
23 24 25 26 27 28 29 30 31 32
**
****************************************************************************/

// **********************************************************************
// 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.
// **********************************************************************

/*!
33
    \contentspage {Qt Creator Manual}
34 35 36 37
    \previouspage creator-diff-editor.html
    \page creator-clang-codemodel.html
    \nextpage creator-finding-overview.html

38
    \title Parsing C++ Files with the Clang Code Model
39 40 41 42 43 44 45

    The \e {code model} is the part of an IDE that understands the language you
    are using to write your application. It is the framework that allows \QC
    to provide the following services:

    \list

46
        \li \l{Completing Code}{Code completion}
47

48
        \li Syntactic and \l{Semantic Highlighting}{semantic highlighting}
49

50 51 52
        \li Navigating in the code by using the \l{Searching with the Locator}
            {locator}, \l{Moving to Symbol Definition or Declaration}
            {following symbols}, and so on
53

54 55
        \li Inspecting code by using the \l{Browsing Project Contents}
            {class browser}, the \l{Viewing QML Types}{outline}, and so on
56

57
        \li Diagnostics and \l{Viewing Function Tooltips}{tooltips}
58

59
        \li \l{Finding Symbols}{Finding and renaming symbols}
60

61
        \li \l{Applying Refactoring Actions}{Refactoring actions}
62 63 64

    \endlist

65 66
    \QC comes with an experimental plugin that provides some of these services
    for C++ on top of \l{http://clang.llvm.org/}{Clang}.
67

68
    \section1 About the Clang Code Model
69

70 71
    The Clang project provides libraries for parsing
    C language family source files. The feedback you get through warning and
72
    error markers is the same as a compiler will give you, not an incomplete
73 74 75 76
    set or a close approximation, as when using the built-in \QC code model.
    Clang focuses on detailed information for diagnostics, which is really
    useful if the code contains typos, for example.

77 78 79
    Clang keeps up with the development of the C++ language. At the time of this
    writing, it supports C++98/03, C++11, C++14, C89, C99, Objective-C, and
    Objective-C++.
80 81 82 83 84 85 86 87 88 89 90 91 92 93

    On the downside, for large projects using Clang as code model is slower than
    using the built-in code model. Clang does not need to generate object files,
    but it still needs to parse and analyze the source files. For small projects
    that only use STL, this is relatively fast. But for larger projects that
    include several files, processing a single file and all the included files
    can take a while.

    The following services are currently implemented in the experimental Clang
    code model plugin:

    \list

        \li Code completion
94
        \li Syntactic and semantic highlighting
95
        \li Diagnostics
96 97 98 99 100

    \endlist

    To use the plugin, you must build it and configure it in \QC.

101
    \section1 Activating Clang Code Model
102

103 104 105
    If you build \QC yourself, ensure that the plugin is also built, as
    described in the \QC
    \l{https://code.qt.io/cgit/qt-creator/qt-creator.git/tree/README.md}{README file}.
106

107
    To activate the plugin:
108

109
    \list 1
110

111 112
        \li Select \uicontrol Help > \uicontrol {About Plugins} >
            \uicontrol {C++} > \uicontrol ClangCodeModel to enable the plugin.
113

114
        \li Restart \QC to be able to use the plugin.
115

116 117
            If you build \QC yourself, add \c ${LLVM_INSTALL_DIR}\bin to the
            \c PATH variable so the LLVM libraries will be found on startup.
118

119
    \endlist
120

121
    \section1 Configuring Clang Code Model
122

123
    To specify settings for the Clang code model:
124

125
    \list 1
126

127 128
        \li Select \uicontrol Tools > \uicontrol Options > \uicontrol C++ >
            \uicontrol {Code Model}.
129

130
            \image qtcreator-clang-code-model-options.png
131

132 133
        \li In the \uicontrol {Configuration to use} list, configure the
            diagnostics that Clang should issue.
134

135 136
            You can either select one of the predefined configurations, or
            create a copy of a configuration and edit it to fit your needs:
137

138
            \list
139

140 141 142
                \li \uicontrol {Pedantic Warnings} uses the \c -Wpendantic
                    option that requests all the warnings demanded by strict
                    ISO C and ISO C++.
143

144 145 146 147
                \li \uicontrol {Warnings for Questionable Constructs} combines
                    the \c -Wall and \c -Wextra options to request all warnings
                    about easily avoidable questionable constructions and some
                    additional warnings.
148

149 150 151
                \li \uicontrol {Warnings for Almost Everything} uses the \c
                    -Weverything option with negative options to suppress some
                    warnings.
152

153
            \endlist
154

155 156 157 158 159 160 161
            You can edit the predefined configurations to request specific
            warnings beginning with \c -W. Each of these warnings also has a
            negative version that begins with \c -Wno. Keep in mind that some
            options turn on other options. For more information, see
            \l{https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html}
            {Options to Request or Suppress Warnings} or the GCC or Clang
            manual pages.
162

163
        \li To process pre-compiled headers, deselect the
164
            \uicontrol {Ignore pre-compiled headers} check box.
165

166 167 168 169 170 171
        \li To avoid out-of-memory crashes caused by indexing huge source files
            that are typically auto-generated by scripts or code, the size of
            files to index is limited to 5MB by default. To adjust the limit,
            edit the value for the \uicontrol {Do not index files greater than}
            check box. To index all files, deselect the check box.

172 173 174
    \endlist

*/