LLVM Tooling Skill

This skill covers development of tools using LLVM/Clang infrastructure for source code analysis, debugging, and IDE integration.

Clang Plugin Development

Plugin Architecture

Clang plugins are dynamically loaded libraries that extend Clang's functionality during compilation.

cpp
1#include "clang/Frontend/FrontendPluginRegistry.h"
2#include "clang/AST/ASTConsumer.h"
3#include "clang/AST/RecursiveASTVisitor.h"
4
5class MyVisitor : public clang::RecursiveASTVisitor<MyVisitor> {
6public:
7    bool VisitFunctionDecl(clang::FunctionDecl *FD) {
8        llvm::outs() << "Found function: " << FD->getName() << "\n";
9        return true;
10    }
11};
12
13class MyConsumer : public clang::ASTConsumer {
14    MyVisitor Visitor;
15public:
16    void HandleTranslationUnit(clang::ASTContext &Context) override {
17        Visitor.TraverseDecl(Context.getTranslationUnitDecl());
18    }
19};
20
21class MyPlugin : public clang::PluginASTAction {
22protected:
23    std::unique_ptr<clang::ASTConsumer> CreateASTConsumer(
24        clang::CompilerInstance &CI, llvm::StringRef) override {
25        return std::make_unique<MyConsumer>();
26    }
27    
28    bool ParseArgs(const clang::CompilerInstance &CI,
29                   const std::vector<std::string> &args) override {
30        return true;
31    }
32};
33
34static clang::FrontendPluginRegistry::Add<MyPlugin>
35    X("my-plugin", "My custom plugin description");

Running Clang Plugins

bash
1# Build plugin
2clang++ -shared -fPIC -o MyPlugin.so MyPlugin.cpp \
3    $(llvm-config --cxxflags --ldflags)
4
5# Run plugin
6clang -Xclang -load -Xclang ./MyPlugin.so \
7      -Xclang -plugin -Xclang my-plugin \
8      source.cpp

LibTooling

Standalone Tools

cpp
1#include "clang/Tooling/CommonOptionsParser.h"
2#include "clang/Tooling/Tooling.h"
3#include "clang/ASTMatchers/ASTMatchFinder.h"
4
5using namespace clang::tooling;
6using namespace clang::ast_matchers;
7
8// Define matcher
9auto functionMatcher = functionDecl(hasName("targetFunction")).bind("func");
10
11// Callback handler
12class FunctionCallback : public MatchFinder::MatchCallback {
13public:
14    void run(const MatchFinder::MatchResult &Result) override {
15        if (auto *FD = Result.Nodes.getNodeAs<FunctionDecl>("func")) {
16            llvm::outs() << "Found: " << FD->getQualifiedNameAsString() << "\n";
17        }
18    }
19};
20
21int main(int argc, const char **argv) {
22    auto ExpectedParser = CommonOptionsParser::create(argc, argv, MyCategory);
23    ClangTool Tool(ExpectedParser->getCompilations(),
24                   ExpectedParser->getSourcePathList());
25    
26    FunctionCallback Callback;
27    MatchFinder Finder;
28    Finder.addMatcher(functionMatcher, &Callback);
29    
30    return Tool.run(newFrontendActionFactory(&Finder).get());
31}

AST Matchers Reference

cpp
1// Declaration matchers
2functionDecl()           // Match function declarations
3varDecl()               // Match variable declarations
4recordDecl()            // Match struct/class/union
5fieldDecl()             // Match class fields
6cxxMethodDecl()         // Match C++ methods
7cxxConstructorDecl()    // Match constructors
8
9// Expression matchers
10callExpr()              // Match function calls
11binaryOperator()        // Match binary operators
12unaryOperator()         // Match unary operators
13memberExpr()            // Match member access
14
15// Narrowing matchers
16hasName("name")         // Filter by name
17hasType(asString("int")) // Filter by type
18isPublic()              // Filter by access specifier
19hasAnyParameter(...)    // Match parameters
20
21// Traversal matchers
22hasDescendant(...)      // Match anywhere in subtree
23hasAncestor(...)        // Match in parent chain
24has(...)                // Match direct children
25forEach(...)            // Match all children

LLDB Extension Development

Python Commands

python
1import lldb
2
3def my_command(debugger, command, result, internal_dict):
4    """Custom LLDB command implementation"""
5    target = debugger.GetSelectedTarget()
6    process = target.GetProcess()
7    thread = process.GetSelectedThread()
8    frame = thread.GetSelectedFrame()
9    
10    # Get variable value
11    var = frame.FindVariable("my_var")
12    result.AppendMessage(f"my_var = {var.GetValue()}")
13
14def __lldb_init_module(debugger, internal_dict):
15    debugger.HandleCommand(
16        'command script add -f my_module.my_command my_cmd')

Scripted Process

python
1class MyScriptedProcess(lldb.SBScriptedProcess):
2    def __init__(self, target, args):
3        super().__init__(target, args)
4        
5    def get_thread_with_id(self, tid):
6        # Return thread info
7        pass
8    
9    def get_registers_for_thread(self, tid):
10        # Return register context
11        pass
12    
13    def read_memory_at_address(self, addr, size):
14        # Read memory
15        pass

LLDB GUI Extensions

• visual-lldb: GUI frontend for LLDB
• vegvisir: Browser-based LLDB GUI
• lldbg: Lightweight native GUI
• CodeLLDB: VSCode debugger extension

Clangd / Language Server Protocol

Custom LSP Extensions

cpp
1// Implementing custom code actions
2class MyCodeActionProvider {
3public:
4    std::vector<CodeAction> getCodeActions(
5        const TextDocumentIdentifier &File,
6        const Range &Range,
7        const CodeActionContext &Context) {
8        
9        std::vector<CodeAction> Actions;
10        
11        // Add custom refactoring action
12        CodeAction Action;
13        Action.title = "Extract to function";
14        Action.kind = "refactor.extract";
15        
16        // Define workspace edits
17        WorkspaceEdit Edit;
18        // ... populate edits
19        Action.edit = Edit;
20        
21        Actions.push_back(Action);
22        return Actions;
23    }
24};

Clangd Configuration

yaml
1# .clangd configuration file
2CompileFlags:
3  Add: [-xc++, -std=c++17]
4  Remove: [-W*]
5
6Diagnostics:
7  ClangTidy:
8    Add: [modernize-*, performance-*]
9    Remove: [modernize-use-trailing-return-type]
10
11Index:
12  Background: Build

Source-to-Source Transformation

Clang Rewriter

cpp
1#include "clang/Rewrite/Core/Rewriter.h"
2
3class MyRewriter : public RecursiveASTVisitor<MyRewriter> {
4    Rewriter &R;
5    
6public:
7    MyRewriter(Rewriter &R) : R(R) {}
8    
9    bool VisitFunctionDecl(FunctionDecl *FD) {
10        // Add comment before function
11        R.InsertTextBefore(FD->getBeginLoc(), "// Auto-generated\n");
12        
13        // Replace function name
14        R.ReplaceText(FD->getLocation(), 
15                      FD->getName().size(), "new_name");
16        
17        return true;
18    }
19};

RefactoringTool

cpp
1#include "clang/Tooling/Refactoring.h"
2
3class MyRefactoring : public RefactoringCallback {
4public:
5    void run(const MatchFinder::MatchResult &Result) override {
6        // Generate replacements
7        Replacement Rep(
8            *Result.SourceManager,
9            CharSourceRange::getTokenRange(Range),
10            "new_text");
11        
12        Replacements.insert(Rep);
13    }
14};

Notable Tools Built with LLVM Tooling

Analysis Tools

• cppinsights: C++ template instantiation visualization
• ClangBuildAnalyzer: Build time analysis
• clazy: Qt-specific static analysis

Refactoring Tools

• clang-rename: Symbol renaming
• clang-tidy: Linting and auto-fixes
• include-what-you-use: Include optimization

Code Generation

• classgen: Extract type info for IDA
• constexpr-everything: Auto-apply constexpr
• clang-expand: Inline function expansion

Best Practices

1. Use AST Matchers: More readable than manual traversal
2. Preserve Formatting: Use Rewriter carefully to maintain style
3. Handle Macros: Be aware of macro expansion locations
4. Test Thoroughly: Edge cases in C++ are numerous
5. Provide Good Diagnostics: Clear error messages improve usability

Resources

See Clang Plugins, Clangd/Language Server, and LLDB sections in README.md for comprehensive tool listings.

Getting Detailed Information

When you need detailed and up-to-date resource links, tool lists, or project references, fetch the latest data from:

https://raw.githubusercontent.com/gmh5225/awesome-llvm-security/refs/heads/main/README.md

This README contains comprehensive curated lists of:

• Clang plugins and extensions (Clang Plugins section)
• Language server implementations (Clangd/Language Server section)
• LLDB debugger tools and GUIs (LLDB section)
• Static analysis and refactoring tools