From 59b37370650091862414d96e81a3b09173df5448 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Wed, 30 May 2018 17:55:50 +0200 Subject: Doc: Edit information about Clang Code Model and Tools Change-Id: I8482e34ce056dd9b6a5a20a0a7a2c7603ea9a4b0 Reviewed-by: Nikolai Kosjar --- .../qtcreator-clang-code-model-build-settings.png | Bin 43490 -> 10377 bytes doc/images/qtcreator-clang-code-model-options.png | Bin 60132 -> 22674 bytes .../qtcreator-clang-static-analyzer-options.png | Bin 4922 -> 0 bytes doc/images/qtcreator-clang-static-analyzer.png | Bin 10550 -> 0 bytes doc/images/qtcreator-clang-tidy.png | Bin 16381 -> 20385 bytes doc/images/qtcreator-clang-tools-options.png | Bin 0 -> 14187 bytes doc/images/qtcreator-clang-tools.png | Bin 0 -> 247291 bytes doc/images/qtcreator-diagnostics-configuration.png | Bin 0 -> 28934 bytes doc/images/qtcreator-files-to-analyze.png | Bin 0 -> 16992 bytes doc/src/analyze/creator-analyze.qdoc | 9 +- doc/src/analyze/creator-clang-static-analyzer.qdoc | 130 ++++++++++++++------- doc/src/analyze/creator-heob.qdoc | 2 +- doc/src/analyze/creator-valgrind.qdoc | 2 +- doc/src/editors/creator-clang-codemodel.qdoc | 119 +++++++------------ doc/src/editors/creator-editors-writing-code.qdoc | 11 +- .../creator-projects-settings-overview.qdoc | 2 +- doc/src/qtcreator-toc.qdoc | 2 +- 17 files changed, 148 insertions(+), 129 deletions(-) delete mode 100644 doc/images/qtcreator-clang-static-analyzer-options.png delete mode 100644 doc/images/qtcreator-clang-static-analyzer.png create mode 100644 doc/images/qtcreator-clang-tools-options.png create mode 100644 doc/images/qtcreator-clang-tools.png create mode 100644 doc/images/qtcreator-diagnostics-configuration.png create mode 100644 doc/images/qtcreator-files-to-analyze.png (limited to 'doc') diff --git a/doc/images/qtcreator-clang-code-model-build-settings.png b/doc/images/qtcreator-clang-code-model-build-settings.png index cc7d3d8cf9..05fa864b7c 100644 Binary files a/doc/images/qtcreator-clang-code-model-build-settings.png and b/doc/images/qtcreator-clang-code-model-build-settings.png differ diff --git a/doc/images/qtcreator-clang-code-model-options.png b/doc/images/qtcreator-clang-code-model-options.png index 99351af363..1a42643d07 100644 Binary files a/doc/images/qtcreator-clang-code-model-options.png and b/doc/images/qtcreator-clang-code-model-options.png differ diff --git a/doc/images/qtcreator-clang-static-analyzer-options.png b/doc/images/qtcreator-clang-static-analyzer-options.png deleted file mode 100644 index e12d71ffa6..0000000000 Binary files a/doc/images/qtcreator-clang-static-analyzer-options.png and /dev/null differ diff --git a/doc/images/qtcreator-clang-static-analyzer.png b/doc/images/qtcreator-clang-static-analyzer.png deleted file mode 100644 index c9a1886ab0..0000000000 Binary files a/doc/images/qtcreator-clang-static-analyzer.png and /dev/null differ diff --git a/doc/images/qtcreator-clang-tidy.png b/doc/images/qtcreator-clang-tidy.png index 156eb23d9d..bcf753b4f5 100644 Binary files a/doc/images/qtcreator-clang-tidy.png and b/doc/images/qtcreator-clang-tidy.png differ diff --git a/doc/images/qtcreator-clang-tools-options.png b/doc/images/qtcreator-clang-tools-options.png new file mode 100644 index 0000000000..9a6cdc36d1 Binary files /dev/null and b/doc/images/qtcreator-clang-tools-options.png differ diff --git a/doc/images/qtcreator-clang-tools.png b/doc/images/qtcreator-clang-tools.png new file mode 100644 index 0000000000..d1bd031788 Binary files /dev/null and b/doc/images/qtcreator-clang-tools.png differ diff --git a/doc/images/qtcreator-diagnostics-configuration.png b/doc/images/qtcreator-diagnostics-configuration.png new file mode 100644 index 0000000000..736a749c60 Binary files /dev/null and b/doc/images/qtcreator-diagnostics-configuration.png differ diff --git a/doc/images/qtcreator-files-to-analyze.png b/doc/images/qtcreator-files-to-analyze.png new file mode 100644 index 0000000000..f3ac5ad49d Binary files /dev/null and b/doc/images/qtcreator-files-to-analyze.png differ diff --git a/doc/src/analyze/creator-analyze.qdoc b/doc/src/analyze/creator-analyze.qdoc index 7e1a76e289..0b21852ab9 100644 --- a/doc/src/analyze/creator-analyze.qdoc +++ b/doc/src/analyze/creator-analyze.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2016 The Qt Company Ltd. +** Copyright (C) 2018 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Creator documentation. @@ -65,11 +65,10 @@ You can detect problems in memory management by using the Memcheck tool and find cache misses in the code by using the Callgrind tool. - \li \l{Using Clang Static Analyzer}{Clang Static Analyzer} + \li \l{Using Clang Tools}{Clang Tools} - You can detect problems in C, C++, and - Objective-C programs by using the experimental plugin that - integrates the Clang Static Analyzer source code analysis tool. + You can detect problems in C, C++, and Objective-C programs by + using Clang-Tidy and Clazy. \li \l{Detecting Memory Leaks with Heob} diff --git a/doc/src/analyze/creator-clang-static-analyzer.qdoc b/doc/src/analyze/creator-clang-static-analyzer.qdoc index 521b4da864..66ef1cd97c 100644 --- a/doc/src/analyze/creator-clang-static-analyzer.qdoc +++ b/doc/src/analyze/creator-clang-static-analyzer.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2016 The Qt Company Ltd. +** Copyright (C) 2018 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Creator documentation. @@ -32,63 +32,113 @@ /*! \contentspage {Qt Creator Manual} \previouspage creator-running-valgrind-remotely.html - \page creator-clang-static-analyzer.html + \page creator-clang-tools.html \nextpage creator-heob.html - \title Using Clang Static Analyzer + \title Using Clang Tools - \QC integrates the \l{http://clang-analyzer.llvm.org} - {Clang Static Analyzer} for finding problems in C, C++, and Objective-C - programs. + \QC integrates the following Clang tools for finding problems in C, C++, and + Objective-C source code by using static analysis: - \image qtcreator-clang-static-analyzer.png + \list + + \li \l{https://clang.llvm.org/extra/clang-tidy/}{Clang-Tidy}, which + provides diagnostics and fixes for typical programming errors, + such as style violations or interface misuse. + + \li \l{https://github.com/KDE/clazy/blob/master/README.md}{Clazy}, which + helps Clang understand Qt semantics. It displays Qt related compiler + warnings, ranging from unnecessary memory allocation to misuse of + API and provides refactoring actions for fixing some of the issues. + + \endlist + + \note The Clang static analyzer checks are a part of Clang-Tidy. To use + the checks you must create a custom configuration for the Clang tools and + enable them for Clang-Tidy. + + Clang tools are delivered and installed with \QC, and therefore you do not + need to set them up separately. + + \section1 Running Clang Tools + + To run the Clang tools to analyze an open project: + + \list 1 + + \li Select \uicontrol Analyze > \uicontrol {Clang-Tidy and Clazy}. + + \image qtcreator-files-to-analyze.png + + \li In the \uicontrol {Diagnostic Configuration} group, select + \uicontrol Custom, and then select \uicontrol Manage to + specify the Clang-Tidy and Clazy checks to perform. + + \li Select the new custom configuration in the list of configurations + (1). + + \li In the \uicontrol {Files to Analyze} group, select the files to + apply the checks to. + + \li Select \uicontrol Analyze to start the checks. + + \endlist + + If you select \uicontrol Debug in the mode selector to open the + \uicontrol Debug mode and then select \uicontrol {Clang-Tidy and Clazy}, + you must select the \inlineimage qtcreator-analyze-start-button.png + (\uicontrol Start) button to open the \uicontrol {Analyzer Configuration} + dialog. + + \image qtcreator-clang-tools.png Select the link in the \uicontrol Location column to move to the location where the issue appears in the code editor. - The Clang Static Analyzer runs with all the default checkers enabled. For - more information about the checkers, see - \l{http://clang-analyzer.llvm.org/available_checks.html}{Available Checkers}. + In the \uicontrol {Fixit Status} column, select issues that you want to + apply refactoring actions to, and then select \uicontrol {Apply Fixits}. + The status of the issues is updated in the \uicontrol {Fixit Status} column. - To suppress diagnostics, select \uicontrol {Suppress This Diagnostic} in the - context menu. To view the suppression list for a project and to remove - diagnostics from it, select \uicontrol Projects > - \uicontrol {Project Settings} > \uicontrol {Clang Static Analyzer}. + \section1 Configuring Clang Tools + + To configure Clang diagnostics globally for Clang tools: - \section1 Supported Project Types and Tool Chains + \list - The Clang Static Analyzer relies on the data (specific macros and include - directories) from the projects and tool chains. Not all projects - and tool chains can provide enough data for reasonable results. + \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Analyzer > + \uicontrol {Clang Tools} > \uicontrol Manage. - Currently, only Qbs and qmake projects together with the GCC, MinGW, Clang - and Microsoft Visual Studio tool chains are supported. + \image qtcreator-clang-tools-options.png - \section1 Setting Up Clang Static Analyzer + \li In the \uicontrol {Clang-Tidy} tab, select the checks to + perform. - As a tested version of Clang is shipped together with Qt Creator, no manual - setup is required. + \image qtcreator-clang-tidy.png - To profit from improved checkers in newer Clang versions, \QC can be set up - to use those. However, only the shipped version of Clang is tested and known - to work. Other versions might not work at all. + \li To edit the selected check as plain text, select + \uicontrol {Edit Checks as String}. - To set up a particular Clang version for the Clang Static Analyzer, select - \uicontrol Tools > \uicontrol Options > \uicontrol Analyzer > - \uicontrol {Clang Static Analyzer} and check that the path to the Clang - executable is set correctly in the \uicontrol {Clang executable} field. + \li In the \uicontrol Clazy tab, select the level of Clazy + checks to perform. + + \image qtcreator-clazy.png + + \endlist + + To suppress diagnostics, select \uicontrol {Suppress This Diagnostic} in the + context menu. To view the suppression list for a project and to remove + diagnostics from it, select \uicontrol Projects > + \uicontrol {Project Settings} > \uicontrol {Clang Tools}. - \image qtcreator-clang-static-analyzer-options.png + \section2 Selecting Clazy Check Levels - \section1 Running Clang Static Analyzer + The Clazy checks are divided into levels from 0 to 3. Each level adds checks + to the previous level. The checks at level 0 are very stable and provide + hardly any false positives, while the checks at level 3 can be considered + experimental. - To run the Clang Static Analyzer to analyze an open project, select - \uicontrol Analyze > \uicontrol {Clang Static Analyzer} on the menu bar. The - Clang Static Analyzer starts automatically. + For more information about the checks run at each level, see + \l{https://github.com/KDE/clazy/blob/master/README.md#list-of-checks} + {List of Checks} in the Clazy documentation. - However, if you select \uicontrol Debug in the mode selector to open the - \uicontrol Debug mode and then select \uicontrol {Clang Static Analyzer}, - you must start the Clang Static Analyzer by selecting the - \inlineimage qtcreator-analyze-start-button.png - (\uicontrol Start) button. */ diff --git a/doc/src/analyze/creator-heob.qdoc b/doc/src/analyze/creator-heob.qdoc index d8c2fae57c..3fba9aca8f 100644 --- a/doc/src/analyze/creator-heob.qdoc +++ b/doc/src/analyze/creator-heob.qdoc @@ -31,7 +31,7 @@ /*! \contentspage {Qt Creator Manual} - \previouspage creator-clang-static-analyzer.html + \previouspage creator-clang-tools.html \page creator-heob.html \nextpage creator-cpu-usage-analyzer.html diff --git a/doc/src/analyze/creator-valgrind.qdoc b/doc/src/analyze/creator-valgrind.qdoc index ce1ed1f345..e52bd67d70 100644 --- a/doc/src/analyze/creator-valgrind.qdoc +++ b/doc/src/analyze/creator-valgrind.qdoc @@ -263,7 +263,7 @@ \contentspage {Qt Creator Manual} \previouspage creator-cache-profiler.html \page creator-running-valgrind-remotely.html - \nextpage creator-clang-static-analyzer.html + \nextpage creator-clang-tools.html \title Running Valgrind Tools on External Applications diff --git a/doc/src/editors/creator-clang-codemodel.qdoc b/doc/src/editors/creator-clang-codemodel.qdoc index 92e786e518..c15717b956 100644 --- a/doc/src/editors/creator-clang-codemodel.qdoc +++ b/doc/src/editors/creator-clang-codemodel.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2016 The Qt Company Ltd. +** Copyright (C) 2018 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Creator documentation. @@ -54,7 +54,9 @@ \li Inspecting code by using the \l{Browsing Project Contents} {class browser}, the \l{Viewing QML Types}{outline}, and so on - \li Diagnostics and \l{Viewing Function Tooltips}{tooltips} + \li Diagnostics + + \li \l{Viewing Function Tooltips}{Tooltips} \li \l{Finding Symbols}{Finding and renaming symbols} @@ -85,79 +87,36 @@ include several files, processing a single file and all the included files can take a while. - The Clang code model plugin replaces services of the old C/C++ code model. - Currently the following services are implemented: + The Clang code model plugin now provides some of the services that were + previously provided by the built-in C/C++ code model. Currently, the + following services are implemented: \list \li Code completion \li Syntactic and semantic highlighting - \li Diagnostics - \li Clang-Tidy checks - \li Clazy checks + \li \l{Using Clang Tools}{Diagnostics} \li Outline of symbols \li Tooltips \li Renaming of local symbols \endlist - \section1 Code Model Warnings + To use the built-in code model instead, select \uicontrol Help > + \uicontrol {About Plugins} > \uicontrol C++, and deselect the + \uicontrol ClangCodeModel check box. The changes take effect after + you restart \QC. - The predefined configurations request Clang warnings at the following - levels: + You can configure Clang diagnostics either globally or separately for: \list - - \li \uicontrol {Pedantic Warnings} uses the \c -Wpendantic option that - requests all the warnings demanded by strict ISO C and ISO C++. - - \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. - - \li \uicontrol {Warnings for Almost Everything} uses the \c -Weverything - option with negative options to suppress some warnings. - + \li Clang code model (globally or at project level) + \li Clang tools (globally or at project level) \endlist - 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. - - \section1 Using Clang-Tidy Checks - - \l{https://clang.llvm.org/extra/clang-tidy/}{Clang-Tidy} is delivered - as a part of the Clang library delivered with \QC. It provides diagnostics - and fixes for typical programming errors, such as style violations, - interface misuse, or issues that can be found via static analysis. - - \QC integrates the fixes and diagnostics into the Clang library, and - therefore they cannot be easily changed or extended when used with \QC. - - \section1 Using Clazy - - \l{https://github.com/KDE/clazy/blob/master/README.md}{Clazy} is delivered - as a part of the Clang library delivered with \QC. It helps Clang understand - Qt semantics. It prints out Qt related compiler warnings, ranging from - unnecessary memory allocation to misuse of API and provides refactoring - actions for fixing some of the issues. - - The Clazy checks are divided into levels from 0 to 3. Each level adds checks - to the previous level. The checks at level 0 are very stable and provide - hardly any false positives, while the checks at level 3 can be considered - experimental. - - For more information about the checks run at each level, see - \l{https://github.com/KDE/clazy/blob/master/README.md#list-of-checks} - {List of Checks} in the Clazy documentation. - \section1 Configuring Clang Code Model - To specify settings for the Clang code model: + To configure the Clang code model globally: \list 1 @@ -179,34 +138,46 @@ edit the value for the \uicontrol {Do not index files greater than} check box. To index all files, deselect the check box. - \li In \uicontrol {Clang Dianostics}, select one of the predefined - configurations, or select \uicontrol Copy to create a copy of a - configuration and edit it to fit your needs. + \li Select \uicontrol Manage to specify the level for requesting Clang + warnings. - \list + \image qtcreator-diagnostics-configuration.png - \li In the \uicontrol Clang tab, edit the predefined - configuration to request specific warnings. + \endlist - \li In the \uicontrol {Clang-Tidy} tab, select the checks to - perform. + \section1 Clang Warnings - \image qtcreator-clang-tidy.png + The predefined configurations request Clang warnings at the following + levels: + + \list - \li In the \uicontrol Clazy tab, select the level of Clazy - checks to perform. + \li \uicontrol {Pedantic Warnings} uses the \c -Wpendantic option that + requests all the warnings demanded by strict ISO C and ISO C++. - \image qtcreator-clazy.png + \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. - \endlist + \li \uicontrol {Warnings for Almost Everything} uses the \c -Weverything + option with negative options to suppress some warnings. \endlist - \section1 Specifying Clang Settings at Project Level + 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. + + \section1 Specifying Clang Code Model Settings at Project Level + + You can specify Clang code model settings at project level by selecting + \uicontrol Projects > \uicontrol {Clang Code Model}. - You can specify Clang settings at project level in the build settings of - the project by selecting \uicontrol Projects > - \uicontrol {Clang Code Model}. In addition to configuring the diagnostics, + In addition to configuring the diagnostics, you can select the \uicontrol {Enable MSVC-compliant template parsing} check box to parse templates in a MSVC-compliant way. This enables Clang to parse headers for example from Active Template Library (ATL) or Windows Runtime diff --git a/doc/src/editors/creator-editors-writing-code.qdoc b/doc/src/editors/creator-editors-writing-code.qdoc index fc358a9bd2..6524880a51 100644 --- a/doc/src/editors/creator-editors-writing-code.qdoc +++ b/doc/src/editors/creator-editors-writing-code.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2016 The Qt Company Ltd. +** Copyright (C) 2018 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Creator documentation. @@ -111,11 +111,10 @@ \li \l{Parsing C++ Files with the Clang Code Model} - A Clang code model plugin enables you to replace the - built-in \QC code model with the Clang code model. Clang is a C - language family front end for LLVM. Clang provides you with more - accurate information than the built-in code model but can be slower - to use for large projects. + The Clang code model provides some of the services previously + provided by the built-in C/C++ code model, such as code + completion, syntactic and semantic highlighting, diagnostics, + tooltips, outline of symbols, and renaming of local symbols. \endlist diff --git a/doc/src/projects/creator-projects-settings-overview.qdoc b/doc/src/projects/creator-projects-settings-overview.qdoc index 11e788951b..687a2df6d1 100644 --- a/doc/src/projects/creator-projects-settings-overview.qdoc +++ b/doc/src/projects/creator-projects-settings-overview.qdoc @@ -104,7 +104,7 @@ \li \l{Parsing C++ Files with the Clang Code Model} {Clang Code Model} - \li \l{Using Clang Static Analyzer}{Clang Static Analyzer} + \li \l{Using Clang Tools}{Clang Tools} \li \l{To-Do Entries}{To-Do} (experimental) diff --git a/doc/src/qtcreator-toc.qdoc b/doc/src/qtcreator-toc.qdoc index bda42932fb..f9e3907665 100644 --- a/doc/src/qtcreator-toc.qdoc +++ b/doc/src/qtcreator-toc.qdoc @@ -178,7 +178,7 @@ \li \l{Profiling Function Execution} \li \l{Running Valgrind Tools on External Applications} \endlist - \li \l{Using Clang Static Analyzer} + \li \l{Using Clang Tools} \li \l{Detecting Memory Leaks with Heob} \li \l{Analyzing CPU Usage} \endlist -- cgit v1.2.3