diff options
Diffstat (limited to 'docs')
68 files changed, 2334 insertions, 1045 deletions
diff --git a/docs/README.txt b/docs/README.txt index 4b607775..cebbf63b 100644 --- a/docs/README.txt +++ b/docs/README.txt @@ -1,11 +1,10 @@ -------------------------------------------------------------- -Documentation for the tools of clang-tools-extra repo project -------------------------------------------------------------- +---------------------------------- +Documentation in clang-tools-extra +---------------------------------- -Sphinx and doxygen documentation is generated by executing make. +To generate documentation in HTML format from files in clang-tools-extra/docs, +build the docs-clang-tools-html target. -Sphinx html files can be generated separately using make html. +To generate documentation from the source code using Doxygen, build the +doxygen-clang-tools target. -Doxygen html files can also be generated using make doxygen. - -The generated documentation will be placed in _build/html. diff --git a/docs/ReleaseNotes.rst b/docs/ReleaseNotes.rst index 8731dc73..bb18c6ed 100644 --- a/docs/ReleaseNotes.rst +++ b/docs/ReleaseNotes.rst @@ -1,5 +1,5 @@ =================================================== -Extra Clang Tools 8.0.0 (In-Progress) Release Notes +Extra Clang Tools 9.0.0 (In-Progress) Release Notes =================================================== .. contents:: @@ -10,7 +10,7 @@ Written by the `LLVM Team <https://llvm.org/>`_ .. warning:: - These are in-progress notes for the upcoming Extra Clang Tools 8 release. + These are in-progress notes for the upcoming Extra Clang Tools 9 release. Release notes for previous releases can be found on `the Download Page <https://releases.llvm.org/download.html>`_. @@ -18,7 +18,7 @@ Introduction ============ This document contains the release notes for the Extra Clang Tools, part of the -Clang release 8.0.0. Here we describe the status of the Extra Clang Tools in +Clang release 9.0.0. Here we describe the status of the Extra Clang Tools in some detail, including major improvements from the previous release and new feature work. All LLVM releases may be downloaded from the `LLVM releases web site <https://llvm.org/releases/>`_. @@ -32,7 +32,7 @@ main Clang web page, this document applies to the *next* release, not the current one. To see the release notes for a specific release, please see the `releases page <https://llvm.org/releases/>`_. -What's New in Extra Clang Tools 8.0.0? +What's New in Extra Clang Tools 9.0.0? ====================================== Some of the major new features and improvements to Extra Clang Tools are listed @@ -57,47 +57,7 @@ The improvements are... Improvements to clang-query --------------------------- -- A new command line parameter ``--preload`` was added to - run commands from a file and then start the interactive interpreter. - -- The command ``q`` can was added as an alias for ``quit`` to exit the - ``clang-query`` interpreter. - -- It is now possible to bind to named values (the result of ``let`` - expressions). For example: - - .. code-block:: none - - let fn functionDecl() - match fn.bind("foo") - -- It is now possible to write comments in ``clang-query`` code. This - is primarily useful when using script-mode. Comments are all content - following the ``#`` character on a line: - - .. code-block:: none - - # This is a comment - match fn.bind("foo") # This is a trailing comment - -- The new ``set print-matcher true`` command now causes ``clang-query`` to - print the evaluated matcher together with the resulting bindings. - -- A new output mode ``detailed-ast`` was added to ``clang-query``. The - existing ``dump`` output mode is now a deprecated alias - for ``detailed-ast`` - -- Output modes can now be enabled or disabled non-exclusively. For example, - - .. code-block:: none - - # Enable detailed-ast without disabling other output, such as diag - enable output detailed-ast - m functionDecl() - - # Disable detailed-ast only - disable output detailed-ast - m functionDecl() +- ... Improvements to clang-rename ---------------------------- @@ -107,204 +67,105 @@ The improvements are... Improvements to clang-tidy -------------------------- -- New :doc:`abseil-duration-comparison - <clang-tidy/checks/abseil-duration-comparison>` check. - - Checks for comparisons which should be done in the ``absl::Duration`` domain - instead of the float of integer domains. - -- New :doc:`abseil-duration-division - <clang-tidy/checks/abseil-duration-division>` check. - - Checks for uses of ``absl::Duration`` division that is done in a - floating-point context, and recommends the use of a function that - returns a floating-point value. - -- New :doc:`abseil-duration-factory-float - <clang-tidy/checks/abseil-duration-factory-float>` check. - - Checks for cases where the floating-point overloads of various - ``absl::Duration`` factory functions are called when the more-efficient - integer versions could be used instead. - -- New :doc:`abseil-duration-factory-scale - <clang-tidy/checks/abseil-duration-factory-scale>` check. - - Checks for cases where arguments to ``absl::Duration`` factory functions are - scaled internally and could be changed to a different factory function. - -- New :doc:`abseil-duration-subtraction - <clang-tidy/checks/abseil-duration-subtraction>` check. - - Checks for cases where subtraction should be performed in the - ``absl::Duration`` domain. +- New OpenMP module. -- New :doc:`abseil-faster-strsplit-delimiter - <clang-tidy/checks/abseil-faster-strsplit-delimiter>` check. + For checks specific to `OpenMP <https://www.openmp.org/>`_ API. - Finds instances of ``absl::StrSplit()`` or ``absl::MaxSplits()`` where the - delimiter is a single character string literal and replaces with a character. +- New :doc:`abseil-duration-addition + <clang-tidy/checks/abseil-duration-addition>` check. -- New :doc:`abseil-no-internal-dependencies - <clang-tidy/checks/abseil-no-internal-dependencies>` check. + Checks for cases where addition should be performed in the ``absl::Time`` + domain. - Gives a warning if code using Abseil depends on internal details. +- New :doc:`abseil-duration-conversion-cast + <clang-tidy/checks/abseil-duration-conversion-cast>` check. -- New :doc:`abseil-no-namespace - <clang-tidy/checks/abseil-no-namespace>` check. + Checks for casts of ``absl::Duration`` conversion functions, and recommends + the right conversion function instead. - Ensures code does not open ``namespace absl`` as that violates Abseil's - compatibility guidelines. +- New :doc:`abseil-duration-unnecessary-conversion + <clang-tidy/checks/abseil-duration-unnecessary-conversion>` check. -- New :doc:`abseil-redundant-strcat-calls - <clang-tidy/checks/abseil-redundant-strcat-calls>` check. + Finds and fixes cases where ``absl::Duration`` values are being converted to + numeric types and back again. - Suggests removal of unnecessary calls to ``absl::StrCat`` when the result is - being passed to another ``absl::StrCat`` or ``absl::StrAppend``. +- New :doc:`abseil-time-comparison + <clang-tidy/checks/abseil-time-comparison>` check. -- New :doc:`abseil-str-cat-append - <clang-tidy/checks/abseil-str-cat-append>` check. + Prefer comparisons in the ``absl::Time`` domain instead of the integer + domain. - Flags uses of ``absl::StrCat()`` to append to a ``std::string``. Suggests - ``absl::StrAppend()`` should be used instead. +- New :doc:`abseil-time-subtraction + <clang-tidy/checks/abseil-time-subtraction>` check. -- New :doc:`abseil-upgrade-duration-conversions - <clang-tidy/checks/abseil-upgrade-duration-conversions>` check. + Finds and fixes ``absl::Time`` subtraction expressions to do subtraction + in the Time domain instead of the numeric domain. - Finds calls to ``absl::Duration`` arithmetic operators and factories whose - argument needs an explicit cast to continue compiling after upcoming API - changes. +- New :doc:`google-readability-avoid-underscore-in-googletest-name + <clang-tidy/checks/google-readability-avoid-underscore-in-googletest-name>` + check. -- New :doc:`bugprone-too-small-loop-variable - <clang-tidy/checks/bugprone-too-small-loop-variable>` check. + Checks whether there are underscores in googletest test and test case names in + test macros, which is prohibited by the Googletest FAQ. - Detects those ``for`` loops that have a loop variable with a "too small" type - which means this type can't represent all values which are part of the - iteration range. +- New :doc:`objc-super-self <clang-tidy/checks/objc-super-self>` check. -- New :doc:`cppcoreguidelines-macro-usage - <clang-tidy/checks/cppcoreguidelines-macro-usage>` check. + Finds invocations of ``-self`` on super instances in initializers of + subclasses of ``NSObject`` and recommends calling a superclass initializer + instead. - Finds macro usage that is considered problematic because better language - constructs exist for the task. +- New alias :doc:`cppcoreguidelines-explicit-virtual-functions + <clang-tidy/checks/cppcoreguidelines-explicit-virtual-functions>` to + :doc:`modernize-use-override + <clang-tidy/checks/modernize-use-override>` was added. -- New :doc:`google-objc-function-naming - <clang-tidy/checks/google-objc-function-naming>` check. +- The :doc:`bugprone-argument-comment + <clang-tidy/checks/bugprone-argument-comment>` now supports + `CommentBoolLiterals`, `CommentIntegerLiterals`, `CommentFloatLiterals`, + `CommentUserDefiniedLiterals`, `CommentStringLiterals`, + `CommentCharacterLiterals` & `CommentNullPtrs` options. - Checks that function names in function declarations comply with the naming - conventions described in the Google Objective-C Style Guide. +- The :doc:`bugprone-too-small-loop-variable + <clang-tidy/checks/bugprone-too-small-loop-variable>` now supports + `MagnitudeBitsUpperLimit` option. The default value was set to 16, + which greatly reduces warnings related to loops which are unlikely to + cause an actual functional bug. -- New :doc:`misc-non-private-member-variables-in-classes - <clang-tidy/checks/misc-non-private-member-variables-in-classes>` check. +- The :doc:`google-runtime-int <clang-tidy/checks/google-runtime-int>` + check has been disabled in Objective-C++. - Finds classes that not only contain the data (non-static member variables), - but also have logic (non-static member functions), and diagnoses all member - variables that have any other scope other than ``private``. +- The `Acronyms` and `IncludeDefaultAcronyms` options for the + :doc:`objc-property-declaration <clang-tidy/checks/objc-property-declaration>` + check have been removed. -- New :doc:`modernize-avoid-c-arrays - <clang-tidy/checks/modernize-avoid-c-arrays>` check. +- The :doc:`modernize-use-override + <clang-tidy/checks/modernize-use-override>` now supports `OverrideSpelling` + and `FinalSpelling` options. - Finds C-style array types and recommend to use ``std::array<>`` / - ``std::vector<>``. +- New :doc:`llvm-prefer-isa-or-dyn-cast-in-conditionals + <clang-tidy/checks/llvm-prefer-isa-or-dyn-cast-in-conditionals>` check. -- New :doc:`modernize-concat-nested-namespaces - <clang-tidy/checks/modernize-concat-nested-namespaces>` check. + Looks at conditionals and finds and replaces cases of ``cast<>``, + which will assert rather than return a null pointer, and + ``dyn_cast<>`` where the return value is not captured. Additionally, + finds and replaces cases that match the pattern ``var && + isa<X>(var)``, where ``var`` is evaluated twice. - Checks for uses of nested namespaces in the form of - ``namespace a { namespace b { ... }}`` and offers change to - syntax introduced in C++17 standard: ``namespace a::b { ... }``. +- New :doc:`openmp-exception-escape + <clang-tidy/checks/openmp-exception-escape>` check. -- New :doc:`modernize-deprecated-ios-base-aliases - <clang-tidy/checks/modernize-deprecated-ios-base-aliases>` check. + Analyzes OpenMP Structured Blocks and checks that no exception escapes + out of the Structured Block it was thrown in. - Detects usage of the deprecated member types of ``std::ios_base`` and replaces - those that have a non-deprecated equivalent. +- New :doc:`openmp-use-default-none + <clang-tidy/checks/openmp-use-default-none>` check. -- New :doc:`modernize-use-nodiscard - <clang-tidy/checks/modernize-use-nodiscard>` check. + Finds OpenMP directives that are allowed to contain a ``default`` clause, + but either don't specify it or the clause is specified but with the kind + other than ``none``, and suggests to use the ``default(none)`` clause. - Adds ``[[nodiscard]]`` attributes (introduced in C++17) to member functions - to highlight at compile time which return values should not be ignored. - -- New :doc:`readability-isolate-decl - <clang-tidy/checks/readability-isolate-declaration>` check. - - Detects local variable declarations declaring more than one variable and - tries to refactor the code to one statement per declaration. - -- New :doc:`readability-const-return-type - <clang-tidy/checks/readability-const-return-type>` check. - - Checks for functions with a ``const``-qualified return type and recommends - removal of the ``const`` keyword. - -- New :doc:`readability-magic-numbers - <clang-tidy/checks/readability-magic-numbers>` check. - - Detects usage of magic numbers, numbers that are used as literals instead of - introduced via constants or symbols. - -- New :doc:`readability-redundant-preprocessor - <clang-tidy/checks/readability-redundant-preprocessor>` check. - - Finds potentially redundant preprocessor directives. - -- New :doc:`readability-uppercase-literal-suffix - <clang-tidy/checks/readability-uppercase-literal-suffix>` check. - - Detects when the integral literal or floating point literal has non-uppercase - suffix, and suggests to make the suffix uppercase. The list of destination - suffixes can be optionally provided. - -- New alias :doc:`cert-dcl16-c - <clang-tidy/checks/cert-dcl16-c>` to :doc:`readability-uppercase-literal-suffix - <clang-tidy/checks/readability-uppercase-literal-suffix>` - added. - -- New alias :doc:`cppcoreguidelines-avoid-c-arrays - <clang-tidy/checks/cppcoreguidelines-avoid-c-arrays>` - to :doc:`modernize-avoid-c-arrays - <clang-tidy/checks/modernize-avoid-c-arrays>` added. - -- New alias :doc:`cppcoreguidelines-non-private-member-variables-in-classes - <clang-tidy/checks/cppcoreguidelines-non-private-member-variables-in-classes>` - to :doc:`misc-non-private-member-variables-in-classes - <clang-tidy/checks/misc-non-private-member-variables-in-classes>` - added. - -- New alias :doc:`hicpp-avoid-c-arrays - <clang-tidy/checks/hicpp-avoid-c-arrays>` - to :doc:`modernize-avoid-c-arrays - <clang-tidy/checks/modernize-avoid-c-arrays>` added. - -- New alias :doc:`hicpp-uppercase-literal-suffix - <clang-tidy/checks/hicpp-uppercase-literal-suffix>` to - :doc:`readability-uppercase-literal-suffix - <clang-tidy/checks/readability-uppercase-literal-suffix>` - added. - -- The :doc:`cppcoreguidelines-narrowing-conversions - <clang-tidy/checks/cppcoreguidelines-narrowing-conversions>` check now - detects more narrowing conversions: - - integer to narrower signed integer (this is compiler implementation defined), - - integer - floating point narrowing conversions, - - floating point - integer narrowing conversions, - - constants with narrowing conversions (even in ternary operator). - -- The :doc:`objc-property-declaration - <clang-tidy/checks/objc-property-declaration>` check now ignores the - `Acronyms` and `IncludeDefaultAcronyms` options. - -- The :doc:`readability-redundant-smartptr-get - <clang-tidy/checks/readability-redundant-smartptr-get>` check does not warn - about calls inside macros anymore by default. - -- The :doc:`readability-uppercase-literal-suffix - <clang-tidy/checks/readability-uppercase-literal-suffix>` check does not warn - about literal suffixes inside macros anymore by default. - -Improvements to include-fixer ------------------------------ +Improvements to clang-include-fixer +----------------------------------- The improvements are... @@ -312,3 +173,9 @@ Improvements to modularize -------------------------- The improvements are... + +Improvements to pp-trace +------------------------ + +- Added a new option `-callbacks` to filter preprocessor callbacks. It replaces + the `-ignore` option. diff --git a/docs/_static/clang-tools-extra-styles.css b/docs/_static/clang-tools-extra-styles.css new file mode 100644 index 00000000..1a6cd710 --- /dev/null +++ b/docs/_static/clang-tools-extra-styles.css @@ -0,0 +1,23 @@ +details { + background-color: rgba(50, 150, 220, 0.08); + margin-bottom: 0.5em; + padding: 0 1em; + overflow-y: hidden; /* Suppress margin-collapsing */ +} +details[open] { + border-bottom: 1px solid rgba(0, 0, 128, 0.2); + margin-bottom: 1em; +} +details summary { + font-weight: bold; + background-color: rgba(50, 150, 220, 0.1); + border-color: rgba(0, 0, 128, 0.2); + border-width: 1px; + border-style: solid none; + padding: 0.2em; + margin: 0 -1em; +} +details summary:hover { + background-color: rgba(50, 150, 220, 0.2); + cursor: pointer; +} diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html new file mode 100644 index 00000000..b4f5b4e1 --- /dev/null +++ b/docs/_templates/layout.html @@ -0,0 +1,3 @@ +{% extends "!layout.html" %} + +{% set css_files = css_files + ['_static/clang-tools-extra-styles.css'] %} diff --git a/docs/clang-doc.rst b/docs/clang-doc.rst index f891b71a..96120687 100644 --- a/docs/clang-doc.rst +++ b/docs/clang-doc.rst @@ -20,10 +20,10 @@ Use ===== :program:`clang-doc` is a `LibTooling -<http://clang.llvm.org/docs/LibTooling.html>`_-based tool, and so requires a +<https://clang.llvm.org/docs/LibTooling.html>`_-based tool, and so requires a compile command database for your project (for an example of how to do this see `How To Setup Tooling For LLVM -<http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html>`_). +<https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html>`_). The tool can be used on a single file or multiple files as defined in the compile commands database: diff --git a/docs/include-fixer.rst b/docs/clang-include-fixer.rst index fcd2998b..783f45ef 100644 --- a/docs/include-fixer.rst +++ b/docs/clang-include-fixer.rst @@ -32,7 +32,7 @@ them up if called with a source file from that tree. Note that by default ``compile_commands.json`` as generated by CMake does not include header files, so only implementation files can be handled by tools. -.. _How To Setup Tooling For LLVM: http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html +.. _How To Setup Tooling For LLVM: https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html Creating a Symbol Index From a Compilation Database --------------------------------------------------- @@ -49,7 +49,7 @@ database for LLVM, any project built by CMake should follow similar steps. $ ninja clang-include-fixer // build clang-include-fixer tool. $ ls compile_commands.json # Make sure compile_commands.json exists. compile_commands.json - $ path/to/llvm/source/tools/clang/tools/extra/include-fixer/find-all-symbols/tool/run-find-all-symbols.py + $ path/to/llvm/source/tools/clang/tools/extra/clang-include-fixer/find-all-symbols/tool/run-find-all-symbols.py ... wait as clang indexes the code base ... $ ln -s $PWD/find_all_symbols_db.yaml path/to/llvm/source/ # Link database into the source tree. $ ln -s $PWD/compile_commands.json path/to/llvm/source/ # Also link compilation database if it's not there already. @@ -64,7 +64,7 @@ following key binding to your ``.vimrc``: .. code-block:: console - noremap <leader>cf :pyf path/to/llvm/source/tools/clang/tools/extra/include-fixer/tool/clang-include-fixer.py<cr> + noremap <leader>cf :pyf path/to/llvm/source/tools/clang/tools/extra/clang-include-fixer/tool/clang-include-fixer.py<cr> This enables `clang-include-fixer` for NORMAL and VISUAL mode. Change `<leader>cf` to another binding if you need clang-include-fixer on a different @@ -118,7 +118,7 @@ in your ``.emacs``: .. code-block:: console - (add-to-list 'load-path "path/to/llvm/source/tools/clang/tools/extra/include-fixer/tool/" + (add-to-list 'load-path "path/to/llvm/source/tools/clang/tools/extra/clang-include-fixer/tool/" (require 'clang-include-fixer) Within Emacs the tool can be invoked with the command diff --git a/docs/clang-rename.rst b/docs/clang-rename.rst index f6227795..2796141f 100644 --- a/docs/clang-rename.rst +++ b/docs/clang-rename.rst @@ -24,10 +24,10 @@ Using Clang-Rename ================== :program:`clang-rename` is a `LibTooling -<http://clang.llvm.org/docs/LibTooling.html>`_-based tool, and it's easier to +<https://clang.llvm.org/docs/LibTooling.html>`_-based tool, and it's easier to work with if you set up a compile command database for your project (for an example of how to do this see `How To Setup Tooling For LLVM -<http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html>`_). You can also +<https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html>`_). You can also specify compilation options on the command line after `--`: .. code-block:: console @@ -139,8 +139,8 @@ Vim Integration You can call :program:`clang-rename` directly from Vim! To set up :program:`clang-rename` integration for Vim see -`clang-rename/tool/clang-rename.py -<http://reviews.llvm.org/diffusion/L/browse/clang-tools-extra/trunk/clang-rename/tool/clang-rename.py>`_. +`clang/tools/clang-rename/clang-rename.py +<https://github.com/llvm/llvm-project/blob/master/clang/tools/clang-rename/clang-rename.py>`_. Please note that **you have to save all buffers, in which the replacement will happen before running the tool**. @@ -157,7 +157,7 @@ Emacs Integration You can also use :program:`clang-rename` while using Emacs! To set up :program:`clang-rename` integration for Emacs see `clang-rename/tool/clang-rename.el -<http://reviews.llvm.org/diffusion/L/browse/clang-tools-extra/trunk/clang-rename/tool/clang-rename.el>`_. +<https://github.com/llvm/llvm-project/blob/master/clang/tools/clang-rename/clang-rename.el>`_. Once installed, you can point your cursor to symbols you want to rename, press `M-X`, type `clang-rename` and new desired name. diff --git a/docs/clang-tidy.rst b/docs/clang-tidy.rst index bcd2bf1e..b9a18069 100644 --- a/docs/clang-tidy.rst +++ b/docs/clang-tidy.rst @@ -3,4 +3,4 @@ .. meta:: :http-equiv=refresh: 0;URL='clang-tidy/' -clang-tidy documentation has moved here: http://clang.llvm.org/extra/clang-tidy/ +clang-tidy documentation has moved here: https://clang.llvm.org/extra/clang-tidy/ diff --git a/docs/clang-tidy/Contributing.rst b/docs/clang-tidy/Contributing.rst new file mode 100644 index 00000000..09ff1f65 --- /dev/null +++ b/docs/clang-tidy/Contributing.rst @@ -0,0 +1,513 @@ +================ +Getting Involved +================ + +:program:`clang-tidy` has several own checks and can run Clang static analyzer +checks, but its power is in the ability to easily write custom checks. + +Checks are organized in modules, which can be linked into :program:`clang-tidy` +with minimal or no code changes in :program:`clang-tidy`. + +Checks can plug into the analysis on the preprocessor level using `PPCallbacks`_ +or on the AST level using `AST Matchers`_. When an error is found, checks can +report them in a way similar to how Clang diagnostics work. A fix-it hint can be +attached to a diagnostic message. + +The interface provided by :program:`clang-tidy` makes it easy to write useful +and precise checks in just a few lines of code. If you have an idea for a good +check, the rest of this document explains how to do this. + +There are a few tools particularly useful when developing clang-tidy checks: + * ``add_new_check.py`` is a script to automate the process of adding a new + check, it will create the check, update the CMake file and create a test; + * ``rename_check.py`` does what the script name suggests, renames an existing + check; + * :program:`clang-query` is invaluable for interactive prototyping of AST + matchers and exploration of the Clang AST; + * `clang-check`_ with the ``-ast-dump`` (and optionally ``-ast-dump-filter``) + provides a convenient way to dump AST of a C++ program. + +If CMake is configured with ``CLANG_ENABLE_STATIC_ANALYZER``, +:program:`clang-tidy` will not be built with support for the +``clang-analyzer-*`` checks or the ``mpi-*`` checks. + + +.. _AST Matchers: https://clang.llvm.org/docs/LibASTMatchers.html +.. _PPCallbacks: https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html +.. _clang-check: https://clang.llvm.org/docs/ClangCheck.html + + +Choosing the Right Place for your Check +--------------------------------------- + +If you have an idea of a check, you should decide whether it should be +implemented as a: + ++ *Clang diagnostic*: if the check is generic enough, targets code patterns that + most probably are bugs (rather than style or readability issues), can be + implemented effectively and with extremely low false positive rate, it may + make a good Clang diagnostic. + ++ *Clang static analyzer check*: if the check requires some sort of control flow + analysis, it should probably be implemented as a static analyzer check. + ++ *clang-tidy check* is a good choice for linter-style checks, checks that are + related to a certain coding style, checks that address code readability, etc. + + +Preparing your Workspace +------------------------ + +If you are new to LLVM development, you should read the `Getting Started with +the LLVM System`_, `Using Clang Tools`_ and `How To Setup Clang Tooling For +LLVM`_ documents to check out and build LLVM, Clang and Clang Extra Tools with +CMake. + +Once you are done, change to the ``llvm/tools/clang/tools/extra`` directory, and +let's start! + +.. _Getting Started with the LLVM System: https://llvm.org/docs/GettingStarted.html +.. _Using Clang Tools: https://clang.llvm.org/docs/ClangTools.html +.. _How To Setup Clang Tooling For LLVM: https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html + + +The Directory Structure +----------------------- + +:program:`clang-tidy` source code resides in the +``llvm/tools/clang/tools/extra`` directory and is structured as follows: + +:: + + clang-tidy/ # Clang-tidy core. + |-- ClangTidy.h # Interfaces for users. + |-- ClangTidyCheck.h # Interfaces for checks. + |-- ClangTidyModule.h # Interface for clang-tidy modules. + |-- ClangTidyModuleRegistry.h # Interface for registering of modules. + ... + |-- google/ # Google clang-tidy module. + |-+ + |-- GoogleTidyModule.cpp + |-- GoogleTidyModule.h + ... + |-- llvm/ # LLVM clang-tidy module. + |-+ + |-- LLVMTidyModule.cpp + |-- LLVMTidyModule.h + ... + |-- objc/ # Objective-C clang-tidy module. + |-+ + |-- ObjCTidyModule.cpp + |-- ObjCTidyModule.h + ... + |-- tool/ # Sources of the clang-tidy binary. + ... + test/clang-tidy/ # Integration tests. + ... + unittests/clang-tidy/ # Unit tests. + |-- ClangTidyTest.h + |-- GoogleModuleTest.cpp + |-- LLVMModuleTest.cpp + |-- ObjCModuleTest.cpp + ... + + +Writing a clang-tidy Check +-------------------------- + +So you have an idea of a useful check for :program:`clang-tidy`. + +First, if you're not familiar with LLVM development, read through the `Getting +Started with LLVM`_ document for instructions on setting up your workflow and +the `LLVM Coding Standards`_ document to familiarize yourself with the coding +style used in the project. For code reviews we mostly use `LLVM Phabricator`_. + +.. _Getting Started with LLVM: https://llvm.org/docs/GettingStarted.html +.. _LLVM Coding Standards: https://llvm.org/docs/CodingStandards.html +.. _LLVM Phabricator: https://llvm.org/docs/Phabricator.html + +Next, you need to decide which module the check belongs to. Modules +are located in subdirectories of `clang-tidy/ +<https://github.com/llvm/llvm-project/tree/master/clang-tools-extra/clang-tidy/>`_ +and contain checks targeting a certain aspect of code quality (performance, +readability, etc.), certain coding style or standard (Google, LLVM, CERT, etc.) +or a widely used API (e.g. MPI). Their names are same as user-facing check +groups names described :ref:`above <checks-groups-table>`. + +After choosing the module and the name for the check, run the +``clang-tidy/add_new_check.py`` script to create the skeleton of the check and +plug it to :program:`clang-tidy`. It's the recommended way of adding new checks. + +If we want to create a `readability-awesome-function-names`, we would run: + +.. code-block:: console + + $ clang-tidy/add_new_check.py readability awesome-function-names + + +The ``add_new_check.py`` script will: + * create the class for your check inside the specified module's directory and + register it in the module and in the build system; + * create a lit test file in the ``test/clang-tidy/`` directory; + * create a documentation file and include it into the + ``docs/clang-tidy/checks/list.rst``. + +Let's see in more detail at the check class definition: + +.. code-block:: c++ + + ... + + #include "../ClangTidyCheck.h" + + namespace clang { + namespace tidy { + namespace readability { + + ... + class AwesomeFunctionNamesCheck : public ClangTidyCheck { + public: + AwesomeFunctionNamesCheck(StringRef Name, ClangTidyContext *Context) + : ClangTidyCheck(Name, Context) {} + void registerMatchers(ast_matchers::MatchFinder *Finder) override; + void check(const ast_matchers::MatchFinder::MatchResult &Result) override; + }; + + } // namespace readability + } // namespace tidy + } // namespace clang + + ... + +Constructor of the check receives the ``Name`` and ``Context`` parameters, and +must forward them to the ``ClangTidyCheck`` constructor. + +In our case the check needs to operate on the AST level and it overrides the +``registerMatchers`` and ``check`` methods. If we wanted to analyze code on the +preprocessor level, we'd need instead to override the ``registerPPCallbacks`` +method. + +In the ``registerMatchers`` method we create an AST Matcher (see `AST Matchers`_ +for more information) that will find the pattern in the AST that we want to +inspect. The results of the matching are passed to the ``check`` method, which +can further inspect them and report diagnostics. + +.. code-block:: c++ + + using namespace ast_matchers; + + void AwesomeFunctionNamesCheck::registerMatchers(MatchFinder *Finder) { + Finder->addMatcher(functionDecl().bind("x"), this); + } + + void AwesomeFunctionNamesCheck::check(const MatchFinder::MatchResult &Result) { + const auto *MatchedDecl = Result.Nodes.getNodeAs<FunctionDecl>("x"); + if (MatchedDecl->getName().startswith("awesome_")) + return; + diag(MatchedDecl->getLocation(), "function %0 is insufficiently awesome") + << MatchedDecl + << FixItHint::CreateInsertion(MatchedDecl->getLocation(), "awesome_"); + } + +(If you want to see an example of a useful check, look at +`clang-tidy/google/ExplicitConstructorCheck.h +<https://github.com/llvm/llvm-project/blob/master/clang-tools-extra/clang-tidy/google/ExplicitConstructorCheck.h>`_ +and `clang-tidy/google/ExplicitConstructorCheck.cpp +<https://reviews.llvm.org/diffusion/L/browse/clang-tools-extra/trunk/clang-tidy/google/ExplicitConstructorCheck.cpp>`_). + + +Registering your Check +---------------------- + +(The ``add_new_check.py`` takes care of registering the check in an existing +module. If you want to create a new module or know the details, read on.) + +The check should be registered in the corresponding module with a distinct name: + +.. code-block:: c++ + + class MyModule : public ClangTidyModule { + public: + void addCheckFactories(ClangTidyCheckFactories &CheckFactories) override { + CheckFactories.registerCheck<ExplicitConstructorCheck>( + "my-explicit-constructor"); + } + }; + +Now we need to register the module in the ``ClangTidyModuleRegistry`` using a +statically initialized variable: + +.. code-block:: c++ + + static ClangTidyModuleRegistry::Add<MyModule> X("my-module", + "Adds my lint checks."); + + +When using LLVM build system, we need to use the following hack to ensure the +module is linked into the :program:`clang-tidy` binary: + +Add this near the ``ClangTidyModuleRegistry::Add<MyModule>`` variable: + +.. code-block:: c++ + + // This anchor is used to force the linker to link in the generated object file + // and thus register the MyModule. + volatile int MyModuleAnchorSource = 0; + +And this to the main translation unit of the :program:`clang-tidy` binary (or +the binary you link the ``clang-tidy`` library in) +``clang-tidy/tool/ClangTidyMain.cpp``: + +.. code-block:: c++ + + // This anchor is used to force the linker to link the MyModule. + extern volatile int MyModuleAnchorSource; + static int MyModuleAnchorDestination = MyModuleAnchorSource; + + +Configuring Checks +------------------ + +If a check needs configuration options, it can access check-specific options +using the ``Options.get<Type>("SomeOption", DefaultValue)`` call in the check +constructor. In this case the check should also override the +``ClangTidyCheck::storeOptions`` method to make the options provided by the +check discoverable. This method lets :program:`clang-tidy` know which options +the check implements and what the current values are (e.g. for the +``-dump-config`` command line option). + +.. code-block:: c++ + + class MyCheck : public ClangTidyCheck { + const unsigned SomeOption1; + const std::string SomeOption2; + + public: + MyCheck(StringRef Name, ClangTidyContext *Context) + : ClangTidyCheck(Name, Context), + SomeOption(Options.get("SomeOption1", -1U)), + SomeOption(Options.get("SomeOption2", "some default")) {} + + void storeOptions(ClangTidyOptions::OptionMap &Opts) override { + Options.store(Opts, "SomeOption1", SomeOption1); + Options.store(Opts, "SomeOption2", SomeOption2); + } + ... + +Assuming the check is registered with the name "my-check", the option can then +be set in a ``.clang-tidy`` file in the following way: + +.. code-block:: yaml + + CheckOptions: + - key: my-check.SomeOption1 + value: 123 + - key: my-check.SomeOption2 + value: 'some other value' + +If you need to specify check options on a command line, you can use the inline +YAML format: + +.. code-block:: console + + $ clang-tidy -config="{CheckOptions: [{key: a, value: b}, {key: x, value: y}]}" ... + + +Testing Checks +-------------- + +To run tests for :program:`clang-tidy` use the command: + +.. code-block:: console + + $ ninja check-clang-tools + +:program:`clang-tidy` checks can be tested using either unit tests or +`lit`_ tests. Unit tests may be more convenient to test complex replacements +with strict checks. `Lit`_ tests allow using partial text matching and regular +expressions which makes them more suitable for writing compact tests for +diagnostic messages. + +The ``check_clang_tidy.py`` script provides an easy way to test both +diagnostic messages and fix-its. It filters out ``CHECK`` lines from the test +file, runs :program:`clang-tidy` and verifies messages and fixes with two +separate `FileCheck`_ invocations: once with FileCheck's directive +prefix set to ``CHECK-MESSAGES``, validating the diagnostic messages, +and once with the directive prefix set to ``CHECK-FIXES``, running +against the fixed code (i.e., the code after generated fix-its are +applied). In particular, ``CHECK-FIXES:`` can be used to check +that code was not modified by fix-its, by checking that it is present +unchanged in the fixed code. The full set of `FileCheck`_ directives +is available (e.g., ``CHECK-MESSAGES-SAME:``, ``CHECK-MESSAGES-NOT:``), though +typically the basic ``CHECK`` forms (``CHECK-MESSAGES`` and ``CHECK-FIXES``) +are sufficient for clang-tidy tests. Note that the `FileCheck`_ +documentation mostly assumes the default prefix (``CHECK``), and hence +describes the directive as ``CHECK:``, ``CHECK-SAME:``, ``CHECK-NOT:``, etc. +Replace ``CHECK`` by either ``CHECK-FIXES`` or ``CHECK-MESSAGES`` for +clang-tidy tests. + +An additional check enabled by ``check_clang_tidy.py`` ensures that +if `CHECK-MESSAGES:` is used in a file then every warning or error +must have an associated CHECK in that file. Or, you can use ``CHECK-NOTES:`` +instead, if you want to **also** ensure that all the notes are checked. + +To use the ``check_clang_tidy.py`` script, put a .cpp file with the +appropriate ``RUN`` line in the ``test/clang-tidy`` directory. Use +``CHECK-MESSAGES:`` and ``CHECK-FIXES:`` lines to write checks against +diagnostic messages and fixed code. + +It's advised to make the checks as specific as possible to avoid checks matching +to incorrect parts of the input. Use ``[[@LINE+X]]``/``[[@LINE-X]]`` +substitutions and distinct function and variable names in the test code. + +Here's an example of a test using the ``check_clang_tidy.py`` script (the full +source code is at `test/clang-tidy/google-readability-casting.cpp`_): + +.. code-block:: c++ + + // RUN: %check_clang_tidy %s google-readability-casting %t + + void f(int a) { + int b = (int)a; + // CHECK-MESSAGES: :[[@LINE-1]]:11: warning: redundant cast to the same type [google-readability-casting] + // CHECK-FIXES: int b = a; + } + +To check more than one scenario in the same test file use +``-check-suffix=SUFFIX-NAME`` on ``check_clang_tidy.py`` command line or +``-check-suffixes=SUFFIX-NAME-1,SUFFIX-NAME-2,...``. +With ``-check-suffix[es]=SUFFIX-NAME`` you need to replace your ``CHECK-*`` +directives with ``CHECK-MESSAGES-SUFFIX-NAME`` and ``CHECK-FIXES-SUFFIX-NAME``. + +Here's an example: + +.. code-block:: c++ + + // RUN: %check_clang_tidy -check-suffix=USING-A %s misc-unused-using-decls %t -- -- -DUSING_A + // RUN: %check_clang_tidy -check-suffix=USING-B %s misc-unused-using-decls %t -- -- -DUSING_B + // RUN: %check_clang_tidy %s misc-unused-using-decls %t + ... + // CHECK-MESSAGES-USING-A: :[[@LINE-8]]:10: warning: using decl 'A' {{.*}} + // CHECK-MESSAGES-USING-B: :[[@LINE-7]]:10: warning: using decl 'B' {{.*}} + // CHECK-MESSAGES: :[[@LINE-6]]:10: warning: using decl 'C' {{.*}} + // CHECK-FIXES-USING-A-NOT: using a::A;$ + // CHECK-FIXES-USING-B-NOT: using a::B;$ + // CHECK-FIXES-NOT: using a::C;$ + + +There are many dark corners in the C++ language, and it may be difficult to make +your check work perfectly in all cases, especially if it issues fix-it hints. The +most frequent pitfalls are macros and templates: + +1. code written in a macro body/template definition may have a different meaning + depending on the macro expansion/template instantiation; +2. multiple macro expansions/template instantiations may result in the same code + being inspected by the check multiple times (possibly, with different + meanings, see 1), and the same warning (or a slightly different one) may be + issued by the check multiple times; :program:`clang-tidy` will deduplicate + _identical_ warnings, but if the warnings are slightly different, all of them + will be shown to the user (and used for applying fixes, if any); +3. making replacements to a macro body/template definition may be fine for some + macro expansions/template instantiations, but easily break some other + expansions/instantiations. + +.. _lit: https://llvm.org/docs/CommandGuide/lit.html +.. _FileCheck: https://llvm.org/docs/CommandGuide/FileCheck.html +.. _test/clang-tidy/google-readability-casting.cpp: https://reviews.llvm.org/diffusion/L/browse/clang-tools-extra/trunk/test/clang-tidy/google-readability-casting.cpp + + +Running clang-tidy on LLVM +-------------------------- + +To test a check it's best to try it out on a larger code base. LLVM and Clang +are the natural targets as you already have the source code around. The most +convenient way to run :program:`clang-tidy` is with a compile command database; +CMake can automatically generate one, for a description of how to enable it see +`How To Setup Clang Tooling For LLVM`_. Once ``compile_commands.json`` is in +place and a working version of :program:`clang-tidy` is in ``PATH`` the entire +code base can be analyzed with ``clang-tidy/tool/run-clang-tidy.py``. The script +executes :program:`clang-tidy` with the default set of checks on every +translation unit in the compile command database and displays the resulting +warnings and errors. The script provides multiple configuration flags. + +.. _How To Setup Clang Tooling For LLVM: https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html + + +* The default set of checks can be overridden using the ``-checks`` argument, + taking the identical format as :program:`clang-tidy` does. For example + ``-checks=-*,modernize-use-override`` will run the ``modernize-use-override`` + check only. + +* To restrict the files examined you can provide one or more regex arguments + that the file names are matched against. + ``run-clang-tidy.py clang-tidy/.*Check\.cpp`` will only analyze clang-tidy + checks. It may also be necessary to restrict the header files warnings are + displayed from using the ``-header-filter`` flag. It has the same behavior + as the corresponding :program:`clang-tidy` flag. + +* To apply suggested fixes ``-fix`` can be passed as an argument. This gathers + all changes in a temporary directory and applies them. Passing ``-format`` + will run clang-format over changed lines. + + +On checks profiling +------------------- + +:program:`clang-tidy` can collect per-check profiling info, and output it +for each processed source file (translation unit). + +To enable profiling info collection, use the ``-enable-check-profile`` argument. +The timings will be output to ``stderr`` as a table. Example output: + +.. code-block:: console + + $ clang-tidy -enable-check-profile -checks=-*,readability-function-size source.cpp + ===-------------------------------------------------------------------------=== + clang-tidy checks profiling + ===-------------------------------------------------------------------------=== + Total Execution Time: 1.0282 seconds (1.0258 wall clock) + + ---User Time--- --System Time-- --User+System-- ---Wall Time--- --- Name --- + 0.9136 (100.0%) 0.1146 (100.0%) 1.0282 (100.0%) 1.0258 (100.0%) readability-function-size + 0.9136 (100.0%) 0.1146 (100.0%) 1.0282 (100.0%) 1.0258 (100.0%) Total + +It can also store that data as JSON files for further processing. Example output: + +.. code-block:: console + + $ clang-tidy -enable-check-profile -store-check-profile=. -checks=-*,readability-function-size source.cpp + $ # Note that there won't be timings table printed to the console. + $ ls /tmp/out/ + 20180516161318717446360-source.cpp.json + $ cat 20180516161318717446360-source.cpp.json + { + "file": "/path/to/source.cpp", + "timestamp": "2018-05-16 16:13:18.717446360", + "profile": { + "time.clang-tidy.readability-function-size.wall": 1.0421266555786133e+00, + "time.clang-tidy.readability-function-size.user": 9.2088400000005421e-01, + "time.clang-tidy.readability-function-size.sys": 1.2418899999999974e-01 + } + } + +There is only one argument that controls profile storage: + +* ``-store-check-profile=<prefix>`` + + By default reports are printed in tabulated format to stderr. When this option + is passed, these per-TU profiles are instead stored as JSON. + If the prefix is not an absolute path, it is considered to be relative to the + directory from where you have run :program:`clang-tidy`. All ``.`` and ``..`` + patterns in the path are collapsed, and symlinks are resolved. + + Example: + Let's suppose you have a source file named ``example.cpp``, located in the + ``/source`` directory. Only the input filename is used, not the full path + to the source file. Additionally, it is prefixed with the current timestamp. + + * If you specify ``-store-check-profile=/tmp``, then the profile will be saved + to ``/tmp/<ISO8601-like timestamp>-example.cpp.json`` + + * If you run :program:`clang-tidy` from within ``/foo`` directory, and specify + ``-store-check-profile=.``, then the profile will still be saved to + ``/foo/<ISO8601-like timestamp>-example.cpp.json`` diff --git a/docs/clang-tidy/Integrations.rst b/docs/clang-tidy/Integrations.rst new file mode 100644 index 00000000..ba08bf7f --- /dev/null +++ b/docs/clang-tidy/Integrations.rst @@ -0,0 +1,117 @@ +================================== +Clang-tidy IDE/Editor Integrations +================================== + +.. _Clangd: https://clang.llvm.org/extra/clangd.html + +Apart from being a standalone tool, :program:`clang-tidy` is integrated into +various IDEs, code analyzers, and editors. Besides, it is currently being +integrated into Clangd_. The following table shows the most +well-known :program:`clang-tidy` integrations in detail. + ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+ +| | Feature | ++======================================+========================+=================================+==========================+=========================================+==========================+ +| **Tool** | On-the-fly inspection | Check list configuration (GUI) | Options to checks (GUI) | Configuration via ``.clang-tidy`` files | Custom clang-tidy binary | ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+ +|A.L.E. for Vim | \+\ | \-\ | \-\ | \-\ | \+\ | ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+ +|Clang Power Tools for Visual Studio | \-\ | \+\ | \-\ | \+\ | \-\ | ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+ +|Clangd | \+\ | \-\ | \-\ | \-\ | \-\ | ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+ +|CLion IDE | \+\ | \+\ | \+\ | \+\ | \+\ | ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+ +|CodeChecker | \-\ | \-\ | \-\ | \-\ | \+\ | ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+ +|CPPCheck | \-\ | \-\ | \-\ | \-\ | \-\ | ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+ +|CPPDepend | \-\ | \-\ | \-\ | \-\ | \-\ | ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+ +|Flycheck for Emacs | \+\ | \-\ | \-\ | \+\ | \+\ | ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+ +|KDevelop IDE | \-\ | \+\ | \+\ | \+\ | \+\ | ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+ +|Qt Creator IDE | \+\ | \+\ | \-\ | \-\ | \+\ | ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+ +|ReSharper C++ for Visual Studio | \+\ | \+\ | \-\ | \+\ | \-\ | ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+ +|Syntastic for Vim | \+\ | \-\ | \-\ | \-\ | \+\ | ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+ +|Visual Assist for Visual Studio | \+\ | \+\ | \-\ | \-\ | \-\ | ++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+ + +**IDEs** + +.. _CLion: https://www.jetbrains.com/clion/ +.. _integrates clang-tidy: https://www.jetbrains.com/help/clion/clang-tidy-checks-support.html + +CLion_ 2017.2 and later `integrates clang-tidy`_ as an extension to the +built-in code analyzer. Starting from 2018.2 EAP, CLion allows using +:program:`clang-tidy` via Clangd. Inspections and applicable quick-fixes are +performed on the fly, and checks can be configured in standard command line +format. In this integration, you can switch to the :program:`clang-tidy` +binary different from the bundled one, pass the configuration in +``.clang-tidy`` files instead of using the IDE settings, and configure +options for particular checks. + +.. _KDevelop: https://www.kdevelop.org/ +.. _kdev-clang-tidy: https://github.com/KDE/kdev-clang-tidy/ + +KDevelop_ with the kdev-clang-tidy_ plugin, starting from version 5.1, performs +static analysis using :program:`clang-tidy`. The plugin launches the +:program:`clang-tidy` binary from the specified location and parses its +output to provide a list of issues. + +.. _QtCreator: https://www.qt.io/ +.. _Clang Code Model: https://doc.qt.io/qtcreator/creator-clang-codemodel.html + +QtCreator_ 4.6 integrates :program:`clang-tidy` warnings into the editor +diagnostics under the `Clang Code Model`_. To employ :program:`clang-tidy` +inspection in QtCreator, you need to create a copy of one of the presets and +choose the checks to be performed in the Clang Code Model Warnings menu. + +.. _MS Visual Studio: https://visualstudio.microsoft.com/ +.. _ReSharper C++: https://www.jetbrains.com/help/resharper/Clang_Tidy_Integration.html +.. _Visual Assist: https://docs.wholetomato.com/default.asp?W761 +.. _Clang Power Tools: https://marketplace.visualstudio.com/items?itemName=caphyon.ClangPowerTools +.. _clang-tidy-vs: https://github.com/llvm/llvm-project/tree/master/clang-tools-extra/clang-tidy-vs + +`MS Visual Studio`_ has a native clang-tidy-vs_ plugin and also can integrate +:program:`clang-tidy` by means of three other tools. The `ReSharper C++`_ +extension, version 2017.3 and later, provides seamless :program:`clang-tidy` +integration: checks and quick-fixes run alongside native inspections. Apart +from that, ReSharper C++ incorporates :program:`clang-tidy` as a separate +step of its code clean-up process. `Visual Assist`_ build 2210 includes a +subset of :program:`clang-tidy` checklist to inspect the code as you edit. +Another way to bring :program:`clang-tidy` functionality to Visual Studio is +the `Clang Power Tools`_ plugin, which includes most of the +:program:`clang-tidy` checks and runs them during compilation or as a separate +step of code analysis. + +**Editors** + +.. _Flycheck: https://github.com/ch1bo/flycheck-clang-tidy +.. _Syntastic: https://github.com/vim-syntastic/syntastic +.. _A.L.E.: https://github.com/w0rp/ale +.. _Emacs24: https://www.gnu.org/s/emacs/ +.. _Vim: https://www.vim.org/ + +Emacs24_, when expanded with the Flycheck_ plugin, incorporates the +:program:`clang-tidy` inspection into the syntax analyzer. For Vim_, you can +use Syntastic_, which includes :program:`clang-tidy`, or `A.L.E.`_, +a lint engine that applies :program:`clang-tidy` along with other linters. + +**Analyzers** + +.. _CPPDepend: https://www.cppdepend.com/cppdependv2018 +.. _CPPCheck: https://sourceforge.net/p/cppcheck/news/ +.. _CodeChecker: https://github.com/Ericsson/codechecker +.. _plugin: https://github.com/Ericsson/CodeCheckerEclipsePlugin + +:program:`clang-tidy` is integrated in CPPDepend_ starting from version 2018.1 +and CPPCheck_ 1.82. CPPCheck integration lets you import Visual Studio +solutions and run the :program:`clang-tidy` inspection on them. The +CodeChecker_ application of version 5.3 or later, which also comes as a plugin_ +for Eclipse, supports :program:`clang-tidy` as a static analysis instrument and +allows to use a custom :program:`clang-tidy` binary. diff --git a/docs/clang-tidy/checks/abseil-duration-addition.rst b/docs/clang-tidy/checks/abseil-duration-addition.rst new file mode 100644 index 00000000..2f3d805e --- /dev/null +++ b/docs/clang-tidy/checks/abseil-duration-addition.rst @@ -0,0 +1,21 @@ +.. title:: clang-tidy - abseil-duration-addition + +abseil-duration-addition +======================== + +Check for cases where addition should be performed in the ``absl::Time`` domain. +When adding two values, and one is known to be an ``absl::Time``, we can infer +that the other should be interpreted as an ``absl::Duration`` of a similar +scale, and make that inference explicit. + +Examples: + +.. code-block:: c++ + + // Original - Addition in the integer domain + int x; + absl::Time t; + int result = absl::ToUnixSeconds(t) + x; + + // Suggestion - Addition in the absl::Time domain + int result = absl::TounixSeconds(t + absl::Seconds(x)); diff --git a/docs/clang-tidy/checks/abseil-duration-conversion-cast.rst b/docs/clang-tidy/checks/abseil-duration-conversion-cast.rst new file mode 100644 index 00000000..3c1a152b --- /dev/null +++ b/docs/clang-tidy/checks/abseil-duration-conversion-cast.rst @@ -0,0 +1,31 @@ +.. title:: clang-tidy - abseil-duration-conversion-cast + +abseil-duration-conversion-cast +=============================== + +Checks for casts of ``absl::Duration`` conversion functions, and recommends +the right conversion function instead. + +Examples: + +.. code-block:: c++ + + // Original - Cast from a double to an integer + absl::Duration d; + int i = static_cast<int>(absl::ToDoubleSeconds(d)); + + // Suggested - Use the integer conversion function directly. + int i = absl::ToInt64Seconds(d); + + + // Original - Cast from a double to an integer + absl::Duration d; + double x = static_cast<double>(absl::ToInt64Seconds(d)); + + // Suggested - Use the integer conversion function directly. + double x = absl::ToDoubleSeconds(d); + + +Note: In the second example, the suggested fix could yield a different result, +as the conversion to integer could truncate. In practice, this is very rare, +and you should use ``absl::Trunc`` to perform this operation explicitly instead. diff --git a/docs/clang-tidy/checks/abseil-duration-subtraction.rst b/docs/clang-tidy/checks/abseil-duration-subtraction.rst index 884eeb2c..b570931b 100644 --- a/docs/clang-tidy/checks/abseil-duration-subtraction.rst +++ b/docs/clang-tidy/checks/abseil-duration-subtraction.rst @@ -21,7 +21,6 @@ Examples: // Suggestion - Subtraction in the absl::Duration domain instead double result = absl::ToDoubleSeconds(d - absl::Seconds(x)); - // Original - Subtraction of two Durations in the double domain absl::Duration d1, d2; double result = absl::ToDoubleSeconds(d1) - absl::ToDoubleSeconds(d2); @@ -29,6 +28,7 @@ Examples: // Suggestion - Subtraction in the absl::Duration domain instead double result = absl::ToDoubleSeconds(d1 - d2); + Note: As with other ``clang-tidy`` checks, it is possible that multiple fixes may overlap (as in the case of nested expressions), so not all occurences can be transformed in one run. In particular, this may occur for nested subtraction diff --git a/docs/clang-tidy/checks/abseil-duration-unnecessary-conversion.rst b/docs/clang-tidy/checks/abseil-duration-unnecessary-conversion.rst new file mode 100644 index 00000000..2f978f4d --- /dev/null +++ b/docs/clang-tidy/checks/abseil-duration-unnecessary-conversion.rst @@ -0,0 +1,46 @@ +.. title:: clang-tidy - abseil-duration-unnecessary-conversion + +abseil-duration-unnecessary-conversion +====================================== + +Finds and fixes cases where ``absl::Duration`` values are being converted to +numeric types and back again. + +Floating-point examples: + +.. code-block:: c++ + + // Original - Conversion to double and back again + absl::Duration d1; + absl::Duration d2 = absl::Seconds(absl::ToDoubleSeconds(d1)); + + // Suggestion - Remove unnecessary conversions + absl::Duration d2 = d1; + + // Original - Division to convert to double and back again + absl::Duration d2 = absl::Seconds(absl::FDivDuration(d1, absl::Seconds(1))); + + // Suggestion - Remove division and conversion + absl::Duration d2 = d1; + +Integer examples: + +.. code-block:: c++ + + // Original - Conversion to integer and back again + absl::Duration d1; + absl::Duration d2 = absl::Hours(absl::ToInt64Hours(d1)); + + // Suggestion - Remove unnecessary conversions + absl::Duration d2 = d1; + + // Original - Integer division followed by conversion + absl::Duration d2 = absl::Seconds(d1 / absl::Seconds(1)); + + // Suggestion - Remove division and conversion + absl::Duration d2 = d1; + +Note: Converting to an integer and back to an ``absl::Duration`` might be a +truncating operation if the value is not aligned to the scale of conversion. +In the rare case where this is the intended result, callers should use +``absl::Trunc`` to truncate explicitly. diff --git a/docs/clang-tidy/checks/abseil-time-comparison.rst b/docs/clang-tidy/checks/abseil-time-comparison.rst new file mode 100644 index 00000000..9342e4cf --- /dev/null +++ b/docs/clang-tidy/checks/abseil-time-comparison.rst @@ -0,0 +1,23 @@ +.. title:: clang-tidy - abseil-time-comparison + +abseil-time-comparison +====================== + +Prefer comparisons in the ``absl::Time`` domain instead of the integer domain. + +N.B.: In cases where an ``absl::Time`` is being converted to an integer, +alignment may occur. If the comparison depends on this alignment, doing the +comparison in the ``absl::Time`` domain may yield a different result. In +practice this is very rare, and still indicates a bug which should be fixed. + +Examples: + +.. code-block:: c++ + + // Original - Comparison in the integer domain + int x; + absl::Time t; + if (x < absl::ToUnixSeconds(t)) ... + + // Suggested - Compare in the absl::Time domain instead + if (absl::FromUnixSeconds(x) < t) ... diff --git a/docs/clang-tidy/checks/abseil-time-subtraction.rst b/docs/clang-tidy/checks/abseil-time-subtraction.rst new file mode 100644 index 00000000..196c0736 --- /dev/null +++ b/docs/clang-tidy/checks/abseil-time-subtraction.rst @@ -0,0 +1,39 @@ +.. title:: clang-tidy - abseil-time-subtraction + +abseil-time-subtraction +======================= + +Finds and fixes ``absl::Time`` subtraction expressions to do subtraction +in the Time domain instead of the numeric domain. + +There are two cases of Time subtraction in which deduce additional type +information: + +- When the result is an ``absl::Duration`` and the first argument is an + ``absl::Time``. +- When the second argument is a ``absl::Time``. + +In the first case, we must know the result of the operation, since without that +the second operand could be either an ``absl::Time`` or an ``absl::Duration``. +In the second case, the first operand *must* be an ``absl::Time``, because +subtracting an ``absl::Time`` from an ``absl::Duration`` is not defined. + +Examples: + +.. code-block:: c++ + + int x; + absl::Time t; + + // Original - absl::Duration result and first operand is a absl::Time. + absl::Duration d = absl::Seconds(absl::ToUnixSeconds(t) - x); + + // Suggestion - Perform subtraction in the Time domain instead. + absl::Duration d = t - absl::FromUnixSeconds(x); + + + // Original - Second operand is an absl::Time. + int i = x - absl::ToUnixSeconds(t); + + // Suggestion - Perform subtraction in the Time domain instead. + int i = absl::ToInt64Seconds(absl::FromUnixSeconds(x) - t); diff --git a/docs/clang-tidy/checks/bugprone-argument-comment.rst b/docs/clang-tidy/checks/bugprone-argument-comment.rst index 5f7e5f0d..afc12186 100644 --- a/docs/clang-tidy/checks/bugprone-argument-comment.rst +++ b/docs/clang-tidy/checks/bugprone-argument-comment.rst @@ -27,3 +27,158 @@ Options When zero (default value), the check will ignore leading and trailing underscores and case when comparing names -- otherwise they are taken into account. + +.. option:: CommentBoolLiterals + + When true, the check will add argument comments in the format + ``/*ParameterName=*/`` right before the boolean literal argument. + +Before: + +.. code-block:: c++ + + void foo(bool TurnKey, bool PressButton); + + foo(true, false); + +After: + +.. code-block:: c++ + + void foo(bool TurnKey, bool PressButton); + + foo(/*TurnKey=*/true, /*PressButton=*/false); + +.. option:: CommentIntegerLiterals + + When true, the check will add argument comments in the format + ``/*ParameterName=*/`` right before the integer literal argument. + +Before: + +.. code-block:: c++ + + void foo(int MeaningOfLife); + + foo(42); + +After: + +.. code-block:: c++ + + void foo(int MeaningOfLife); + + foo(/*MeaningOfLife=*/42); + +.. option:: CommentFloatLiterals + + When true, the check will add argument comments in the format + ``/*ParameterName=*/`` right before the float/double literal argument. + +Before: + +.. code-block:: c++ + + void foo(float Pi); + + foo(3.14159); + +After: + +.. code-block:: c++ + + void foo(float Pi); + + foo(/*Pi=*/3.14159); + +.. option:: CommentStringLiterals + + When true, the check will add argument comments in the format + ``/*ParameterName=*/`` right before the string literal argument. + +Before: + +.. code-block:: c++ + + void foo(const char *String); + void foo(const wchar_t *WideString); + + foo("Hello World"); + foo(L"Hello World"); + +After: + +.. code-block:: c++ + + void foo(const char *String); + void foo(const wchar_t *WideString); + + foo(/*String=*/"Hello World"); + foo(/*WideString=*/L"Hello World"); + +.. option:: CommentCharacterLiterals + + When true, the check will add argument comments in the format + ``/*ParameterName=*/`` right before the character literal argument. + +Before: + +.. code-block:: c++ + + void foo(char *Character); + + foo('A'); + +After: + +.. code-block:: c++ + + void foo(char *Character); + + foo(/*Character=*/'A'); + +.. option:: CommentUserDefinedLiterals + + When true, the check will add argument comments in the format + ``/*ParameterName=*/`` right before the user defined literal argument. + +Before: + +.. code-block:: c++ + + void foo(double Distance); + + double operator"" _km(long double); + + foo(402.0_km); + +After: + +.. code-block:: c++ + + void foo(double Distance); + + double operator"" _km(long double); + + foo(/*Distance=*/402.0_km); + +.. option:: CommentNullPtrs + + When true, the check will add argument comments in the format + ``/*ParameterName=*/`` right before the nullptr literal argument. + +Before: + +.. code-block:: c++ + + void foo(A* Value); + + foo(nullptr); + +After: + +.. code-block:: c++ + + void foo(A* Value); + + foo(/*Value=*/nullptr); diff --git a/docs/clang-tidy/checks/bugprone-parent-virtual-call.rst b/docs/clang-tidy/checks/bugprone-parent-virtual-call.rst index e1021b18..c3521272 100755..100644 --- a/docs/clang-tidy/checks/bugprone-parent-virtual-call.rst +++ b/docs/clang-tidy/checks/bugprone-parent-virtual-call.rst @@ -8,15 +8,15 @@ to overridden parent's virtual methods. .. code-block:: c++ - class A { + struct A { int virtual foo() {...} }; - class B: public A { + struct B: public A { int foo() override {...} }; - class C: public B { + struct C: public B { int foo() override { A::foo(); } // ^^^^^^^^ // warning: qualified name A::foo refers to a member overridden in subclass; did you mean 'B'? [bugprone-parent-virtual-call] diff --git a/docs/clang-tidy/checks/bugprone-too-small-loop-variable.rst b/docs/clang-tidy/checks/bugprone-too-small-loop-variable.rst index 7688a3a5..702541d8 100644 --- a/docs/clang-tidy/checks/bugprone-too-small-loop-variable.rst +++ b/docs/clang-tidy/checks/bugprone-too-small-loop-variable.rst @@ -27,3 +27,20 @@ In a real use case size means a container's size which depends on the user input This algorithm works for small amount of objects, but will lead to freeze for a a larger user input. + +.. option:: MagnitudeBitsUpperLimit + + Upper limit for the magnitude bits of the loop variable. If it's set the check + filters out those catches in which the loop variable's type has more magnitude + bits as the specified upper limit. The default value is 16. + For example, if the user sets this option to 31 (bits), then a 32-bit ``unsigend int`` + is ignored by the check, however a 32-bit ``int`` is not (A 32-bit ``signed int`` + has 31 magnitude bits). + +.. code-block:: c++ + + int main() { + long size = 294967296l; + for (unsigned i = 0; i < size; ++i) {} // no warning with MagnitudeBitsUpperLimit = 31 on a system where unsigned is 32-bit + for (int i = 0; i < size; ++i) {} // warning with MagnitudeBitsUpperLimit = 31 on a system where int is 32-bit + } diff --git a/docs/clang-tidy/checks/cppcoreguidelines-explicit-virtual-functions.rst b/docs/clang-tidy/checks/cppcoreguidelines-explicit-virtual-functions.rst new file mode 100644 index 00000000..87a8fe2d --- /dev/null +++ b/docs/clang-tidy/checks/cppcoreguidelines-explicit-virtual-functions.rst @@ -0,0 +1,10 @@ +.. title:: clang-tidy - cppcoreguidelines-explicit-virtual-functions +.. meta:: + :http-equiv=refresh: 5;URL=modernize-use-override.html + +cppcoreguidelines-explicit-virtual-functions +============================================ + +The cppcoreguidelines-explicit-virtual-functions check is an alias, please see +`modernize-use-override <modernize-use-override.html>`_ +for more information. diff --git a/docs/clang-tidy/checks/cppcoreguidelines-owning-memory.rst b/docs/clang-tidy/checks/cppcoreguidelines-owning-memory.rst index 3f6f8c4b..cd190163 100644 --- a/docs/clang-tidy/checks/cppcoreguidelines-owning-memory.rst +++ b/docs/clang-tidy/checks/cppcoreguidelines-owning-memory.rst @@ -50,7 +50,7 @@ to be deleted. int* NonOwner = new int(42); // First warning here, since new must land in an owner delete NonOwner; // Second warning here, since only owners are allowed to be deleted - // Example Good, Ownership correclty stated + // Example Good, Ownership correctly stated gsl::owner<int*> Owner = new int(42); // Good delete Owner; // Good as well, statically enforced, that only owners get deleted diff --git a/docs/clang-tidy/checks/google-objc-avoid-throwing-exception.rst b/docs/clang-tidy/checks/google-objc-avoid-throwing-exception.rst index 39b02174..884e9719 100644 --- a/docs/clang-tidy/checks/google-objc-avoid-throwing-exception.rst +++ b/docs/clang-tidy/checks/google-objc-avoid-throwing-exception.rst @@ -36,4 +36,4 @@ Instead, returning an error via ``NSError **`` is preferred: } The corresponding style guide rule: -http://google.github.io/styleguide/objcguide.html#avoid-throwing-exceptions +https://google.github.io/styleguide/objcguide.html#avoid-throwing-exceptions diff --git a/docs/clang-tidy/checks/google-objc-global-variable-declaration.rst b/docs/clang-tidy/checks/google-objc-global-variable-declaration.rst index d4703706..e4b41fbc 100644 --- a/docs/clang-tidy/checks/google-objc-global-variable-declaration.rst +++ b/docs/clang-tidy/checks/google-objc-global-variable-declaration.rst @@ -7,7 +7,7 @@ Finds global variable declarations in Objective-C files that do not follow the pattern of variable names in Google's Objective-C Style Guide. The corresponding style guide rule: -http://google.github.io/styleguide/objcguide.html#variable-names +https://google.github.io/styleguide/objcguide.html#variable-names All the global variables should follow the pattern of `g[A-Z].*` (variables) or `k[A-Z].*` (constants). The check will suggest a variable name that follows the diff --git a/docs/clang-tidy/checks/google-readability-avoid-underscore-in-googletest-name.rst b/docs/clang-tidy/checks/google-readability-avoid-underscore-in-googletest-name.rst new file mode 100644 index 00000000..75b1a9ab --- /dev/null +++ b/docs/clang-tidy/checks/google-readability-avoid-underscore-in-googletest-name.rst @@ -0,0 +1,34 @@ +.. title:: clang-tidy - google-readability-avoid-underscore-in-googletest-name + +google-readability-avoid-underscore-in-googletest-name +====================================================== + +Checks whether there are underscores in googletest test and test case names in +test macros: + +- ``TEST`` +- ``TEST_F`` +- ``TEST_P`` +- ``TYPED_TEST`` +- ``TYPED_TEST_P`` + +The ``FRIEND_TEST`` macro is not included. + +For example: + +.. code-block:: c++ + + TEST(TestCaseName, Illegal_TestName) {} + TEST(Illegal_TestCaseName, TestName) {} + +would trigger the check. `Underscores are not allowed`_ in test names nor test +case names. + +The ``DISABLED_`` prefix, which may be used to `disable individual tests`_, is +ignored when checking test names, but the rest of the rest of the test name is +still checked. + +This check does not propose any fixes. + +.. _Underscores are not allowed: https://github.com/google/googletest/blob/master/googletest/docs/faq.md#why-should-test-suite-names-and-test-names-not-contain-underscore +.. _disable individual tests: https://github.com/google/googletest/blob/master/googletest/docs/faq.md#why-should-test-suite-names-and-test-names-not-contain-underscore diff --git a/docs/clang-tidy/checks/list.rst b/docs/clang-tidy/checks/list.rst index 080e747b..fc28cf61 100644 --- a/docs/clang-tidy/checks/list.rst +++ b/docs/clang-tidy/checks/list.rst @@ -4,17 +4,22 @@ Clang-Tidy Checks ================= .. toctree:: + abseil-duration-addition abseil-duration-comparison + abseil-duration-conversion-cast abseil-duration-division abseil-duration-factory-float abseil-duration-factory-scale abseil-duration-subtraction + abseil-duration-unnecessary-conversion abseil-faster-strsplit-delimiter abseil-no-internal-dependencies abseil-no-namespace abseil-redundant-strcat-calls abseil-str-cat-append abseil-string-find-startswith + abseil-time-comparison + abseil-time-subtraction abseil-upgrade-duration-conversions android-cloexec-accept android-cloexec-accept4 @@ -95,6 +100,7 @@ Clang-Tidy Checks cppcoreguidelines-avoid-goto cppcoreguidelines-avoid-magic-numbers (redirects to readability-magic-numbers) <cppcoreguidelines-avoid-magic-numbers> cppcoreguidelines-c-copy-assignment-signature (redirects to misc-unconventional-assign-operator) <cppcoreguidelines-c-copy-assignment-signature> + cppcoreguidelines-explicit-virtual-functions (redirects to modernize-use-override) <cppcoreguidelines-explicit-virtual-functions> cppcoreguidelines-interfaces-global-init cppcoreguidelines-macro-usage cppcoreguidelines-narrowing-conversions @@ -130,6 +136,7 @@ Clang-Tidy Checks google-objc-avoid-throwing-exception google-objc-function-naming google-objc-global-variable-declaration + google-readability-avoid-underscore-in-googletest-name google-readability-braces-around-statements (redirects to readability-braces-around-statements) <google-readability-braces-around-statements> google-readability-casting google-readability-function-size (redirects to readability-function-size) <google-readability-function-size> @@ -171,6 +178,7 @@ Clang-Tidy Checks llvm-header-guard llvm-include-order llvm-namespace-comment + llvm-prefer-isa-or-dyn-cast-in-conditionals llvm-twine-local misc-definitions-in-headers misc-misplaced-const @@ -220,6 +228,9 @@ Clang-Tidy Checks objc-avoid-spinlock objc-forbidden-subclassing objc-property-declaration + objc-super-self + openmp-exception-escape + openmp-use-default-none performance-faster-string-find performance-for-range-copy performance-implicit-conversion-in-loop diff --git a/docs/clang-tidy/checks/llvm-include-order.rst b/docs/clang-tidy/checks/llvm-include-order.rst index dba98376..8a215b8e 100644 --- a/docs/clang-tidy/checks/llvm-include-order.rst +++ b/docs/clang-tidy/checks/llvm-include-order.rst @@ -6,4 +6,4 @@ llvm-include-order Checks the correct order of ``#includes``. -See http://llvm.org/docs/CodingStandards.html#include-style +See https://llvm.org/docs/CodingStandards.html#include-style diff --git a/docs/clang-tidy/checks/llvm-namespace-comment.rst b/docs/clang-tidy/checks/llvm-namespace-comment.rst index f6bc5985..be90260b 100644 --- a/docs/clang-tidy/checks/llvm-namespace-comment.rst +++ b/docs/clang-tidy/checks/llvm-namespace-comment.rst @@ -8,7 +8,7 @@ check. Checks that long namespaces have a closing comment. -http://llvm.org/docs/CodingStandards.html#namespace-indentation +https://llvm.org/docs/CodingStandards.html#namespace-indentation https://google.github.io/styleguide/cppguide.html#Namespaces diff --git a/docs/clang-tidy/checks/llvm-prefer-isa-or-dyn-cast-in-conditionals.rst b/docs/clang-tidy/checks/llvm-prefer-isa-or-dyn-cast-in-conditionals.rst new file mode 100644 index 00000000..70ff0f27 --- /dev/null +++ b/docs/clang-tidy/checks/llvm-prefer-isa-or-dyn-cast-in-conditionals.rst @@ -0,0 +1,34 @@ +.. title:: clang-tidy - llvm-prefer-isa-or-dyn-cast-in-conditionals + +llvm-prefer-isa-or-dyn-cast-in-conditionals +=========================================== + +Looks at conditionals and finds and replaces cases of ``cast<>``, +which will assert rather than return a null pointer, and +``dyn_cast<>`` where the return value is not captured. Additionally, +finds and replaces cases that match the pattern ``var && +isa<X>(var)``, where ``var`` is evaluated twice. + +.. code-block:: c++ + + // Finds these: + if (auto x = cast<X>(y)) {} + // is replaced by: + if (auto x = dyn_cast<X>(y)) {} + + if (cast<X>(y)) {} + // is replaced by: + if (isa<X>(y)) {} + + if (dyn_cast<X>(y)) {} + // is replaced by: + if (isa<X>(y)) {} + + if (var && isa<T>(var)) {} + // is replaced by: + if (isa_and_nonnull<T>(var.foo())) {} + + // Other cases are ignored, e.g.: + if (auto f = cast<Z>(y)->foo()) {} + if (cast<Z>(y)->foo()) {} + if (X.cast(y)) {} diff --git a/docs/clang-tidy/checks/misc-non-private-member-variables-in-classes.rst b/docs/clang-tidy/checks/misc-non-private-member-variables-in-classes.rst index db88c9b1..57990622 100644 --- a/docs/clang-tidy/checks/misc-non-private-member-variables-in-classes.rst +++ b/docs/clang-tidy/checks/misc-non-private-member-variables-in-classes.rst @@ -6,11 +6,11 @@ misc-non-private-member-variables-in-classes `cppcoreguidelines-non-private-member-variables-in-classes` redirects here as an alias for this check. -Finds classes that contain non-static data members in addition to non-static -member functions and diagnose all data members declared with a non-``public`` -access specifier. The data members should be declared as ``private`` and -accessed through member functions instead of exposed to derived classes or -class consumers. +Finds classes that contain non-static data members in addition to user-declared +non-static member functions and diagnose all data members declared with a +non-``public`` access specifier. The data members should be declared as +``private`` and accessed through member functions instead of exposed to derived +classes or class consumers. Options ------- diff --git a/docs/clang-tidy/checks/misc-throw-by-value-catch-by-reference.rst b/docs/clang-tidy/checks/misc-throw-by-value-catch-by-reference.rst index 1a6d6b3f..91287d86 100644 --- a/docs/clang-tidy/checks/misc-throw-by-value-catch-by-reference.rst +++ b/docs/clang-tidy/checks/misc-throw-by-value-catch-by-reference.rst @@ -3,8 +3,8 @@ misc-throw-by-value-catch-by-reference ====================================== -"cert-err09-cpp" redirects here as an alias for this check. -"cert-err61-cpp" redirects here as an alias for this check. +`cert-err09-cpp` redirects here as an alias for this check. +`cert-err61-cpp` redirects here as an alias for this check. Finds violations of the rule "Throw by value, catch by reference" presented for example in "C++ Coding Standards" by H. Sutter and A. Alexandrescu. diff --git a/docs/clang-tidy/checks/modernize-avoid-c-arrays.rst b/docs/clang-tidy/checks/modernize-avoid-c-arrays.rst index 8f856a52..d7bc7474 100644 --- a/docs/clang-tidy/checks/modernize-avoid-c-arrays.rst +++ b/docs/clang-tidy/checks/modernize-avoid-c-arrays.rst @@ -54,3 +54,7 @@ such headers between C code, and C++ code. } } + +Similarly, the ``main()`` function is ignored. Its second and third parameters +can be either ``char* argv[]`` or ``char** argv``, but can not be +``std::array<>``. diff --git a/docs/clang-tidy/checks/modernize-pass-by-value.rst b/docs/clang-tidy/checks/modernize-pass-by-value.rst index f49648d4..e538135a 100644 --- a/docs/clang-tidy/checks/modernize-pass-by-value.rst +++ b/docs/clang-tidy/checks/modernize-pass-by-value.rst @@ -144,7 +144,7 @@ Example: + C(std::string S) : S(std::move(S)) {} }; -.. _Clang Compiler User’s Manual - Microsoft extensions: http://clang.llvm.org/docs/UsersManual.html#microsoft-extensions +.. _Clang Compiler User’s Manual - Microsoft extensions: https://clang.llvm.org/docs/UsersManual.html#microsoft-extensions .. seealso:: diff --git a/docs/clang-tidy/checks/modernize-use-emplace.rst b/docs/clang-tidy/checks/modernize-use-emplace.rst index 533125e9..447a110f 100644 --- a/docs/clang-tidy/checks/modernize-use-emplace.rst +++ b/docs/clang-tidy/checks/modernize-use-emplace.rst @@ -10,7 +10,7 @@ results in less verbose and potentially more efficient code. Right now the check doesn't support ``push_front`` and ``insert``. It also doesn't support ``insert`` functions for associative containers because replacing ``insert`` with ``emplace`` may result in -`speed regression <http://htmlpreview.github.io/?https://github.com/HowardHinnant/papers/blob/master/insert_vs_emplace.html>`_, but it might get support with some addition flag in the future. +`speed regression <https://htmlpreview.github.io/?https://github.com/HowardHinnant/papers/blob/master/insert_vs_emplace.html>`_, but it might get support with some addition flag in the future. By default only ``std::vector``, ``std::deque``, ``std::list`` are considered. This list can be modified using the :option:`ContainersWithPushBack` option. diff --git a/docs/clang-tidy/checks/modernize-use-override.rst b/docs/clang-tidy/checks/modernize-use-override.rst index f2c778aa..4273c6e5 100644 --- a/docs/clang-tidy/checks/modernize-use-override.rst +++ b/docs/clang-tidy/checks/modernize-use-override.rst @@ -3,5 +3,42 @@ modernize-use-override ====================== +Adds ``override`` (introduced in C++11) to overridden virtual functions and +removes ``virtual`` from those functions as it is not required. -Use C++11's ``override`` and remove ``virtual`` where applicable. +``virtual`` on non base class implementations was used to help indiciate to the +user that a function was virtual. C++ compilers did not use the presence of +this to signify an overriden function. + +In C++ 11 ``override`` and ``final`` keywords were introduced to allow +overridden functions to be marked appropriately. Their presence allows +compilers to verify that an overridden function correctly overrides a base +class implementation. + +This can be useful as compilers can generate a compile time error when: + + - The base class implementation function signature changes. + - The user has not created the override with the correct signature. + +Options +------- + +.. option:: IgnoreDestructors + + If set to non-zero, this check will not diagnose destructors. Default is `0`. + +.. option:: OverrideSpelling + + Specifies a macro to use instead of ``override``. This is useful when + maintaining source code that also needs to compile with a pre-C++11 + compiler. + +.. option:: FinalSpelling + + Specifies a macro to use instead of ``final``. This is useful when + maintaining source code that also needs to compile with a pre-C++11 + compiler. + +.. note:: + + For more information on the use of ``override`` see https://en.cppreference.com/w/cpp/language/override diff --git a/docs/clang-tidy/checks/objc-property-declaration.rst b/docs/clang-tidy/checks/objc-property-declaration.rst index 49df5102..60b9c82e 100644 --- a/docs/clang-tidy/checks/objc-property-declaration.rst +++ b/docs/clang-tidy/checks/objc-property-declaration.rst @@ -40,15 +40,3 @@ lowercase letters followed by a '_' to avoid naming conflict. For example: @property(nonatomic, assign) int abc_lowerCamelCase; The corresponding style rule: https://developer.apple.com/library/content/qa/qa1908/_index.html - - -Options -------- - -.. option:: Acronyms - - This option is deprecated and ignored. - -.. option:: IncludeDefaultAcronyms - - This option is deprecated and ignored. diff --git a/docs/clang-tidy/checks/objc-super-self.rst b/docs/clang-tidy/checks/objc-super-self.rst new file mode 100644 index 00000000..ed0bb295 --- /dev/null +++ b/docs/clang-tidy/checks/objc-super-self.rst @@ -0,0 +1,13 @@ +.. title:: clang-tidy - objc-super-self + +objc-super-self +=============== + +Finds invocations of ``-self`` on super instances in initializers of subclasses +of ``NSObject`` and recommends calling a superclass initializer instead. + +Invoking ``-self`` on super instances in initializers is a common programmer +error when the programmer's original intent is to call a superclass +initializer. Failing to call a superclass initializer breaks initializer +chaining and can result in invalid object initialization. + diff --git a/docs/clang-tidy/checks/openmp-exception-escape.rst b/docs/clang-tidy/checks/openmp-exception-escape.rst new file mode 100644 index 00000000..d85e4fd5 --- /dev/null +++ b/docs/clang-tidy/checks/openmp-exception-escape.rst @@ -0,0 +1,25 @@ +.. title:: clang-tidy - openmp-exception-escape + +openmp-exception-escape +======================= + +Analyzes OpenMP Structured Blocks and checks that no exception escapes +out of the Structured Block it was thrown in. + +As per the OpenMP specification, a structured block is an executable statement, +possibly compound, with a single entry at the top and a single exit at the +bottom. Which means, ``throw`` may not be used to to 'exit' out of the +structured block. If an exception is not caught in the same structured block +it was thrown in, the behaviour is undefined. + +FIXME: this check does not model SEH, ``setjmp``/``longjmp``. + +WARNING! This check may be expensive on large source files. + +Options +------- + +.. option:: IgnoredExceptions + + Comma-separated list containing type names which are not counted as thrown + exceptions in the check. Default value is an empty string. diff --git a/docs/clang-tidy/checks/openmp-use-default-none.rst b/docs/clang-tidy/checks/openmp-use-default-none.rst new file mode 100644 index 00000000..4223a10b --- /dev/null +++ b/docs/clang-tidy/checks/openmp-use-default-none.rst @@ -0,0 +1,53 @@ +.. title:: clang-tidy - openmp-use-default-none + +openmp-use-default-none +======================= + +Finds OpenMP directives that are allowed to contain a ``default`` clause, +but either don't specify it or the clause is specified but with the kind +other than ``none``, and suggests to use the ``default(none)`` clause. + +Using ``default(none)`` clause forces developers to explicitly specify data +sharing attributes for the variables referenced in the construct, +thus making it obvious which variables are referenced, and what is their +data sharing attribute, thus increasing readability and possibly making errors +easier to spot. + +Example +------- + +.. code-block:: c++ + + // ``for`` directive can not have ``default`` clause, no diagnostics. + void n0(const int a) { + #pragma omp for + for (int b = 0; b < a; b++) + ; + } + + // ``parallel`` directive. + + // ``parallel`` directive can have ``default`` clause, but said clause is not + // specified, diagnosed. + void p0_0() { + #pragma omp parallel + ; + // WARNING: OpenMP directive ``parallel`` does not specify ``default`` + // clause. Consider specifying ``default(none)`` clause. + } + + // ``parallel`` directive can have ``default`` clause, and said clause is + // specified, with ``none`` kind, all good. + void p0_1() { + #pragma omp parallel default(none) + ; + } + + // ``parallel`` directive can have ``default`` clause, and said clause is + // specified, but with ``shared`` kind, which is not ``none``, diagnose. + void p0_2() { + #pragma omp parallel default(shared) + ; + // WARNING: OpenMP directive ``parallel`` specifies ``default(shared)`` + // clause. Consider using ``default(none)`` clause instead. + } diff --git a/docs/clang-tidy/checks/portability-simd-intrinsics.rst b/docs/clang-tidy/checks/portability-simd-intrinsics.rst index 2cd9d9f7..fedd47a1 100644 --- a/docs/clang-tidy/checks/portability-simd-intrinsics.rst +++ b/docs/clang-tidy/checks/portability-simd-intrinsics.rst @@ -46,4 +46,4 @@ Options The namespace used to suggest `P0214`_ alternatives. If not specified, `std::` for `-std=c++2a` and `std::experimental::` for `-std=c++11`. -.. _P0214: http://wg21.link/p0214 +.. _P0214: https://wg21.link/p0214 diff --git a/docs/clang-tidy/checks/readability-else-after-return.rst b/docs/clang-tidy/checks/readability-else-after-return.rst index 949b5bb4..c178a6a6 100644 --- a/docs/clang-tidy/checks/readability-else-after-return.rst +++ b/docs/clang-tidy/checks/readability-else-after-return.rst @@ -3,7 +3,7 @@ readability-else-after-return ============================= -`LLVM Coding Standards <http://llvm.org/docs/CodingStandards.html>`_ advises to +`LLVM Coding Standards <https://llvm.org/docs/CodingStandards.html>`_ advises to reduce indentation where possible and where it makes understanding code easier. Early exit is one of the suggested enforcements of that. Please do not use ``else`` or ``else if`` after something that interrupts control flow - like @@ -61,4 +61,4 @@ Would be transformed into: This check helps to enforce this `LLVM Coding Standards recommendation -<http://llvm.org/docs/CodingStandards.html#don-t-use-else-after-a-return>`_. +<https://llvm.org/docs/CodingStandards.html#don-t-use-else-after-a-return>`_. diff --git a/docs/clang-tidy/checks/readability-magic-numbers.rst b/docs/clang-tidy/checks/readability-magic-numbers.rst index 946672ed..9968809e 100644 --- a/docs/clang-tidy/checks/readability-magic-numbers.rst +++ b/docs/clang-tidy/checks/readability-magic-numbers.rst @@ -9,7 +9,7 @@ code and not introduced via constants or symbols. Many coding guidelines advise replacing the magic values with symbolic constants to improve readability. Here are a few references: - * `Rule ES.45: Avoid “magic constants”; use symbolic constants in C++ Core Guidelines <http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-magic>`_ + * `Rule ES.45: Avoid “magic constants”; use symbolic constants in C++ Core Guidelines <https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-magic>`_ * `Rule 5.1.1 Use symbolic names instead of literal values in code in High Integrity C++ <http://www.codingstandard.com/rule/5-1-1-use-symbolic-names-instead-of-literal-values-in-code/>`_ * Item 17 in "C++ Coding Standards: 101 Rules, Guidelines and Best Practices" by Herb Sutter and Andrei Alexandrescu diff --git a/docs/clang-tidy/index.rst b/docs/clang-tidy/index.rst index 20b18b4b..1b5af60d 100644 --- a/docs/clang-tidy/index.rst +++ b/docs/clang-tidy/index.rst @@ -10,6 +10,8 @@ See also: :maxdepth: 1 The list of clang-tidy checks <checks/list> + Clang-tidy IDE/Editor Integrations <Integrations> + Getting Involved <Contributing> :program:`clang-tidy` is a clang-based C++ "linter" tool. Its purpose is to provide an extensible framework for diagnosing and fixing typical programming @@ -71,6 +73,7 @@ Name prefix Description means "C++11") language constructs. ``mpi-`` Checks related to MPI (Message Passing Interface). ``objc-`` Checks related to Objective-C coding conventions. +``openmp-`` Checks related to OpenMP API. ``performance-`` Checks that target performance-related issues. ``portability-`` Checks that target portability-related issues that don't relate to any particular coding style. @@ -223,7 +226,7 @@ An overview of all the command-line options: CMake option to get this output). When no build path is specified, a search for compile_commands.json will be attempted through all parent paths of the first input file . See: - http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html for an + https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html for an example of setting up Clang Tooling on a source tree. <source0> ... specify the paths of source files. These paths are @@ -258,30 +261,51 @@ An overview of all the command-line options: Suppressing Undesired Diagnostics ================================= -:program:`clang-tidy` diagnostics are intended to call out code that does -not adhere to a coding standard, or is otherwise problematic in some way. -However, if it is known that the code is correct, the check-specific ways -to silence the diagnostics could be used, if they are available (e.g. -bugprone-use-after-move can be silenced by re-initializing the variable after it -has been moved out, bugprone-string-integer-assignment can be suppressed by -explicitly casting the integer to char, readability-implicit-bool-conversion can -also be suppressed by using explicit casts, etc.). If they are not available or -if changing the semantics of the code is not desired, the ``NOLINT`` or -``NOLINTNEXTLINE`` comments can be used instead. For example: +:program:`clang-tidy` diagnostics are intended to call out code that does not +adhere to a coding standard, or is otherwise problematic in some way. However, +if the code is known to be correct, it may be useful to silence the warning. +Some clang-tidy checks provide a check-specific way to silence the diagnostics, +e.g. `bugprone-use-after-move <checks/bugprone-use-after-move.html>`_ can be +silenced by re-initializing the variable after it has been moved out, +`bugprone-string-integer-assignment +<checks/bugprone-string-integer-assignment.html>`_ can be suppressed by +explicitly casting the integer to ``char``, +`readability-implicit-bool-conversion +<checks/readability-implicit-bool-conversion.html>`_ can also be suppressed by +using explicit casts, etc. + +If a specific suppression mechanism is not available for a certain warning, or +its use is not desired for some reason, :program:`clang-tidy` has a generic +mechanism to suppress diagnostics using ``NOLINT`` or ``NOLINTNEXTLINE`` +comments. + +The ``NOLINT`` comment instructs :program:`clang-tidy` to ignore warnings on the +*same line* (it doesn't apply to a function, a block of code or any other +language construct, it applies to the line of code it is on). If introducing the +comment in the same line would change the formatting in undesired way, the +``NOLINTNEXTLINE`` comment allows to suppress clang-tidy warnings on the *next +line*. + +Both comments can be followed by an optional list of check names in parentheses +(see below for the formal syntax). + +For example: .. code-block:: c++ - class Foo - { - // Silent all the diagnostics for the line + class Foo { + // Suppress all the diagnostics for the line Foo(int param); // NOLINT - // Silent only the specified checks for the line + // Consider explaining the motivation to suppress the warning. + Foo(char param); // NOLINT: Allow implicit conversion from `char`, because <some valid reason>. + + // Silence only the specified checks for the line Foo(double param); // NOLINT(google-explicit-constructor, google-runtime-int) - // Silent only the specified diagnostics for the next line + // Silence only the specified diagnostics for the next line // NOLINTNEXTLINE(google-explicit-constructor, google-runtime-int) - Foo(bool param); + Foo(bool param); }; The formal syntax of ``NOLINT``/``NOLINTNEXTLINE`` is the following: @@ -305,516 +329,8 @@ The formal syntax of ``NOLINT``/``NOLINTNEXTLINE`` is the following: Note that whitespaces between ``NOLINT``/``NOLINTNEXTLINE`` and the opening parenthesis are not allowed (in this case the comment will be treated just as -``NOLINT``/``NOLINTNEXTLINE``), whereas in check names list (inside -the parenthesis) whitespaces can be used and will be ignored. - -.. _LibTooling: http://clang.llvm.org/docs/LibTooling.html -.. _How To Setup Tooling For LLVM: http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html - - -Getting Involved -================ - -:program:`clang-tidy` has several own checks and can run Clang static analyzer -checks, but its power is in the ability to easily write custom checks. - -Checks are organized in modules, which can be linked into :program:`clang-tidy` -with minimal or no code changes in :program:`clang-tidy`. - -Checks can plug into the analysis on the preprocessor level using `PPCallbacks`_ -or on the AST level using `AST Matchers`_. When an error is found, checks can -report them in a way similar to how Clang diagnostics work. A fix-it hint can be -attached to a diagnostic message. - -The interface provided by :program:`clang-tidy` makes it easy to write useful -and precise checks in just a few lines of code. If you have an idea for a good -check, the rest of this document explains how to do this. - -There are a few tools particularly useful when developing clang-tidy checks: - * ``add_new_check.py`` is a script to automate the process of adding a new - check, it will create the check, update the CMake file and create a test; - * ``rename_check.py`` does what the script name suggests, renames an existing - check; - * :program:`clang-query` is invaluable for interactive prototyping of AST - matchers and exploration of the Clang AST; - * `clang-check`_ with the ``-ast-dump`` (and optionally ``-ast-dump-filter``) - provides a convenient way to dump AST of a C++ program. - -If CMake is configured with ``CLANG_ENABLE_STATIC_ANALYZER``, -:program:`clang-tidy` will not be built with support for the -``clang-analyzer-*`` checks or the ``mpi-*`` checks. - - -.. _AST Matchers: http://clang.llvm.org/docs/LibASTMatchers.html -.. _PPCallbacks: http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html -.. _clang-check: http://clang.llvm.org/docs/ClangCheck.html - - -Choosing the Right Place for your Check ---------------------------------------- - -If you have an idea of a check, you should decide whether it should be -implemented as a: - -+ *Clang diagnostic*: if the check is generic enough, targets code patterns that - most probably are bugs (rather than style or readability issues), can be - implemented effectively and with extremely low false positive rate, it may - make a good Clang diagnostic. - -+ *Clang static analyzer check*: if the check requires some sort of control flow - analysis, it should probably be implemented as a static analyzer check. - -+ *clang-tidy check* is a good choice for linter-style checks, checks that are - related to a certain coding style, checks that address code readability, etc. - - -Preparing your Workspace ------------------------- - -If you are new to LLVM development, you should read the `Getting Started with -the LLVM System`_, `Using Clang Tools`_ and `How To Setup Tooling For LLVM`_ -documents to check out and build LLVM, Clang and Clang Extra Tools with CMake. - -Once you are done, change to the ``llvm/tools/clang/tools/extra`` directory, and -let's start! - -.. _Getting Started with the LLVM System: http://llvm.org/docs/GettingStarted.html -.. _Using Clang Tools: http://clang.llvm.org/docs/ClangTools.html - - -The Directory Structure ------------------------ - -:program:`clang-tidy` source code resides in the -``llvm/tools/clang/tools/extra`` directory and is structured as follows: - -:: - - clang-tidy/ # Clang-tidy core. - |-- ClangTidy.h # Interfaces for users and checks. - |-- ClangTidyModule.h # Interface for clang-tidy modules. - |-- ClangTidyModuleRegistry.h # Interface for registering of modules. - ... - |-- google/ # Google clang-tidy module. - |-+ - |-- GoogleTidyModule.cpp - |-- GoogleTidyModule.h - ... - |-- llvm/ # LLVM clang-tidy module. - |-+ - |-- LLVMTidyModule.cpp - |-- LLVMTidyModule.h - ... - |-- objc/ # Objective-C clang-tidy module. - |-+ - |-- ObjCTidyModule.cpp - |-- ObjCTidyModule.h - ... - |-- tool/ # Sources of the clang-tidy binary. - ... - test/clang-tidy/ # Integration tests. - ... - unittests/clang-tidy/ # Unit tests. - |-- ClangTidyTest.h - |-- GoogleModuleTest.cpp - |-- LLVMModuleTest.cpp - |-- ObjCModuleTest.cpp - ... - - -Writing a clang-tidy Check --------------------------- - -So you have an idea of a useful check for :program:`clang-tidy`. - -First, if you're not familiar with LLVM development, read through the `Getting -Started with LLVM`_ document for instructions on setting up your workflow and -the `LLVM Coding Standards`_ document to familiarize yourself with the coding -style used in the project. For code reviews we mostly use `LLVM Phabricator`_. - -.. _Getting Started with LLVM: http://llvm.org/docs/GettingStarted.html -.. _LLVM Coding Standards: http://llvm.org/docs/CodingStandards.html -.. _LLVM Phabricator: http://llvm.org/docs/Phabricator.html - -Next, you need to decide which module the check belongs to. Modules -are located in subdirectories of `clang-tidy/ -<http://reviews.llvm.org/diffusion/L/browse/clang-tools-extra/trunk/clang-tidy/>`_ -and contain checks targeting a certain aspect of code quality (performance, -readability, etc.), certain coding style or standard (Google, LLVM, CERT, etc.) -or a widely used API (e.g. MPI). Their names are same as user-facing check -groups names described :ref:`above <checks-groups-table>`. - -After choosing the module and the name for the check, run the -``clang-tidy/add_new_check.py`` script to create the skeleton of the check and -plug it to :program:`clang-tidy`. It's the recommended way of adding new checks. - -If we want to create a `readability-awesome-function-names`, we would run: - -.. code-block:: console - - $ clang-tidy/add_new_check.py readability awesome-function-names - - -The ``add_new_check.py`` script will: - * create the class for your check inside the specified module's directory and - register it in the module and in the build system; - * create a lit test file in the ``test/clang-tidy/`` directory; - * create a documentation file and include it into the - ``docs/clang-tidy/checks/list.rst``. - -Let's see in more detail at the check class definition: - -.. code-block:: c++ - - ... - - #include "../ClangTidy.h" - - namespace clang { - namespace tidy { - namespace readability { - - ... - class AwesomeFunctionNamesCheck : public ClangTidyCheck { - public: - AwesomeFunctionNamesCheck(StringRef Name, ClangTidyContext *Context) - : ClangTidyCheck(Name, Context) {} - void registerMatchers(ast_matchers::MatchFinder *Finder) override; - void check(const ast_matchers::MatchFinder::MatchResult &Result) override; - }; - - } // namespace readability - } // namespace tidy - } // namespace clang - - ... - -Constructor of the check receives the ``Name`` and ``Context`` parameters, and -must forward them to the ``ClangTidyCheck`` constructor. - -In our case the check needs to operate on the AST level and it overrides the -``registerMatchers`` and ``check`` methods. If we wanted to analyze code on the -preprocessor level, we'd need instead to override the ``registerPPCallbacks`` -method. - -In the ``registerMatchers`` method we create an AST Matcher (see `AST Matchers`_ -for more information) that will find the pattern in the AST that we want to -inspect. The results of the matching are passed to the ``check`` method, which -can further inspect them and report diagnostics. - -.. code-block:: c++ - - using namespace ast_matchers; - - void AwesomeFunctionNamesCheck::registerMatchers(MatchFinder *Finder) { - Finder->addMatcher(functionDecl().bind("x"), this); - } - - void AwesomeFunctionNamesCheck::check(const MatchFinder::MatchResult &Result) { - const auto *MatchedDecl = Result.Nodes.getNodeAs<FunctionDecl>("x"); - if (MatchedDecl->getName().startswith("awesome_")) - return; - diag(MatchedDecl->getLocation(), "function %0 is insufficiently awesome") - << MatchedDecl - << FixItHint::CreateInsertion(MatchedDecl->getLocation(), "awesome_"); - } - -(If you want to see an example of a useful check, look at -`clang-tidy/google/ExplicitConstructorCheck.h -<http://reviews.llvm.org/diffusion/L/browse/clang-tools-extra/trunk/clang-tidy/google/ExplicitConstructorCheck.h>`_ -and `clang-tidy/google/ExplicitConstructorCheck.cpp -<http://reviews.llvm.org/diffusion/L/browse/clang-tools-extra/trunk/clang-tidy/google/ExplicitConstructorCheck.cpp>`_). - - -Registering your Check ----------------------- - -(The ``add_new_check.py`` takes care of registering the check in an existing -module. If you want to create a new module or know the details, read on.) - -The check should be registered in the corresponding module with a distinct name: - -.. code-block:: c++ - - class MyModule : public ClangTidyModule { - public: - void addCheckFactories(ClangTidyCheckFactories &CheckFactories) override { - CheckFactories.registerCheck<ExplicitConstructorCheck>( - "my-explicit-constructor"); - } - }; - -Now we need to register the module in the ``ClangTidyModuleRegistry`` using a -statically initialized variable: - -.. code-block:: c++ - - static ClangTidyModuleRegistry::Add<MyModule> X("my-module", - "Adds my lint checks."); - - -When using LLVM build system, we need to use the following hack to ensure the -module is linked into the :program:`clang-tidy` binary: - -Add this near the ``ClangTidyModuleRegistry::Add<MyModule>`` variable: - -.. code-block:: c++ - - // This anchor is used to force the linker to link in the generated object file - // and thus register the MyModule. - volatile int MyModuleAnchorSource = 0; - -And this to the main translation unit of the :program:`clang-tidy` binary (or -the binary you link the ``clang-tidy`` library in) -``clang-tidy/tool/ClangTidyMain.cpp``: - -.. code-block:: c++ - - // This anchor is used to force the linker to link the MyModule. - extern volatile int MyModuleAnchorSource; - static int MyModuleAnchorDestination = MyModuleAnchorSource; - - -Configuring Checks ------------------- - -If a check needs configuration options, it can access check-specific options -using the ``Options.get<Type>("SomeOption", DefaultValue)`` call in the check -constructor. In this case the check should also override the -``ClangTidyCheck::storeOptions`` method to make the options provided by the -check discoverable. This method lets :program:`clang-tidy` know which options -the check implements and what the current values are (e.g. for the -``-dump-config`` command line option). - -.. code-block:: c++ - - class MyCheck : public ClangTidyCheck { - const unsigned SomeOption1; - const std::string SomeOption2; - - public: - MyCheck(StringRef Name, ClangTidyContext *Context) - : ClangTidyCheck(Name, Context), - SomeOption(Options.get("SomeOption1", -1U)), - SomeOption(Options.get("SomeOption2", "some default")) {} - - void storeOptions(ClangTidyOptions::OptionMap &Opts) override { - Options.store(Opts, "SomeOption1", SomeOption1); - Options.store(Opts, "SomeOption2", SomeOption2); - } - ... - -Assuming the check is registered with the name "my-check", the option can then -be set in a ``.clang-tidy`` file in the following way: - -.. code-block:: yaml - - CheckOptions: - - key: my-check.SomeOption1 - value: 123 - - key: my-check.SomeOption2 - value: 'some other value' - -If you need to specify check options on a command line, you can use the inline -YAML format: - -.. code-block:: console - - $ clang-tidy -config="{CheckOptions: [{key: a, value: b}, {key: x, value: y}]}" ... - - -Testing Checks --------------- - -To run tests for :program:`clang-tidy` use the command: - -.. code-block:: console - - $ ninja check-clang-tools - -:program:`clang-tidy` checks can be tested using either unit tests or -`lit`_ tests. Unit tests may be more convenient to test complex replacements -with strict checks. `Lit`_ tests allow using partial text matching and regular -expressions which makes them more suitable for writing compact tests for -diagnostic messages. - -The ``check_clang_tidy.py`` script provides an easy way to test both -diagnostic messages and fix-its. It filters out ``CHECK`` lines from the test -file, runs :program:`clang-tidy` and verifies messages and fixes with two -separate `FileCheck`_ invocations: once with FileCheck's directive -prefix set to ``CHECK-MESSAGES``, validating the diagnostic messages, -and once with the directive prefix set to ``CHECK-FIXES``, running -against the fixed code (i.e., the code after generated fix-its are -applied). In particular, ``CHECK-FIXES:`` can be used to check -that code was not modified by fix-its, by checking that it is present -unchanged in the fixed code. The full set of `FileCheck`_ directives -is available (e.g., ``CHECK-MESSAGES-SAME:``, ``CHECK-MESSAGES-NOT:``), though -typically the basic ``CHECK`` forms (``CHECK-MESSAGES`` and ``CHECK-FIXES``) -are sufficient for clang-tidy tests. Note that the `FileCheck`_ -documentation mostly assumes the default prefix (``CHECK``), and hence -describes the directive as ``CHECK:``, ``CHECK-SAME:``, ``CHECK-NOT:``, etc. -Replace ``CHECK`` by either ``CHECK-FIXES`` or ``CHECK-MESSAGES`` for -clang-tidy tests. - -An additional check enabled by ``check_clang_tidy.py`` ensures that -if `CHECK-MESSAGES:` is used in a file then every warning or error -must have an associated CHECK in that file. Or, you can use ``CHECK-NOTES:`` -instead, if you want to **also** ensure that all the notes are checked. - -To use the ``check_clang_tidy.py`` script, put a .cpp file with the -appropriate ``RUN`` line in the ``test/clang-tidy`` directory. Use -``CHECK-MESSAGES:`` and ``CHECK-FIXES:`` lines to write checks against -diagnostic messages and fixed code. - -It's advised to make the checks as specific as possible to avoid checks matching -to incorrect parts of the input. Use ``[[@LINE+X]]``/``[[@LINE-X]]`` -substitutions and distinct function and variable names in the test code. - -Here's an example of a test using the ``check_clang_tidy.py`` script (the full -source code is at `test/clang-tidy/google-readability-casting.cpp`_): - -.. code-block:: c++ - - // RUN: %check_clang_tidy %s google-readability-casting %t - - void f(int a) { - int b = (int)a; - // CHECK-MESSAGES: :[[@LINE-1]]:11: warning: redundant cast to the same type [google-readability-casting] - // CHECK-FIXES: int b = a; - } - -To check more than one scenario in the same test file use -``-check-suffix=SUFFIX-NAME`` on ``check_clang_tidy.py`` command line or -``-check-suffixes=SUFFIX-NAME-1,SUFFIX-NAME-2,...``. -With ``-check-suffix[es]=SUFFIX-NAME`` you need to replace your ``CHECK-*`` -directives with ``CHECK-MESSAGES-SUFFIX-NAME`` and ``CHECK-FIXES-SUFFIX-NAME``. - -Here's an example: - -.. code-block:: c++ - - // RUN: %check_clang_tidy -check-suffix=USING-A %s misc-unused-using-decls %t -- -- -DUSING_A - // RUN: %check_clang_tidy -check-suffix=USING-B %s misc-unused-using-decls %t -- -- -DUSING_B - // RUN: %check_clang_tidy %s misc-unused-using-decls %t - ... - // CHECK-MESSAGES-USING-A: :[[@LINE-8]]:10: warning: using decl 'A' {{.*}} - // CHECK-MESSAGES-USING-B: :[[@LINE-7]]:10: warning: using decl 'B' {{.*}} - // CHECK-MESSAGES: :[[@LINE-6]]:10: warning: using decl 'C' {{.*}} - // CHECK-FIXES-USING-A-NOT: using a::A;$ - // CHECK-FIXES-USING-B-NOT: using a::B;$ - // CHECK-FIXES-NOT: using a::C;$ - - -There are many dark corners in the C++ language, and it may be difficult to make -your check work perfectly in all cases, especially if it issues fix-it hints. The -most frequent pitfalls are macros and templates: - -1. code written in a macro body/template definition may have a different meaning - depending on the macro expansion/template instantiation; -2. multiple macro expansions/template instantiations may result in the same code - being inspected by the check multiple times (possibly, with different - meanings, see 1), and the same warning (or a slightly different one) may be - issued by the check multiple times; :program:`clang-tidy` will deduplicate - _identical_ warnings, but if the warnings are slightly different, all of them - will be shown to the user (and used for applying fixes, if any); -3. making replacements to a macro body/template definition may be fine for some - macro expansions/template instantiations, but easily break some other - expansions/instantiations. - -.. _lit: http://llvm.org/docs/CommandGuide/lit.html -.. _FileCheck: http://llvm.org/docs/CommandGuide/FileCheck.html -.. _test/clang-tidy/google-readability-casting.cpp: http://reviews.llvm.org/diffusion/L/browse/clang-tools-extra/trunk/test/clang-tidy/google-readability-casting.cpp - - -Running clang-tidy on LLVM --------------------------- - -To test a check it's best to try it out on a larger code base. LLVM and Clang -are the natural targets as you already have the source code around. The most -convenient way to run :program:`clang-tidy` is with a compile command database; -CMake can automatically generate one, for a description of how to enable it see -`How To Setup Tooling For LLVM`_. Once ``compile_commands.json`` is in place and -a working version of :program:`clang-tidy` is in ``PATH`` the entire code base -can be analyzed with ``clang-tidy/tool/run-clang-tidy.py``. The script executes -:program:`clang-tidy` with the default set of checks on every translation unit -in the compile command database and displays the resulting warnings and errors. -The script provides multiple configuration flags. - -* The default set of checks can be overridden using the ``-checks`` argument, - taking the identical format as :program:`clang-tidy` does. For example - ``-checks=-*,modernize-use-override`` will run the ``modernize-use-override`` - check only. - -* To restrict the files examined you can provide one or more regex arguments - that the file names are matched against. - ``run-clang-tidy.py clang-tidy/.*Check\.cpp`` will only analyze clang-tidy - checks. It may also be necessary to restrict the header files warnings are - displayed from using the ``-header-filter`` flag. It has the same behavior - as the corresponding :program:`clang-tidy` flag. - -* To apply suggested fixes ``-fix`` can be passed as an argument. This gathers - all changes in a temporary directory and applies them. Passing ``-format`` - will run clang-format over changed lines. - - -On checks profiling -------------------- - -:program:`clang-tidy` can collect per-check profiling info, and output it -for each processed source file (translation unit). - -To enable profiling info collection, use the ``-enable-check-profile`` argument. -The timings will be output to ``stderr`` as a table. Example output: - -.. code-block:: console - - $ clang-tidy -enable-check-profile -checks=-*,readability-function-size source.cpp - ===-------------------------------------------------------------------------=== - clang-tidy checks profiling - ===-------------------------------------------------------------------------=== - Total Execution Time: 1.0282 seconds (1.0258 wall clock) - - ---User Time--- --System Time-- --User+System-- ---Wall Time--- --- Name --- - 0.9136 (100.0%) 0.1146 (100.0%) 1.0282 (100.0%) 1.0258 (100.0%) readability-function-size - 0.9136 (100.0%) 0.1146 (100.0%) 1.0282 (100.0%) 1.0258 (100.0%) Total - -It can also store that data as JSON files for further processing. Example output: - -.. code-block:: console +``NOLINT``/``NOLINTNEXTLINE``), whereas in check names list (inside the +parenthesis) whitespaces can be used and will be ignored. - $ clang-tidy -enable-check-profile -store-check-profile=. -checks=-*,readability-function-size source.cpp - $ # Note that there won't be timings table printed to the console. - $ ls /tmp/out/ - 20180516161318717446360-source.cpp.json - $ cat 20180516161318717446360-source.cpp.json - { - "file": "/path/to/source.cpp", - "timestamp": "2018-05-16 16:13:18.717446360", - "profile": { - "time.clang-tidy.readability-function-size.wall": 1.0421266555786133e+00, - "time.clang-tidy.readability-function-size.user": 9.2088400000005421e-01, - "time.clang-tidy.readability-function-size.sys": 1.2418899999999974e-01 - } - } - -There is only one argument that controls profile storage: - -* ``-store-check-profile=<prefix>`` - - By default reports are printed in tabulated format to stderr. When this option - is passed, these per-TU profiles are instead stored as JSON. - If the prefix is not an absolute path, it is considered to be relative to the - directory from where you have run :program:`clang-tidy`. All ``.`` and ``..`` - patterns in the path are collapsed, and symlinks are resolved. - - Example: - Let's suppose you have a source file named ``example.cpp``, located in the - ``/source`` directory. Only the input filename is used, not the full path - to the source file. Additionally, it is prefixed with the current timestamp. - - * If you specify ``-store-check-profile=/tmp``, then the profile will be saved - to ``/tmp/<ISO8601-like timestamp>-example.cpp.json`` - - * If you run :program:`clang-tidy` from within ``/foo`` directory, and specify - ``-store-check-profile=.``, then the profile will still be saved to - ``/foo/<ISO8601-like timestamp>-example.cpp.json`` +.. _LibTooling: https://clang.llvm.org/docs/LibTooling.html +.. _How To Setup Tooling For LLVM: https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html diff --git a/docs/clangd.rst b/docs/clangd.rst index 0b276380..7910fac3 100644 --- a/docs/clangd.rst +++ b/docs/clangd.rst @@ -1,161 +1,6 @@ -============ -Clangd -============ +:orphan: -.. contents:: +.. meta:: + :http-equiv=refresh: 0;URL='clangd/' -.. toctree:: - :maxdepth: 1 - -:program:`Clangd` is an implementation of the `Language Server Protocol -<https://github.com/Microsoft/language-server-protocol>`_ leveraging Clang. -Clangd's goal is to provide language "smartness" features like code completion, -find references, etc. for clients such as C/C++ Editors. - -Using Clangd -================== - -:program:`Clangd` is not meant to be used by C/C++ developers directly but -rather from a client implementing the protocol. A client would be typically -implemented in an IDE or an editor. - -At the moment, `Visual Studio Code <https://code.visualstudio.com/>`_ is mainly -used in order to test :program:`Clangd` but more clients are likely to make -use of :program:`Clangd` in the future as it matures and becomes a production -quality tool. If you are interested in trying :program:`Clangd` in combination -with Visual Studio Code, you can start by `installing Clangd`_ or -`building Clangd`_, then open Visual Studio Code in the clangd-vscode folder and -launch the extension. - -Installing Clangd -================== - -Packages are available for debian-based distributions, see the `LLVM packages -page <http://apt.llvm.org/>`_. :program:`Clangd` is included in the -`clang-tools` package. -However, it is a good idea to check your distribution's packaging system first -as it might already be available. - -Otherwise, you can install :program:`Clangd` by `building Clangd`_ first. - -Building Clangd -================== - -You can follow the instructions for `building Clang -<https://clang.llvm.org/get_started.html>`_ but "extra Clang tools" is **not** -optional. - -Current Status -================== - -Many features could be implemented in :program:`Clangd`. -Here is a list of features that could be useful with the status of whether or -not they are already implemented in :program:`Clangd` and specified in the -Language Server Protocol. Note that for some of the features, it is not clear -whether or not they should be part of the Language Server Protocol, so those -features might be eventually developed outside :program:`Clangd` or as an -extension to the protocol. - -+-------------------------------------+------------+----------+ -| C/C++ Editor feature | LSP | Clangd | -+=====================================+============+==========+ -| Formatting | Yes | Yes | -+-------------------------------------+------------+----------+ -| Completion | Yes | Yes | -+-------------------------------------+------------+----------+ -| Diagnostics | Yes | Yes | -+-------------------------------------+------------+----------+ -| Fix-its | Yes | Yes | -+-------------------------------------+------------+----------+ -| Go to Definition | Yes | Yes | -+-------------------------------------+------------+----------+ -| Signature Help | Yes | Yes | -+-------------------------------------+------------+----------+ -| Document Highlights | Yes | Yes | -+-------------------------------------+------------+----------+ -| Rename | Yes | Yes | -+-------------------------------------+------------+----------+ -| Source hover | Yes | Yes | -+-------------------------------------+------------+----------+ -| Find References | Yes | No | -+-------------------------------------+------------+----------+ -| Code Lens | Yes | No | -+-------------------------------------+------------+----------+ -| Document Symbols | Yes | Yes | -+-------------------------------------+------------+----------+ -| Workspace Symbols | Yes | Yes | -+-------------------------------------+------------+----------+ -| Syntax and Semantic Coloring | No | No | -+-------------------------------------+------------+----------+ -| Code folding | No | No | -+-------------------------------------+------------+----------+ -| Call hierarchy | No | No | -+-------------------------------------+------------+----------+ -| Type hierarchy | No | No | -+-------------------------------------+------------+----------+ -| Organize Includes | No | No | -+-------------------------------------+------------+----------+ -| Quick Assist | No | No | -+-------------------------------------+------------+----------+ -| Extract Local Variable | No | No | -+-------------------------------------+------------+----------+ -| Extract Function/Method | No | No | -+-------------------------------------+------------+----------+ -| Hide Method | No | No | -+-------------------------------------+------------+----------+ -| Implement Method | No | No | -+-------------------------------------+------------+----------+ -| Gen. Getters/Setters | No | No | -+-------------------------------------+------------+----------+ - -Editor Integration -================== - -Any full-featured Language Server Protocol Client implementation should work -with :program:`Clangd`. This `list -<https://langserver.org/#implementations-client>`_ contains information about -extensions and plugins that are known to work for different editors. - -Vim Integration ---------------- - -LanguageClient-neovim -~~~~~~~~~~~~~~~~~~~~~ - -One of the options of using :program:`Clangd` in :program:`vim` (or -:program:`nvim`) is to utilize `LanguageClient-neovim -<https://github.com/autozimu/LanguageClient-neovim>`_ plugin. Please see the -`Clangd Wiki page -<https://github.com/autozimu/LanguageClient-neovim/wiki/Clangd>`_ for -instructions. - -VSCode Integration ------------------- - -:program:`VSCode` provides `vscode-clangd -<https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd>`_ -which is published in Visual Studio Marketplace and can be installed direcetly -from :program:`VSCode`. - -Emacs Integration ------------------ - -:program:`Emacs` provides `lsp-mode <github.com/emacs-lsp/lsp-mode>`_ and -`Eglot <https://github.com/joaotavora/eglot>`_ plugins for LSP integration. - -Getting Involved -================== - -A good place for interested contributors is the `Clangd developer mailing list -<http://lists.llvm.org/mailman/listinfo/clangd-dev>`_. For discussions with the -broader community on topics not only related to Clangd, use -`Clang developer mailing list -<http://lists.llvm.org/mailman/listinfo/cfe-dev>`_. -If you're also interested in contributing patches to :program:`Clangd`, take a -look at the `LLVM Developer Policy -<http://llvm.org/docs/DeveloperPolicy.html>`_ and `Code Reviews -<http://llvm.org/docs/Phabricator.html>`_ page. Contributions of new features -to the `Language Server Protocol -<https://github.com/Microsoft/language-server-protocol>`_ itself would also be -very useful, so that :program:`Clangd` can eventually implement them in a -conforming way. +All :program:`clangd` documentation was moved to the :doc:`clangd/index` pages. diff --git a/docs/clangd/ApplyClangTidyFixInVSCode.gif b/docs/clangd/ApplyClangTidyFixInVSCode.gif Binary files differnew file mode 100644 index 00000000..b07bdeb4 --- /dev/null +++ b/docs/clangd/ApplyClangTidyFixInVSCode.gif diff --git a/docs/clangd/ApplyFixInVSCode.gif b/docs/clangd/ApplyFixInVSCode.gif Binary files differnew file mode 100644 index 00000000..929a98c3 --- /dev/null +++ b/docs/clangd/ApplyFixInVSCode.gif diff --git a/docs/clangd/CodeCompletionInEmacsCompanyMode.png b/docs/clangd/CodeCompletionInEmacsCompanyMode.png Binary files differnew file mode 100644 index 00000000..1accc5af --- /dev/null +++ b/docs/clangd/CodeCompletionInEmacsCompanyMode.png diff --git a/docs/clangd/CodeCompletionInSublimeText.png b/docs/clangd/CodeCompletionInSublimeText.png Binary files differnew file mode 100644 index 00000000..b09fed3b --- /dev/null +++ b/docs/clangd/CodeCompletionInSublimeText.png diff --git a/docs/clangd/CodeCompletionInVSCode.png b/docs/clangd/CodeCompletionInVSCode.png Binary files differnew file mode 100644 index 00000000..bc42e9dd --- /dev/null +++ b/docs/clangd/CodeCompletionInVSCode.png diff --git a/docs/clangd/CodeCompletionInYCM.png b/docs/clangd/CodeCompletionInYCM.png Binary files differnew file mode 100644 index 00000000..b74508d6 --- /dev/null +++ b/docs/clangd/CodeCompletionInYCM.png diff --git a/docs/clangd/CodeCompletionInsertsNamespaceQualifiersInVSCode.gif b/docs/clangd/CodeCompletionInsertsNamespaceQualifiersInVSCode.gif Binary files differnew file mode 100644 index 00000000..f0d49d63 --- /dev/null +++ b/docs/clangd/CodeCompletionInsertsNamespaceQualifiersInVSCode.gif diff --git a/docs/clangd/DeveloperDocumentation.rst b/docs/clangd/DeveloperDocumentation.rst new file mode 100644 index 00000000..75843279 --- /dev/null +++ b/docs/clangd/DeveloperDocumentation.rst @@ -0,0 +1,29 @@ +================================== +Developer documentation for clangd +================================== + +.. toctree:: + :maxdepth: 1 + + Extensions + +Compiling clangd +================ + +To build clangd from source, please follow the instructions for `building Clang +<https://clang.llvm.org/get_started.html>`_ and include LLVM, Clang, and the +"extra Clang tools" in your build. + +Contributing to clangd +====================== + +A good place for interested contributors is the `Clangd developer mailing list +<https://lists.llvm.org/mailman/listinfo/clangd-dev>`_. For discussions with +the broader community on topics not only related to Clangd, use `Clang +developer mailing list <https://lists.llvm.org/mailman/listinfo/cfe-dev>`_. If +you're also interested in contributing patches to clangd, take a look at the +`LLVM Developer Policy <https://llvm.org/docs/DeveloperPolicy.html>`_ and `Code +Reviews <https://llvm.org/docs/Phabricator.html>`_ page. Contributions of new +features to the `Language Server Protocol +<https://github.com/Microsoft/language-server-protocol>`_ itself would also be +very useful, so that clangd can eventually implement them in a conforming way. diff --git a/docs/clangd/DiagnosticsInEmacsEglot.png b/docs/clangd/DiagnosticsInEmacsEglot.png Binary files differnew file mode 100644 index 00000000..f5be84bf --- /dev/null +++ b/docs/clangd/DiagnosticsInEmacsEglot.png diff --git a/docs/clangd/ErrorsInVSCode.png b/docs/clangd/ErrorsInVSCode.png Binary files differnew file mode 100644 index 00000000..52de4029 --- /dev/null +++ b/docs/clangd/ErrorsInVSCode.png diff --git a/docs/clangd/Extensions.rst b/docs/clangd/Extensions.rst new file mode 100644 index 00000000..6c972ebd --- /dev/null +++ b/docs/clangd/Extensions.rst @@ -0,0 +1,175 @@ +=================== +Protocol extensions +=================== + +.. contents:: + +clangd supports some features that are not in the official +`Language Server Protocol specification +<https://microsoft.github.io/language-server-protocol/specification>`__. + +We cautious about adding extensions. The most important considerations are: + +- **Editor support**: How many users will the feature be available to? +- **Standardization**: Is the feature stable? Is it likely to be adopted by more + editors over time? +- **Utility**: Does the feature provide a lot of value? +- **Complexity**: Is this hard to implement in clangd, or constrain future work? + Is the protocol complicated? + +These extensions may evolve or disappear over time. If you use them, try to +recover gracefully if the structures aren't what's expected. + +Switch between the implementation file and the header +===================================================== + +*This extension is supported in clangd 6 and newer.* + +Switching between the implementation file and the header is an important +feature for C++. A language server that understands C++ can do a better job +than the editor. + +**New client->server request**: ``textDocument/switchSourceHeader``. + +Lets editors switch between the main source file (``*.cpp``) and header (``*.h``). + +Parameter: ``TextDocumentIdentifier``: an open file. + +Result: ``string``: the URI of the corresponding header (if a source file was +provided) or source file (if a header was provided). + +If the corresponding file can't be determined, ``""`` is returned. + +File status +=========== + +*This extension is supported in clangd 8 and newer.* + +It is important to provide feedback to the user when the UI is not responsive. + +This extension provides information about activity on clangd's per-file worker +thread. This information can be displayed to users to let them know that the +language server is busy with something. For example, in clangd, building the +AST blocks many other operations. + +**New server->client notification**: ``textDocument/clangd.fileStatus`` + +Sent when the current activity for a file changes. Replaces previous activity +for that file. + +Parameter: ``FileStatus`` object with properties: + +- ``uri : string``: the document whose status is being updated. +- ``state : string``: human-readable information about current activity. + +**New initialization option**: ``initializationOptions.clangdFileStatus : bool`` + +Enables receiving ``textDocument/clangd.fileStatus`` notifications. + +Compilation commands +==================== + +*This extension is supported in clangd 8 and newer.* + +clangd relies on knowing accurate compilation options to correctly interpret a +file. Typically they are found in a ``compile_commands.json`` file in a +directory that contains the file, or an ancestor directory. The following +extensions allow editors to supply the commands over LSP instead. + +**New initialization option**: ``initializationOptions.compilationDatabasePath : string`` + +Specifies the directory containing the compilation database (e.g., +``compile_commands.json``). This path will be used for all files, instead of +searching their ancestor directories. + +**New initialization option**: ``initializationOptions.fallbackFlags : string[]`` + +Controls the flags used when no specific compile command is found. The compile +command will be approximately ``clang $FILE $fallbackFlags`` in this case. + +**New configuration setting**: ``settings.compilationDatabaseChanges : {string: CompileCommand}`` + +Provides compile commands for files. This can also be provided on startup as +``initializationOptions.compilationDatabaseChanges``. + +Keys are file paths (Not URIs!) + +Values are ``{workingDirectory: string, compilationCommand: string[]}``. + +Force diagnostics generation +============================ + +*This extension is supported in clangd 7 and newer.* + +Clangd does not regenerate diagnostics for every version of a file (e.g., after +every keystroke), as that would be too slow. Its heuristics ensure: + +- diagnostics do not get too stale, +- if you stop editing, diagnostics will catch up. + +This extension allows editors to force diagnostics to be generated or not +generated at a particular revision. + +**New property of** ``textDocument/didChange`` **request**: ``wantDiagnostics : bool`` + +- if true, diagnostics will be produced for exactly this version. +- if false, diagnostics will not be produced for this version, even if there + are no further edits. +- if unset, diagnostics will be produced for this version or some subsequent + one in a bounded amount of time. + +Diagnostic categories +===================== + +*This extension is supported in clangd 8 and newer.* + +Clang compiler groups diagnostics into categories (e.g., "Inline Assembly +Issue"). Clangd can emit these categories for interested editors. + +**New property of** ``Diagnostic`` **object**: ``category : string``: + +A human-readable name for a group of related diagnostics. Diagnostics with the +same code will always have the same category. + +**New client capability**: ``textDocument.publishDiagnostics.categorySupport``: + +Requests that clangd send ``Diagnostic.category``. + +Inline fixes for diagnostics +============================ + +*This extension is supported in clangd 8 and newer.* + +LSP specifies that code actions for diagnostics (fixes) are retrieved +asynchronously using ``textDocument/codeAction``. clangd always computes fixes +eagerly. Providing them alongside diagnostics can improve the UX in editors. + +**New property of** ``Diagnostic`` **object**: ``codeActions : CodeAction[]``: + +All the code actions that address this diagnostic. + +**New client capability**: ``textDocument.publishDiagnostics.codeActionsInline : bool`` + +Requests clangd to send ``Diagnostic.codeActions``. + +Symbol info request +=================== + +*This extension is supported in clangd 8 and newer.* + +**New client->server request**: ``textDocument/symbolInfo``: + +This request attempts to resolve the symbol under the cursor, without +retrieving further information (like definition location, which may require +consulting an index). This request was added to support integration with +indexes outside clangd. + +Parameter: ``TextDocumentPositionParams`` + +Response: ``SymbolDetails``, an object with properties: + +- ``name : string`` the unqualified name of the symbol +- ``containerName : string`` the enclosing namespace, class etc (without + trailing ``::``) +- ``usr : string``: the clang-specific "unified symbol resolution" identifier +- ``id : string?``: the clangd-specific opaque symbol ID diff --git a/docs/clangd/Features.rst b/docs/clangd/Features.rst new file mode 100644 index 00000000..3e6e745a --- /dev/null +++ b/docs/clangd/Features.rst @@ -0,0 +1,267 @@ +======== +Features +======== + +.. contents:: + +.. role:: raw-html(raw) + :format: html + +Here is what clangd can do for you. Screenshots below show `VSCode +<https://code.visualstudio.com/>`__; the available features and UI depend on +the editor. + +Errors and warnings +=================== + +clangd runs the clang compiler on your code as you type, and shows errors and +warnings in-place. Some errors are suppressed: diagnostics that require +expanding templates in headers are disabled for performance reasons. + +:raw-html:`<details><summary markdown="span">Screenshot</summary>` + +.. image:: ErrorsInVSCode.png + :align: center + :alt: Demonstration of errors + +:raw-html:`</details>` + +Fixes in errors and warnings +---------------------------- + +The compiler can suggest fixes for many common problems automatically, and +clangd can update the code for you. + +:raw-html:`<details><summary markdown="span">Animated demo</summary>` + +.. image:: ApplyFixInVSCode.gif + :align: center + :alt: Applying a fix suggested by the compiler + +:raw-html:`</details>` + +**(New in v9)** +If a missing symbol was seen in a file you've edited recently, clangd will +suggest inserting it. + +clang-tidy checks +----------------- + +**(New in v9)** +clangd embeds `clang-tidy <https://clang.llvm.org/extra/clang-tidy/>`__ +which provides extra hints about code problems: bug-prone patterns, +performance traps, and style issues. + +:raw-html:`<details><summary markdown="span">Animated demo</summary>` + +.. image:: ApplyClangTidyFixInVSCode.gif + :align: center + :alt: Applying a fix suggested by the compiler + +:raw-html:`</details>` + +clangd respects your project's ``.clang-tidy`` file which controls the checks +to run. Not all checks work within clangd. You must pass the ``-clang-tidy`` +flag to enable this feature. + +Code completion +=============== + +You'll see suggestions as you type based on what methods, variables, etc are +available in this context. + +:raw-html:`<details><summary markdown="span">Screenshot</summary>` + +.. image:: CodeCompletionInVSCode.png + :align: center + :alt: Code completion demonstration + +:raw-html:`</details>` + +Abbreviating words may help you find the right result faster. If you type in +``camelCase`` but the function you're looking for is ``snake_case``, that's OK. + +Insertion of namespace qualifiers and includes +---------------------------------------------- + +**(New in v8)** +clangd will sometimes suggest results from other files and namespaces. In this +case the correct qualifier and ``#include`` directive will be inserted. + +:raw-html:`<details><summary markdown="span">Animated demo</summary>` + +.. image:: CodeCompletionInsertsNamespaceQualifiersInVSCode.gif + :align: center + :alt: Code completion inserts namespace qualifiers + +:raw-html:`</details>` + +Signature help +-------------- + +Some editors will show you the parameters of the function you're calling, as +you fill them in. + +:raw-html:`<details><summary markdown="span">Animated demo</summary>` + +.. image:: SignatureHelpInVSCode.gif + :align: center + :alt: Demonstration of the signature help feature + +:raw-html:`</details>` + +Cross-references +================ + +The following features let you navigate your codebase. + +If there is no project-wide index, cross-references work across the files +you have opened. + +**(New in v9)** +clangd will also automatically index your whole project. + +Find definition/declaration +--------------------------- + +Jump to the definition or declaration of a symbol under the cursor. + +:raw-html:`<details><summary markdown="span">Animated demo</summary>` + +.. image:: GoToDefinitionInVSCode.gif + :align: center + :alt: Demonstration of the "Go to definition" feature + +:raw-html:`</details>` + +**(New in v9)** +Some editors only expose "find definition"; use "find definition" on the +definition to jump to the declaration. + +"Find definition" also works on ``#include`` lines, to jump to the included +file. + +Find references +--------------- + +Show all references to a symbol under the cursor. + +:raw-html:`<details><summary markdown="span">Animated demo</summary>` + +.. image:: FindAllReferencesInVSCode.gif + :align: center + :alt: Demonstration of the "Find all references" feature + +:raw-html:`</details>` + +Some editors will automatically highlight local references to the selected +symbol as you move around a file. + +Navigation +========== + +clangd informs the editor of the code structure in the current file. +Some editors use this to present an outline view: + +:raw-html:`<details><summary markdown="span">Screenshot</summary>` + +.. image:: OutlineInVSCode.png + :align: center + :alt: Outline of a file + +:raw-html:`</details>` + +In VSCode, the outline is also presented as breadcrumbs that allow jumping to a +symbol within the current file. Searching for symbols within the scope of the +whole project is also possible. + +:raw-html:`<details><summary markdown="span">Animated demo</summary>` + +.. image:: NavigationWithBreadcrumbsInVSCode.gif + :align: center + :alt: Navigation with breadcrumbs + +:raw-html:`</details>` + +Formatting +========== + +clangd embeds `clang-format <https://clang.llvm.org/docs/ClangFormat.html>`__, +which can reformat your code: fixing indentation, breaking lines, and reflowing +comments. + +:raw-html:`<details><summary markdown="span">Animated demo</summary>` + +.. image:: FormatSelectionInVSCode.gif + :align: center + :alt: Formatting selected code + +:raw-html:`</details>` + +clangd respects your project's ``.clang-format`` file which controls styling +options. + +Format-as-you-type is experimental and doesn't work well yet. + +Complete list of features +========================= + +Here is a list of features that could be useful for editors, together with the +implementation status in clangd, and specification in the Language Server +Protocol. + +It is not clear whether or not some of the features mentioned below should be a +part of the Language Server Protocol; those features might be eventually +developed outside clangd or become clangd extensions to LSP. + ++-------------------------------------+------------+----------+ +| C/C++ Editor feature | LSP | Clangd | ++=====================================+============+==========+ +| Formatting | Yes | Yes | ++-------------------------------------+------------+----------+ +| Completion | Yes | Yes | ++-------------------------------------+------------+----------+ +| Diagnostics | Yes | Yes | ++-------------------------------------+------------+----------+ +| Fix-its | Yes | Yes | ++-------------------------------------+------------+----------+ +| Go to Definition | Yes | Yes | ++-------------------------------------+------------+----------+ +| Signature Help | Yes | Yes | ++-------------------------------------+------------+----------+ +| Document Highlights | Yes | Yes | ++-------------------------------------+------------+----------+ +| Rename | Yes | Yes | ++-------------------------------------+------------+----------+ +| Source hover | Yes | Yes | ++-------------------------------------+------------+----------+ +| Find References | Yes | Yes | ++-------------------------------------+------------+----------+ +| Document Symbols | Yes | Yes | ++-------------------------------------+------------+----------+ +| Workspace Symbols | Yes | Yes | ++-------------------------------------+------------+----------+ +| Code Lens | Yes | No | ++-------------------------------------+------------+----------+ +| Code folding | Yes | No | ++-------------------------------------+------------+----------+ +| Extract Local Variable | Yes | No | ++-------------------------------------+------------+----------+ +| Extract Function/Method | Yes | No | ++-------------------------------------+------------+----------+ +| Quick Assist | Yes | No | ++-------------------------------------+------------+----------+ +| Hide Method | Yes | No | ++-------------------------------------+------------+----------+ +| Implement Method | Yes | No | ++-------------------------------------+------------+----------+ +| Gen. Getters/Setters | Yes | No | ++-------------------------------------+------------+----------+ +| Syntax and Semantic Coloring | No | No | ++-------------------------------------+------------+----------+ +| Call hierarchy | No | No | ++-------------------------------------+------------+----------+ +| Type hierarchy | No | No | ++-------------------------------------+------------+----------+ +| Organize Includes | No | No | ++-------------------------------------+------------+----------+ diff --git a/docs/clangd/FindAllReferencesInVSCode.gif b/docs/clangd/FindAllReferencesInVSCode.gif Binary files differnew file mode 100644 index 00000000..b9eecf3c --- /dev/null +++ b/docs/clangd/FindAllReferencesInVSCode.gif diff --git a/docs/clangd/FormatSelectionInVSCode.gif b/docs/clangd/FormatSelectionInVSCode.gif Binary files differnew file mode 100644 index 00000000..1d4be410 --- /dev/null +++ b/docs/clangd/FormatSelectionInVSCode.gif diff --git a/docs/clangd/GoToDefinitionInVSCode.gif b/docs/clangd/GoToDefinitionInVSCode.gif Binary files differnew file mode 100644 index 00000000..396966f7 --- /dev/null +++ b/docs/clangd/GoToDefinitionInVSCode.gif diff --git a/docs/clangd/Installation.rst b/docs/clangd/Installation.rst new file mode 100644 index 00000000..1552efce --- /dev/null +++ b/docs/clangd/Installation.rst @@ -0,0 +1,371 @@ +=========================== +Getting started with clangd +=========================== + +.. contents:: + +.. role:: raw-html(raw) + :format: html + +To use clangd, you need to: + +- install clangd, +- install a plugin for your editor, +- tell clangd how your project is built. + +Installing clangd +================= + +You need a **recent** version of clangd: 7.0 was the first usable release, and +8.0 is much better. + +After installing, ``clangd --version`` should print ``clangd version 7.0.0`` or +later. + +:raw-html:`<details><summary markdown="span">macOS</summary>` + +`Homebrew <https://brew.sh>`__ can install clangd along with LLVM: + +.. code-block:: console + + $ brew install llvm + +If you don't want to use Homebrew, you can download the a binary release of +LLVM from `releases.llvm.org <http://releases.llvm.org/download.html>`__. +Alongside ``bin/clangd`` you will need at least ``lib/clang/*/include``: + +.. code-block:: console + + $ cp clang+llvm-7.0.0/bin/clangd /usr/local/bin/clangd + $ cp -r clang+llvm-7.0.0/lib/clang/ /usr/local/lib/ + +:raw-html:`</details>` + +:raw-html:`<details><summary markdown="span">Windows</summary>` + +Download and run the LLVM installer from `releases.llvm.org +<http://releases.llvm.org/download.html>`__. + +:raw-html:`</details>` + +:raw-html:`<details><summary markdown="span">Debian/Ubuntu</summary>` + +The ``clang-tools`` package usually contains an old version of clangd. + +Try to install the latest release (8.0): + +.. code-block:: console + + $ sudo apt-get install clang-tools-8 + +If that is not found, at least ``clang-tools-7`` should be available. + +The ``clangd`` executable will be installed as ``/usr/bin/clangd-8``. Make it +the default ``clangd``: + +.. code-block:: console + + $ sudo update-alternatives --install /usr/bin/clangd clangd /usr/bin/clangd-8 100 + +:raw-html:`</details>` + +:raw-html:`<details><summary markdown="span">Other systems</summary>` + +Most distributions include clangd in a ``clang-tools`` package, or in the full +``llvm`` distribution. + +For some platforms, binaries are also avaliable at `releases.llvm.org +<http://releases.llvm.org/download.html>`__. + +:raw-html:`</details>` + +Editor plugins +============== + +Language Server plugins are available for many editors. In principle, clangd +should work with any of them, though the feature set and UI may vary. + +Here are some plugins we know work well with clangd. + +:raw-html:`<details><summary markdown="span">YouCompleteMe for Vim</summary>` + +`YouCompleteMe <https://valloric.github.io/YouCompleteMe/>`__ supports clangd. +However, clangd support is not turned on by default, so you must install +YouCompleteMe with ``install.py --clangd-completer``. + +We recommend changing a couple of YCM's default settings. In ``.vimrc`` add: + +:: + + " Let clangd fully control code completion + let g:ycm_clangd_uses_ycmd_caching = 0 + " Use installed clangd, not YCM-bundled clangd which doesn't get updates. + let g:ycm_clangd_binary_path = exepath("clangd") + +You should see errors highlighted and code completions as you type. + +.. image:: CodeCompletionInYCM.png + :align: center + :alt: Code completion in YouCompleteMe + +YouCompleteMe supports many of clangd's features: + +- code completion, +- diagnostics and fixes (``:YcmCompleter FixIt``), +- find declarations, references, and definitions (``:YcmCompleter GoTo`` etc), +- rename symbol (``:YcmCompleter RefactorRename``). + +**Under the hood** + +- **Debug logs**: run ``:YcmDebugInfo`` to see clangd status, and ``:YcmToggleLogs`` + to view clangd's debug logs. +- **Command-line flags**: Set ``g:ycm_clangd_args`` in ``.vimrc``, e.g.: + + :: + + let g:ycm_clangd_args = ['-log=verbose', '-pretty'] + +- **Alternate clangd binary**: set ``g:ycm_clangd_binary_path`` in ``.vimrc``. + +:raw-html:`</details>` + +:raw-html:`<details><summary markdown="span">LanguageClient for Vim and Neovim</summary>` + +`LanguageClient-neovim <https://github.com/autozimu/LanguageClient-neovim>`__ +has `instructions for using clangd +<https://github.com/autozimu/LanguageClient-neovim/wiki/Clangd>`__, and **may** +be easier to install than YouCompleteMe. + +:raw-html:`</details>` + +:raw-html:`<details><summary markdown="span">Eglot for Emacs</summary>` + +`eglot <https://github.com/joaotavora/eglot>`__ can be configured to work with +clangd. + +Install eglot with ``M-x package-install RET eglot RET``. + +Add the following to ``~/.emacs`` to enable clangd: + +:: + + (require 'eglot) + (add-to-list 'eglot-server-programs '((c++-mode c-mode) "clangd")) + (add-hook 'c-mode-hook 'eglot-ensure) + (add-hook 'c++-mode-hook 'eglot-ensure) + +After restarting you should see diagnostics for errors in your code, and ``M-x +completion-at-point`` should work. + +.. image:: DiagnosticsInEmacsEglot.png + :align: center + :alt: Diagnostics in Emacs + +eglot supports many of clangd's features, with caveats: + +- code completion, though the interaction is quite poor (even with + ``company-mode``, see below), +- diagnostics and fixes, +- find definitions and references (``M-x xref-find-definitions`` etc), +- hover and highlights, +- code actions (``M-x eglot-code-actions``). + +**company-mode** + +eglot does have basic integration with company-mode, which provides a more +fluent completion UI. + +You can install it with ``M-x package-install RET company RET``, and enable it +with ``M-x company-mode``. + +**company-clang is enabled by default**, and will interfere with clangd. +Disable it in ``M-x customize-variable RET company-backends RET``. + +Completion still has some major limitations: + +- completions are alphabetically sorted, not ranked. +- only pure-prefix completions are shown - no fuzzy matches. +- completion triggering seems to be a bit hit-and-miss. + +.. image:: CodeCompletionInEmacsCompanyMode.png + :align: center + :alt: Completion in company-mode + +**Under the hood** + +- **Debug logs**: available in the ``EGLOT stderr`` buffer. +- **Command-line flags and alternate binary**: instead of adding ``"clangd"`` + to ``eglot-server-programs``, add ``("/path/to/clangd" "-log=verbose")`` etc. + +:raw-html:`</details>` + +:raw-html:`<details><summary markdown="span">Visual Studio Code</summary>` + +The official extension is `vscode-clangd +<https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd>`__ +and can be installed from within VSCode. + +Choose **View** --> **Extensions**, then search for "clangd". (Make sure the +Microsoft C/C++ extension is **not** installed). + +After restarting, you should see red underlines underneath errors, and you +should get rich code completions including e.g. function parameters. + +.. image:: CodeCompletionInVSCode.png + :align: center + :alt: Code completion in VSCode + +vscode-clangd has excellent support for all clangd features, including: + +- code completion +- diagnostics and fixes +- find declarations, references, and definitions +- find symbol in file (``Ctrl-P @foo``) or workspace (``Ctrl-P #foo``) +- hover and highlights +- code actions + +**Under the hood** + +- **Debug logs**: when clangd is running, you should see "Clang Language + Server" in the dropdown of the Output panel (**View** -> **Output**). + +- **Command-line flags**: these can be passed in the ``clangd.arguments`` array + in your ``settings.json``. (**File** -> **Preferences** -> **Settings**). + +- **Alternate clangd binary**: set the ``clangd.path`` string in + ``settings.json``. + +:raw-html:`</details>` + +:raw-html:`<details><summary markdown="span">Sublime Text</summary>` + +`tomv564/LSP <https://github.com/tomv564/LSP>`__ works with clangd out of the box. + +Select **Tools** --> **Install Package Control** (if you haven't installed it +yet). + +Press ``Ctrl-Shift-P`` and select **Package Control: Install Package**. Select +**LSP**. + +Press ``Ctrl-Shift-P`` and select **LSP: Enable Language Server Globally**. +Select **clangd**. + +Open a C++ file, and you should see diagnostics and completion: + +.. image:: CodeCompletionInSublimeText.png + :align: center + :alt: Code completion in Sublime Text + + +The LSP package has excellent support for all most clangd features, including: + +- code completion (a bit noisy due to how snippets are presented) +- diagnostics and fixes +- find definition and references +- hover and highlights +- code actions + +**Under the hood** + +Settings can be tweaked under **Preferences** --> **Package Settings** --> +**LSP**. + +- **Debug logs**: add ``"log_stderr": true`` +- **Command-line flags and alternate clangd binary**: inside the ``"clients": + {"clangd": { ... } }`` section, add ``"command": ["/path/to/clangd", + "-log=verbose"]`` etc. + +:raw-html:`</details>` + +:raw-html:`<details><summary markdown="span">Other editors</summary>` + +There is a directory of LSP clients at `langserver.org +<http://langserver.org>`__. + +A generic client should be configured to run the command ``clangd``, and +communicate via the language server protocol on standard input/output. + +If you don't have strong feelings about an editor, we suggest you try out +`VSCode <https://code.visualstudio.com/>`__, it has excellent language server +support and most faithfully demonstrates what clangd can do. + +:raw-html:`</details>` + +Project setup +============= + +To understand source code in your project, clangd needs to know the build +flags. (This is just a fact of life in C++, source files are not +self-contained.) + +By default, clangd will assume that source code is built as ``clang +some_file.cc``, and you'll probably get spurious errors about missing +``#include``\ d files, etc. There are a couple of ways to fix this. + +``compile_commands.json`` +------------------------- + +``compile_commands.json`` file provides compile commands for all source files +in the project. This file is usually generated by the build system, or tools +integrated with the build system. Clangd will look for this file in the parent +directories of the files you edit. + +:raw-html:`<details><summary markdown="span">CMake-based projects</summary>` + +If your project builds with CMake, it can generate ``compile_commands.json``. +You should enable it with: + +:: + + $ cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1 + +``compile_commands.json`` will be written to your build directory. You should +symlink it (or copy it) to the root of your source tree, if they are different. + +:: + + $ ln -s ~/myproject/compile_commands.json ~/myproject-build/ + +:raw-html:`</details>` + +:raw-html:`<details><summary markdown="span">Other build systems, using Bear</summary>` + +`Bear <https://github.com/rizsotto/Bear>`__ is a tool that generates a +``compile_commands.json`` file by recording a complete build. + +For a ``make``-based build, you can run ``make clean; bear make`` to generate the +file (and run a clean build!) + +:raw-html:`</details>` + +Other tools can also generate this file. See `the compile_commands.json +specification <https://clang.llvm.org/docs/JSONCompilationDatabase.html>`__. + +``compile_flags.txt`` +--------------------- + +If all files in a project use the same build flags, you can put those flags, +one flag per line, in ``compile_flags.txt`` in your source root. + +Clangd will assume the compile command is ``clang $FLAGS some_file.cc``. + +Creating this file by hand is a reasonable place to start if your project is +quite simple. + +Project-wide Index +================== + +By default clangd only has a view on symbols coming from files you are +currently editing. You can extend this view to whole project by providing a +project-wide index to clangd. There are two ways to do this. + +- Pass an experimental `-background-index` command line argument. With + this feature enabled, clangd incrementally builds an index of projects + that you work on and uses the just-built index automatically. + +- Generate an index file using `clangd-indexer + <https://github.com/llvm/llvm-project/blob/master/clang-tools-extra/clangd/indexer/IndexerMain.cpp>`__ + Then you can pass generated index file to clangd using + `-index-file=/path/to/index_file`. *Note that clangd-indexer isn't + included alongside clangd in the Debian clang-tools package. You will + likely have to build it from source to use this option.* diff --git a/docs/clangd/NavigationWithBreadcrumbsInVSCode.gif b/docs/clangd/NavigationWithBreadcrumbsInVSCode.gif Binary files differnew file mode 100644 index 00000000..499f5c1a --- /dev/null +++ b/docs/clangd/NavigationWithBreadcrumbsInVSCode.gif diff --git a/docs/clangd/OutlineInVSCode.png b/docs/clangd/OutlineInVSCode.png Binary files differnew file mode 100644 index 00000000..570a80de --- /dev/null +++ b/docs/clangd/OutlineInVSCode.png diff --git a/docs/clangd/SignatureHelpInVSCode.gif b/docs/clangd/SignatureHelpInVSCode.gif Binary files differnew file mode 100644 index 00000000..e5700f22 --- /dev/null +++ b/docs/clangd/SignatureHelpInVSCode.gif diff --git a/docs/clangd/index.rst b/docs/clangd/index.rst new file mode 100644 index 00000000..46939062 --- /dev/null +++ b/docs/clangd/index.rst @@ -0,0 +1,27 @@ +====== +clangd +====== + +.. toctree:: + :maxdepth: 1 + + Installation + Features + +What is clangd? +=============== + +clangd understands your C++ code and adds smart features to your editor: code +completion, compile errors, go-to-definition and more. + +clangd is a language server that implements the `Language Server Protocol +<https://github.com/Microsoft/language-server-protocol>`__; it can work with +many editors through a plugin. Here's Visual Studio Code with the clangd +plugin, demonstrating code completion: + +.. image:: CodeCompletionInVSCode.png + :align: center + :alt: Code completion in VSCode + +clangd is based on the `Clang <https://clang.llvm.org>`__ C++ compiler, and is +part of the `LLVM <https://llvm.org>`__ project. diff --git a/docs/conf.py b/docs/conf.py index 1b07e8ef..16e81051 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -49,9 +49,9 @@ copyright = u'2007-%d, The Clang Team' % date.today().year # built documents. # # The short version. -version = '8' +version = '9' # The full version, including alpha/beta/rc tags. -release = '8' +release = '9' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -121,7 +121,7 @@ html_theme = 'haiku' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = [] +html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. diff --git a/docs/doxygen.cfg.in b/docs/doxygen.cfg.in index 88095889..fd77fc47 100644 --- a/docs/doxygen.cfg.in +++ b/docs/doxygen.cfg.in @@ -752,7 +752,7 @@ INPUT = \ @abs_srcdir@/../clang-reorder-fields \ @abs_srcdir@/../clang-tidy \ @abs_srcdir@/../clangd \ - @abs_srcdir@/../include-fixer \ + @abs_srcdir@/../clang-include-fixer \ @abs_srcdir@/../modularize \ @abs_srcdir@/../pp-trace \ @abs_srcdir@/../tool-template \ diff --git a/docs/index.rst b/docs/index.rst index 8e6beb35..0fe98952 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,14 +1,9 @@ -.. Extra Clang Tools documentation master file, created by - sphinx-quickstart on Wed Feb 13 10:00:18 2013. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - .. title:: Welcome to Extra Clang Tools's documentation! Introduction ============ Welcome to the clang-tools-extra project which contains extra tools built using -Clang's tooling API's. +Clang's tooling APIs. .. toctree:: :maxdepth: 1 @@ -21,11 +16,12 @@ Contents :maxdepth: 2 clang-tidy/index - include-fixer + clang-include-fixer modularize pp-trace clang-rename - clangd + clangd/index + clangd/DeveloperDocumentation clang-doc diff --git a/docs/modularize.rst b/docs/modularize.rst index 6fe49b42..406ab9ce 100644 --- a/docs/modularize.rst +++ b/docs/modularize.rst @@ -42,9 +42,9 @@ To build from source: Before continuing, take a look at :doc:`ModularizeUsage` to see how to invoke modularize. -.. _Getting Started with the LLVM System: http://llvm.org/docs/GettingStarted.html -.. _Building LLVM with CMake: http://llvm.org/docs/CMake.html -.. _Clang Tools Documentation: http://clang.llvm.org/docs/ClangTools.html +.. _Getting Started with the LLVM System: https://llvm.org/docs/GettingStarted.html +.. _Building LLVM with CMake: https://llvm.org/docs/CMake.html +.. _Clang Tools Documentation: https://clang.llvm.org/docs/ClangTools.html What Modularize Checks ====================== @@ -262,4 +262,4 @@ names. If a header has one of these names, an underscore ('_') will be prepended to the name. For example, if the header name is ``header.h``, because ``header`` is a keyword, the module name will be ``_header``. For a list of the module map keywords, please see: -`Lexical structure <http://clang.llvm.org/docs/Modules.html#lexical-structure>`_ +`Lexical structure <https://clang.llvm.org/docs/Modules.html#lexical-structure>`_ diff --git a/docs/pp-trace.rst b/docs/pp-trace.rst index b8768ed0..ed01ae94 100644 --- a/docs/pp-trace.rst +++ b/docs/pp-trace.rst @@ -11,7 +11,7 @@ pp-trace User's Manual activity. It's also used as a test of Clang's PPCallbacks interface. It runs a given source file through the Clang preprocessor, displaying selected information from callback functions overridden in a -`PPCallbacks <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html>`_ +`PPCallbacks <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html>`_ derivation. The output is in a high-level YAML format, described in :ref:`OutputFormat`. @@ -23,7 +23,7 @@ pp-trace Usage Command Line Format ------------------- -``pp-trace [<pp-trace-options>] <source-file> [<front-end-options>]`` +``pp-trace [<pp-trace-options>] <source-file> [-- <front-end-options>]`` ``<pp-trace-options>`` is a place-holder for options specific to pp-trace, which are described below in @@ -32,7 +32,7 @@ specific to pp-trace, which are described below in ``<source-file>`` specifies the source file to run through the preprocessor. ``<front-end-options>`` is a place-holder for regular -`Clang Compiler Options <http://clang.llvm.org/docs/UsersManual.html#command-line-options>`_, +`Clang Compiler Options <https://clang.llvm.org/docs/UsersManual.html#command-line-options>`_, which must follow the <source-file>. .. _CommandLineOptions: @@ -40,12 +40,12 @@ which must follow the <source-file>. Command Line Options -------------------- -.. option:: -ignore <callback-name-list> +.. option:: -callbacks <comma-separated-globs> - This option specifies a comma-separated list of names of callbacks - that shouldn't be traced. It can be used to eliminate unwanted - trace output. The callback names are the name of the actual - callback function names in the PPCallbacks class: + This option specifies a comma-separated list of globs describing the list of + callbacks that should be traced. Globs are processed in order of appearance. + Positive globs add matched callbacks to the set, netative globs (those with + the '-' prefix) remove callacks from the set. * FileChanged * FileSkipped @@ -88,7 +88,7 @@ Command Line Options pp-trace Output Format ====================== -The pp-trace output is formatted as YAML. See http://yaml.org/ for general +The pp-trace output is formatted as YAML. See https://yaml.org/ for general YAML information. It's arranged as a sequence of information about the callback call, including the callback name and argument information, for example::: @@ -150,8 +150,8 @@ Note that in some cases, such as when a structure pointer is an argument value, only some key member or members are shown to represent the value, instead of trying to display all members of the structure. -`FileChanged <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a7cc8cfaf34114fc65e92af621cd6464e>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`FileChanged <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a7cc8cfaf34114fc65e92af621cd6464e>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ FileChanged is called when the preprocessor enters or exits a file, both the top level file being compiled, as well as any #include directives. It will @@ -177,8 +177,8 @@ Example::: FileType: C_User PrevFID: (invalid) -`FileSkipped <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ab5b338a0670188eb05fa7685bbfb5128>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`FileSkipped <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ab5b338a0670188eb05fa7685bbfb5128>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ FileSkipped is called when a source file is skipped as the result of header guard optimization. @@ -200,8 +200,8 @@ Example::: FilenameTok: "filename.h" FileType: C_User -`FileNotFound <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a3045151545f987256bfa8d978916ef00>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`FileNotFound <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a3045151545f987256bfa8d978916ef00>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ FileNotFound is called when an inclusion directive results in a file-not-found error. @@ -220,8 +220,8 @@ Example::: FileName: "/path/filename.h" RecoveryPath: -`InclusionDirective <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a557d9738c329793513a6f57d6b60de52>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`InclusionDirective <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a557d9738c329793513a6f57d6b60de52>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ InclusionDirective is called when an inclusion directive of any kind (#include</code>, #import</code>, etc.) has been processed, regardless of whether the inclusion will actually result in an inclusion. @@ -253,8 +253,8 @@ Example::: RelativePath: "Input/Level1B.h" Imported: (null) -`moduleImport <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#af32dcf1b8b7c179c7fcd3e24e89830fe>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`moduleImport <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#af32dcf1b8b7c179c7fcd3e24e89830fe>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ moduleImport is called when there was an explicit module-import syntax. @@ -275,8 +275,8 @@ Example::: Path: [{Name: Level1B, Loc: "d:/Clang/llvmnewmod/tools/clang/tools/extra/test/pp-trace/pp-trace-modules.cpp:4:9"}, {Name: Level2B, Loc: "d:/Clang/llvmnewmod/tools/clang/tools/extra/test/pp-trace/pp-trace-modules.cpp:4:17"}] Imported: Level2B -`EndOfMainFile <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a63e170d069e99bc1c9c7ea0f3bed8bcc>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`EndOfMainFile <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a63e170d069e99bc1c9c7ea0f3bed8bcc>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ EndOfMainFile is called when the end of the main file is reached. @@ -292,8 +292,8 @@ Example::: - Callback: EndOfMainFile -`Ident <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a3683f1d1fa513e9b6193d446a5cc2b66>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`Ident <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a3683f1d1fa513e9b6193d446a5cc2b66>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Ident is called when a #ident or #sccs directive is read. @@ -312,8 +312,8 @@ Example::: Loc: "D:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-ident.cpp:3:1" str: "$Id$" -`PragmaDirective <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a0a2d7a72c62184b3cbde31fb62c6f2f7>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`PragmaDirective <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a0a2d7a72c62184b3cbde31fb62c6f2f7>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PragmaDirective is called when start reading any pragma directive. @@ -332,8 +332,8 @@ Example::: Loc: "D:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-pragma.cpp:3:1" Introducer: PIK_HashPragma -`PragmaComment <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ace0d940fc2c12ab76441466aab58dc37>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`PragmaComment <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ace0d940fc2c12ab76441466aab58dc37>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PragmaComment is called when a #pragma comment directive is read. @@ -354,8 +354,8 @@ Example::: Kind: library Str: kernel32.lib -`PragmaDetectMismatch <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ab11158c9149fb8ad8af1903f4a6cd65d>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`PragmaDetectMismatch <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ab11158c9149fb8ad8af1903f4a6cd65d>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PragmaDetectMismatch is called when a #pragma detect_mismatch directive is read. @@ -376,8 +376,8 @@ Example::: Name: name Value: value -`PragmaDebug <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a57cdccb6dcc07e926513ac3d5b121466>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`PragmaDebug <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a57cdccb6dcc07e926513ac3d5b121466>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PragmaDebug is called when a #pragma clang __debug directive is read. @@ -396,8 +396,8 @@ Example::: Loc: "D:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-pragma.cpp:3:1" DebugType: warning -`PragmaMessage <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#abb42935d9a9fd8e2c4f51cfdc4ea2ae1>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`PragmaMessage <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#abb42935d9a9fd8e2c4f51cfdc4ea2ae1>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PragmaMessage is called when a #pragma message directive is read. @@ -420,8 +420,8 @@ Example::: Kind: PMK_Message Str: The message text. -`PragmaDiagnosticPush <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a0f3ff19762baa38fe6c5c58022d32979>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`PragmaDiagnosticPush <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a0f3ff19762baa38fe6c5c58022d32979>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PragmaDiagnosticPush is called when a #pragma gcc dianostic push directive is read. @@ -440,7 +440,7 @@ Example::: Loc: "D:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-pragma.cpp:3:1" Namespace: "GCC" -`PragmaDiagnosticPop <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ac94d789873122221fba8d76f6c5ea45e>`_ Callback +`PragmaDiagnosticPop <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ac94d789873122221fba8d76f6c5ea45e>`_ Callback ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PragmaDiagnosticPop is called when a #pragma gcc dianostic pop directive is read. @@ -460,8 +460,8 @@ Example::: Loc: "D:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-pragma.cpp:3:1" Namespace: "GCC" -`PragmaDiagnostic <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#afe7938f38a83cb7b4b25a13edfdd7bdd>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`PragmaDiagnostic <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#afe7938f38a83cb7b4b25a13edfdd7bdd>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PragmaDiagnostic is called when a #pragma gcc dianostic directive is read. @@ -484,8 +484,8 @@ Example::: mapping: MAP_WARNING Str: WarningName -`PragmaOpenCLExtension <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a92a20a21fadbab4e2c788f4e27fe07e7>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`PragmaOpenCLExtension <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a92a20a21fadbab4e2c788f4e27fe07e7>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PragmaOpenCLExtension is called when OpenCL extension is either disabled or enabled with a pragma. @@ -508,8 +508,8 @@ Example::: StateLoc: "D:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-pragma.cpp:3:18" State: 1 -`PragmaWarning <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#aa17169d25fa1cf0a6992fc944d1d8730>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`PragmaWarning <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#aa17169d25fa1cf0a6992fc944d1d8730>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PragmaWarning is called when a #pragma warning directive is read. @@ -530,8 +530,8 @@ Example::: WarningSpec: disable Ids: 1,2,3 -`PragmaWarningPush <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ae5626ef70502687a859f323a809ed0b6>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`PragmaWarningPush <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ae5626ef70502687a859f323a809ed0b6>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PragmaWarningPush is called when a #pragma warning(push) directive is read. @@ -550,8 +550,8 @@ Example::: Loc: "D:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-pragma.cpp:3:1" Level: 1 -`PragmaWarningPop <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ac98d502af8811b8a6e7342d7cd2b3b95>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`PragmaWarningPop <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ac98d502af8811b8a6e7342d7cd2b3b95>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PragmaWarningPop is called when a #pragma warning(pop) directive is read. @@ -568,8 +568,8 @@ Example::: - Callback: PragmaWarningPop Loc: "D:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-pragma.cpp:3:1" -`MacroExpands <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a9bc725209d3a071ea649144ab996d515>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`MacroExpands <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a9bc725209d3a071ea649144ab996d515>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ MacroExpands is called when ::HandleMacroExpandedIdentifier when a macro invocation is found. @@ -592,8 +592,8 @@ Example::: Range: [(nonfile), (nonfile)] Args: [a <plus> y, b] -`MacroDefined <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a8448fc9f96f22ad1b93ff393cffc5a76>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`MacroDefined <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a8448fc9f96f22ad1b93ff393cffc5a76>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ MacroDefined is called when a macro definition is seen. @@ -612,8 +612,8 @@ Example::: MacroNameTok: X_IMPL MacroDirective: MD_Define -`MacroUndefined <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#acb80fc6171a839db8e290945bf2c9d7a>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`MacroUndefined <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#acb80fc6171a839db8e290945bf2c9d7a>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ MacroUndefined is called when a macro #undef is seen. @@ -632,8 +632,8 @@ Example::: MacroNameTok: X_IMPL MacroDirective: MD_Define -`Defined <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a3cc2a644533d0e4088a13d2baf90db94>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`Defined <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a3cc2a644533d0e4088a13d2baf90db94>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Defined is called when the 'defined' operator is seen. @@ -654,8 +654,8 @@ Example::: MacroDirective: (null) Range: ["D:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-macro.cpp:8:5", "D:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-macro.cpp:8:19"] -`SourceRangeSkipped <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#abdb4ebe11610f079ac33515965794b46>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`SourceRangeSkipped <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#abdb4ebe11610f079ac33515965794b46>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ SourceRangeSkipped is called when a source range is skipped. @@ -672,8 +672,8 @@ Example::: - Callback: SourceRangeSkipped Range: [":/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-macro.cpp:8:2", ":/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-macro.cpp:9:2"] -`If <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a645edcb0d6becbc6f256f02fd1287778>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`If <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a645edcb0d6becbc6f256f02fd1287778>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If is called when an #if is seen. @@ -694,8 +694,8 @@ Example::: ConditionRange: ["D:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-macro.cpp:8:4", "D:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-macro.cpp:9:1"] ConditionValue: false -`Elif <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a180c9e106a28d60a6112e16b1bb8302a>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`Elif <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a180c9e106a28d60a6112e16b1bb8302a>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Elif is called when an #elif is seen. @@ -718,8 +718,8 @@ Example::: ConditionValue: false IfLoc: "D:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-macro.cpp:8:2" -`Ifdef <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a0ce79575dda307784fd51a6dd4eec33d>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`Ifdef <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a0ce79575dda307784fd51a6dd4eec33d>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Ifdef is called when an #ifdef is seen. @@ -740,8 +740,8 @@ Example::: MacroNameTok: MACRO MacroDirective: MD_Define -`Ifndef <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a767af69f1cdcc4cd880fa2ebf77ad3ad>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`Ifndef <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#a767af69f1cdcc4cd880fa2ebf77ad3ad>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Ifndef is called when an #ifndef is seen. @@ -762,8 +762,8 @@ Example::: MacroNameTok: MACRO MacroDirective: MD_Define -`Else <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ad57f91b6d9c3cbcca326a2bfb49e0314>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`Else <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#ad57f91b6d9c3cbcca326a2bfb49e0314>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Else is called when an #else is seen. @@ -782,8 +782,8 @@ Example::: Loc: "D:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-macro.cpp:10:2" IfLoc: "D:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-macro.cpp:8:2" -`Endif <http://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#afc62ca1401125f516d58b1629a2093ce>`_ Callback -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +`Endif <https://clang.llvm.org/doxygen/classclang_1_1PPCallbacks.html#afc62ca1401125f516d58b1629a2093ce>`_ Callback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Endif is called when an #endif is seen. @@ -819,7 +819,7 @@ To build from source: * If using CMake, you can also use the ``pp-trace`` target to build just the pp-trace tool and its dependencies. -.. _Getting Started with the LLVM System: http://llvm.org/docs/GettingStarted.html -.. _Building LLVM with CMake: http://llvm.org/docs/CMake.html -.. _Clang Tools Documentation: http://clang.llvm.org/docs/ClangTools.html +.. _Getting Started with the LLVM System: https://llvm.org/docs/GettingStarted.html +.. _Building LLVM with CMake: https://llvm.org/docs/CMake.html +.. _Clang Tools Documentation: https://clang.llvm.org/docs/ClangTools.html |
