clang-tools-extra

clang-tools-extra/ is a sibling of clang/ that hosts higher-level developer tooling built on Clang's libraries. The split exists for historical reasons — to allow lighter-weight checkouts of Clang itself — and is preserved today as the standard location for new Clang-based tools.

Purpose

If a tool consumes Clang as a library (for parsing, analysis, formatting, refactoring, indexing) and isn't part of the compilation pipeline itself, it goes here. The biggest user-facing examples are clangd (the LSP server), clang-tidy (the linter), and clang-format (the formatter, whose engine actually lives in clang/lib/Format/ but whose driver lives here).

Directory layout

clang-tools-extra/
├── clangd/             # The LSP language server
├── clang-tidy/         # The linter; checks live in subdirectories per category
├── clang-doc/          # Documentation generator
├── clang-include-fixer/
├── clang-move/
├── clang-query/        # Interactive AST-matcher REPL
├── clang-reorder-fields/
├── clang-change-namespace/
├── modularize/         # Module-conversion helper
├── pseudo/             # Heuristic ("pseudo") C++ parser used in clangd
├── include-cleaner/    # IWYU-style header analyzer
├── tool-template/      # Skeleton for a new Clang tool
├── unittests/
├── test/               # lit regression tests
├── docs/
└── README.txt

Key tools

clangd

clang-tools-extra/clangd/ is a Language Server Protocol implementation for C, C++, Objective-C, and CUDA. It powers VS Code's C/C++ extension (when configured), Vim/Neovim LSP plugins, Emacs, etc. It uses Clang's libraries to parse projects, build an in-memory index, surface diagnostics, hover, completions, find references, rename, format, code actions, and inlay hints.

Sub-areas:

• clangd/index/ — file-based and memory-based symbol indices
• clangd/refactor/ — code-action and tweak implementations
• clangd/Hover.cpp, clangd/CodeComplete.cpp, clangd/SemanticHighlighting.cpp, etc.
• clangd/tool/ — the clangd executable
• clangd-indexer/ — offline indexer

clang-tidy

clang-tools-extra/clang-tidy/ is the linter framework. Each check is a class deriving from clang::tidy::ClangTidyCheck (clang-tools-extra/clang-tidy/ClangTidyCheck.h) that registers AST matchers and emits diagnostics. Checks are grouped into modules: bugprone, cert, cppcoreguidelines, google, hicpp, llvm, misc, modernize, performance, portability, readability, concurrency, darwin, mpi, objc, openmp, zircon, etc. Each module is its own subdirectory.

clang-doc

clang-tools-extra/clang-doc/ is a documentation generator that consumes Clang ASTs and produces HTML/Markdown/YAML output. It is younger than the other tools and still maturing.

clang-include-fixer

clang-tools-extra/clang-include-fixer/ suggests #include directives for unresolved symbols, using a pre-built symbol database.

include-cleaner

clang-tools-extra/include-cleaner/ is a "what headers do I actually use" analyzer in the spirit of include-what-you-use. It is also embedded in clangd as a code-action provider.

pseudo

clang-tools-extra/pseudo/ is an experimental heuristic C++ parser that can build approximate ASTs without a full Clang invocation. Used inside clangd for partial-results scenarios where running the real parser is too slow or impossible.

tool-template

clang-tools-extra/tool-template/ is the canonical skeleton for adding a new Clang tool. Copy it, rename, and start filling in your FrontendAction.

Integration points

• All tools link against Clang's libraries: libClangTooling, libClangFormat, libClangAST, libClangIndex, libClangSema.
• clangd embeds the same parsing path as clang -cc1 — bug fixes in Clang's parser frequently fix clangd issues at the same time.
• clang-tidy checks emit diagnostics through Clang's DiagnosticEngine, so they participate in -Werror, -Wno-..., and IDE diagnostic display.

Entry points for modification

• Adding a clang-tidy check: copy an existing check (any small one in bugprone/ or readability/ is a good template), add Register glue in the module's *.cpp, document it under clang-tools-extra/docs/clang-tidy/checks/, and add a RUN: lit test under clang-tools-extra/test/clang-tidy/checkers/.
• Adding a clangd code action: implement a Tweak (clang-tools-extra/clangd/refactor/) — a class deriving from Tweak that returns an LSP WorkspaceEdit when applicable.
• Adding a new tool: copy tool-template/, register it in the parent CMakeLists.txt, and link the Clang libraries you need.

Reference

• Extra Clang Tools documentation
• clangd documentation
• clang-tidy documentation
• clang-tools-extra README