clangd-kernel-helper

English | 中文

A tool to automatically generate compile_commands.json for Linux kernel driver development, enabling full code intelligence support with clangd.

✨ Features

• 🔍 Auto-extract CONFIG_ macros*: Extract all kernel configuration macros (947+) from autoconf.h
• 📁 Smart file scanning: Automatically scan all compiled .c files in the kernel
• 🔄 Auto-generate compile commands: Generate from .cmd files if kernel doesn't have compile_commands.json
• 🛠️ Path fixing: Ensure clangd can correctly parse relative/absolute paths
• 🔗 Merge driver and kernel: Support generating compilation database for both driver code and kernel source

🎯 Code Intelligence Features

After generating compile_commands.json with this tool, clangd provides:

• ✅ Code Completion: Auto-suggest functions, struct members, etc.
• 🚀 Go to Definition (F12): Jump to function/variable definitions
• 🔎 Find References: See where symbols are used
• 📖 Hover Documentation: Show function prototypes and comments on hover
• ⚠️ Syntax Checking: Real-time code error diagnostics

📦 Installation

1. Install clangd Extension

In VSCode or Cursor:

1. Press Ctrl+Shift+X to open Extensions
2. Search for "clangd"
3. Install the "clangd" extension by LLVM
4. Restart your editor

Note: If you have Microsoft C/C++ extension installed, consider disabling it to avoid conflicts.

2. Install clangd Server

Ubuntu/Debian

sudo apt update
sudo apt install clangd
# Or install a specific version (clangd-15 or higher recommended)
sudo apt install clangd-15
sudo update-alternatives --install /usr/bin/clangd clangd /usr/bin/clangd-15 100

Fedora/RHEL

sudo dnf install clang-tools-extra

Arch Linux

sudo pacman -S clang

macOS (Homebrew)

brew install llvm
# Add to PATH
export PATH="/usr/local/opt/llvm/bin:$PATH"

Verify installation:

clangd --version

3. Configure clangd

Create a .clangd file in your project root:

CompileFlags:
  Add:
    # Ignore some GCC-specific warnings (not supported by clang)
    - "-Wno-unknown-warning-option"
    - "-Wno-unused-command-line-argument"
  Remove:
    # Remove GCC-specific options not supported by clang
    - "-mno-thumb-interwork"
    - "-fno-allow-store-data-races"
    - "-fconserve-stack"
    - "-mno-sched-prolog"
    - "-mapcs"
    - "-mabi=*"

Diagnostics:
  # Suppress less important warnings
  Suppress:
    - "pp_including_mainfile_in_preamble"
    - "-Wunused-variable"

InlayHints:
  # Enable inline hints (show parameter names, types, etc.)
  Enabled: true
  ParameterNames: true
  DeducedTypes: true

Hover:
  ShowAKA: true  # Show actual typedef types

4. VSCode/Cursor Settings (Optional)

Press Ctrl+Shift+P, type "Preferences: Open Settings (JSON)", and add:

{
  // clangd configuration
  "clangd.path": "/usr/bin/clangd",
  "clangd.arguments": [
    "--background-index",
    "--clang-tidy",
    "--completion-style=detailed",
    "--header-insertion=iwyu",
    "-j=4",
    "--pch-storage=memory"
  ],
  "clangd.fallbackFlags": [
    "-std=gnu11"
  ],

  // Disable Microsoft C/C++ IntelliSense (avoid conflicts)
  "C_Cpp.intelliSenseEngine": "disabled",

  // File associations
  "files.associations": {
    "*.h": "c",
    "Kconfig*": "kconfig",
    "Makefile*": "makefile"
  }
}

🚀 Usage

Prerequisites

⚠️ The kernel must be compiled first to generate compile_commands.json (requires .cmd files and autoconf.h)

ARM Architecture Kernel Build Example

cd /path/to/kernel

# Set cross-compilation environment
export ARCH=arm
export CROSS_COMPILE=arm-none-linux-gnueabi-

# Generate default config
make defconfig
# Or use vendor config: make xxx_defconfig
# Or manual config: make menuconfig

# Build kernel (generates .cmd files and autoconf.h)
make -j$(nproc)

ARM64 Architecture

export ARCH=arm64
export CROSS_COMPILE=aarch64-linux-gnu-
make defconfig && make -j$(nproc)

x86_64 Native

make defconfig && make -j$(nproc)

Basic Usage

# Generate for driver source only (fastest, recommended for daily use)
./clangd-kernel-helper

# Include kernel source (supports F12 jump to kernel function definitions)
./clangd-kernel-helper --with-kernel

# Force regenerate kernel's compile_commands.json
./clangd-kernel-helper --with-kernel --regenerate-kernel

# Use a different kernel directory
./clangd-kernel-helper --kernel-dir ~/linux-5.10 --with-kernel

# Specify cross-compiler and architecture
./clangd-kernel-helper --arch arm64 --cross-compile aarch64-linux-gnu-

# Show help
./clangd-kernel-helper --help

Command Line Options

Option	Description
--with-kernel	Include kernel source compilation commands (supports jump to kernel implementation)
--regenerate-kernel	Force regenerate kernel's compile_commands.json
--kernel-dir	Specify kernel source directory (default: /home/sky/linux-4.14.139)
--cross-compile	Cross-compiler prefix (default: arm-none-linux-gnueabi-)
--arch	Target architecture (default: arm)

📝 Examples

Example 1: Working with Custom Kernel

# After pulling a new kernel, just specify the path
./clangd-kernel-helper --kernel-dir ~/linux-5.15 --with-kernel

Example 2: ARM64 Development

./clangd-kernel-helper \
  --arch arm64 \
  --cross-compile aarch64-linux-gnu- \
  --with-kernel

Example 3: Update After Kernel Recompile

# Force regenerate after kernel config changes
./clangd-kernel-helper --with-kernel --regenerate-kernel

❓ FAQ

Q: clangd can't find header files?

• Ensure compile_commands.json is generated
• Check if paths in compile_commands.json are correct
• Restart clangd: Ctrl+Shift+P → "clangd: Restart language server"

Q: Lots of syntax errors?

• Create .clangd file to remove clang-unsupported GCC options
• Check if kernel is compiled (needs autoconf.h)

Q: F12 doesn't jump to kernel function definitions?

• Use --with-kernel option to regenerate
• Ensure kernel is compiled

Q: Indexing is slow?

• clangd builds index on first project open, please be patient
• Check indexing progress in VSCode status bar
• Index is cached after completion, subsequent opens will be fast

Q: Completion is inaccurate?

• Ensure CONFIG_* macros are correctly extracted (check script output)
• May need to run --regenerate-kernel to regenerate

🔧 How It Works

1. Extract config macros: Extract all CONFIG_* macro definitions from autoconf.h
2. Scan source files: Traverse driver and kernel directories to find all .c files
3. Generate compile commands: Generate compilation commands with correct header paths and macro definitions for each source file
4. Fix paths: Convert relative paths to absolute paths to ensure clangd can parse correctly
5. Merge output: Merge driver and kernel compilation commands into one compile_commands.json file

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Ways to Contribute

• 🐛 Report bugs and issues
• 💡 Suggest new features
• 📖 Improve documentation
• 🔧 Submit pull requests
• 🌍 Add translations for other languages
• ⭐ Star this project to help more people discover it

📄 License

GPL-2.0 - See LICENSE file for details.

This project follows the same license as the Linux kernel to ensure compatibility.

🔗 Related Links

• clangd Official Website
• compile_commands.json Format Specification
• Linux Kernel Build Guide

🌟 Star History

If this project helps you, please consider giving it a star ⭐ to help more developers discover it!

---

Made with ❤️ for kernel developers worldwide