clangd-tidy 1.0.0

A faster alternative to clang-tidy

clangd-tidy: A Faster Alternative to clang-tidy

Motivation

clang-tidy is a powerful tool for static analysis of C++ code. However, it's widely acknowledged that clang-tidy takes a significant amount of time to run on large codebases, particularly when enabling numerous checks. This often leads to the dilemma of disabling valuable checks to expedite clang-tidy execution.

In contrast, clangd, the language server with built-in support for clang-tidy, has been observed to be significantly faster than clang-tidy when running the same checks. It provides diagnostics almost instantly upon opening a file in your editor. The key distinction lies in the fact that clang-tidy checks the codes from all headers (although it suppresses the warnings from them by default), whereas clangd only builds AST from these headers.

Unfortunately, there seems to be no plan within LLVM to accelerate the standalone version of clang-tidy. This project addresses this by offering a faster alternative to clang-tidy, leveraging the speed of clangd. It acts as a wrapper for clangd, running it in the background and collecting diagnostics. Designed as a drop-in replacement for clang-tidy, it seamlessly integrates with existing build systems and CI scripts.

Comparison with clang-tidy

Pros:

• clangd-tidy is significantly faster than clang-tidy (over 10x in my experience).
• clangd-tidy can check header files individually, even if they are not included in the compilation database.
• clangd-tidy groups diagnostics by files -- no more duplicated diagnostics from the same header!
• clangd-tidy supports .clangd configuration files, offering features not supported by clang-tidy.
  • Example: Removing unknown compiler flags from the compilation database.

    CompileFlags:
      Remove: -fabi*
    

  • Example: Adding IWYU include checks.

    Diagnostics:
      # Available in clangd-14
      UnusedIncludes: Strict
      # Require clangd-17
      MissingIncludes: Strict
    

• Refer to Usage for more features.

Cons:

• clangd-tidy lacks support for the --fix option. (Consider using code actions provided by your editor if you have clangd properly configured, as clangd-tidy is primarily designed for speeding up CI checks.)
• clangd-tidy silently disables several checks not supported by clangd.
• Diagnostics generated by clangd-tidy might be marginally less aesthetically pleasing compared to clang-tidy.

Prerequisites

• clangd
• Python 3.8+ (may work on older versions, but not tested)
• tqdm (optional)

Installation

pip install clangd-tidy

Usage

usage: clangd-tidy [-h] [-p COMPILE_COMMANDS_DIR] [-j JOBS] [-o OUTPUT]
                   [--clangd-executable CLANGD_EXECUTABLE]
                   [--allow-extensions ALLOW_EXTENSIONS]
                   [--fail-on-severity SEVERITY] [--tqdm] [--github]
                   [--git-root GIT_ROOT] [-c] [--context CONTEXT]
                   [--color {auto,always,never}] [-v]
                   filename [filename ...]

Run clangd with clang-tidy and output diagnostics. This aims to serve as a
faster alternative to clang-tidy.

positional arguments:
  filename              Files to check. Files whose extensions are not in
                        ALLOW_EXTENSIONS will be ignored.

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -p COMPILE_COMMANDS_DIR, --compile-commands-dir COMPILE_COMMANDS_DIR
                        Specify a path to look for compile_commands.json. If
                        the path is invalid, clangd will look in the current
                        directory and parent paths of each source file.
                        [default: build]
  -j JOBS, --jobs JOBS  Number of async workers used by clangd. Background
                        index also uses this many workers. [default: 1]
  -o OUTPUT, --output OUTPUT
                        Output file for diagnostics. [default: stdout]
  --clangd-executable CLANGD_EXECUTABLE
                        Path to clangd executable. [default: clangd]
  --allow-extensions ALLOW_EXTENSIONS
                        A comma-separated list of file extensions to allow.
                        [default: c,h,cpp,cc,cxx,hpp,hh,hxx,cu,cuh]
  --fail-on-severity SEVERITY
                        On which severity of diagnostics this program should
                        exit with a non-zero status. Candidates: error, warn,
                        info, hint. [default: hint]
  --tqdm                Show a progress bar (tqdm required).
  --github              Append workflow commands for GitHub Actions to output.
  --git-root GIT_ROOT   Root directory of the git repository. Only works with
                        --github. [default: current directory]
  -c, --compact         Print compact diagnostics (legacy).
  --context CONTEXT     Number of additional lines to display on both sides of
                        each diagnostic. This option is ineffective with
                        --compact. [default: 2]
  --color {auto,always,never}
                        Colorize the output. This option is ineffective with
                        --compact. [default: auto]
  -v, --verbose         Show verbose output from clangd.

Find more information on https://github.com/lljbash/clangd-tidy.

Acknowledgement

Special thanks to @yeger00 for his pylspclient.

A big shoutout to clangd and clang-tidy for their great work!

Claps to @ArchieAtkinson for his artistic flair in the fancy diagnostic formatter.

Contributions are welcome! Feel free to open an issue or a pull request.