Implementation:ClickHouse ClickHouse Find Unused Headers
| Knowledge Sources | |
|---|---|
| Domains | Build_System, Utilities |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
A Python tool that identifies and verifies unused C++ header includes in ClickHouse source files using compilation verification.
Description
This utility combines `clang-include-cleaner` analysis with actual compilation testing to find headers that can be safely removed from C++ source files. Unlike simple static analysis tools, it verifies each header removal by attempting compilation, ensuring that only truly unused headers are reported. The tool supports both single-file analysis and batch processing of entire directories with parallel execution.
The implementation reads `compile_commands.json` to obtain exact compilation flags, uses `clang-include-cleaner` to identify candidate headers, and then performs syntax-only compilation tests on temporary files with each header removed to verify safety.
Usage
Use this tool when you need to:
- Clean up unnecessary includes in C++ source files
- Reduce compilation dependencies and build times
- Maintain clean code hygiene in large codebases
- Verify that header removals are safe before applying them
Code Reference
Source Location
- Repository: ClickHouse
- File: utils/find_unused_headers.py
- Lines: 1-316
Signature
def get_compile_command(source_file: str, build_dir: str) -> Optional[dict]
def get_unused_includes(source_file: str, build_dir: str) -> List[Tuple[str, int]]
def test_compilation(source_file: str, compile_cmd: dict) -> bool
def find_safe_removals(source_file: str, build_dir: str, verbose: bool = False) -> List[Tuple[str, int]]
def find_quick_removals(source_file: str, build_dir: str, verbose: bool = False) -> List[Tuple[str, int]]
def apply_removals(source_file: str, removals: List[Tuple[str, int]]) -> None
Import
#!/usr/bin/env python3
./find_unused_headers.py <source_file.cpp> [--build-dir BUILD_DIR] [--apply]
./find_unused_headers.py --batch <directory> [--build-dir BUILD_DIR] [--jobs N]
I/O Contract
| Input | Type | Description |
|---|---|---|
| source_file | str | Path to C++ source file to analyze |
| build_dir | str | Path to build directory containing compile_commands.json |
| verbose | bool | Enable verbose output |
| quick | bool | Skip compilation verification (faster but less accurate) |
| Output | Type | Description |
|---|---|---|
| removals | List[Tuple[str, int]] | List of (header_name, line_number) tuples for safely removable headers |
Usage Examples
# Analyze single file
./find_unused_headers.py src/Storages/MergeTree/MergeTreeData.cpp --build-dir build
# Analyze single file with verbose output
./find_unused_headers.py src/Core/Block.cpp --build-dir build --verbose
# Analyze and apply removals
./find_unused_headers.py src/Functions/array/arrayElement.cpp --build-dir build --apply
# Batch process directory with parallel jobs
./find_unused_headers.py --batch src/Functions --build-dir build --jobs 8
# Quick mode without compilation verification
./find_unused_headers.py src/Interpreters/Context.cpp --build-dir build --quick
# Save results to file
./find_unused_headers.py --batch src --build-dir build --output unused_headers.txt