cpp-linter · shenxianpeng · Jul 5, 2025 · Jul 5, 2025 · Jul 5, 2025 · Jul 5, 2025
diff --git a/.gitignore b/.gitignore
@@ -13,7 +13,7 @@ result.txt
 testing/main.c
 */*compile_commands.json
 
-# Ignore clang-tools binaries
+# Ignore Python wheel packages (clang-format, clang-tidy)
 clang-tidy-1*
 clang-tidy-2*
 clang-format-1*

diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml
@@ -4,12 +4,12 @@
   entry: clang-format-hook
   language: python
   files: \.(h\+\+|h|hh|hxx|hpp|c|cc|cpp|c\+\+|cxx)$
-  require_serial: true
+  require_serial: false
 
 - id: clang-tidy
   name: clang-tidy
   description: Automatically install any specific version of clang-tidy and diagnose/fix typical programming errors
   entry: clang-tidy-hook
   language: python
   files: \.(h\+\+|h|hh|hxx|hpp|c|cc|cpp|c\+\+|cxx)$
-  require_serial: true
+  require_serial: false
diff --git a/MIGRATION.md b/MIGRATION.md
@@ -0,0 +1,109 @@
+# Migration: From Clang Tools Binaries to Python Wheels
+
+## Overview
+
+Starting from version **v1.0.0**, `cpp-linter-hooks` has migrated from using the `clang-tools` package to using Python wheel packages for `clang-format` and `clang-tidy`. This change provides:
+
+- **Better cross-platform compatibility**
+- **Easier installation and dependency management**
+- **Improved performance and reliability**
+- **More predictable version management**
+
+## What Changed
+
+### Core Changes
+
+| Aspect | Before (< v1.0.0) | After (≥ v1.0.0) |
+|--------|-------------------|-------------------|
+| **Installation** | `clang-tools` package (binary management) | Python wheel packages (`clang-format`, `clang-tidy`) |
+| **Distribution** | Single package for both tools | Separate packages for each tool |
+| **Version Control** | Limited version flexibility | Enhanced version management with pip |
+| **Performance** | Standard performance | Optimized wheel packages |
+
+### Implementation Details
+
+- **Dependencies**: Updated to use separate `clang-format==20.1.7` and `clang-tidy==20.1.0` Python wheels
+- **Installation Logic**: Enhanced with pip-based installation and runtime version checks
+- **Performance**: Pre-commit hooks can now run in parallel for better speed
+
+## Breaking Changes
+
+### For End Users
+
+> **No breaking changes for end users**
+
+- Your existing `.pre-commit-config.yaml` files will continue to work without modification
+- All hook configurations remain backward compatible
+- No changes required to your workflow
+
+## Migration Steps
+
+### For End Users
+
+**No action required!** Your existing configuration will continue to work seamlessly.
+
+However, we recommend updating to the latest version for:
+- Better performance
+- Enhanced reliability
+- Latest features and bug fixes
+
+#### Example Configuration (No Changes Needed)
+
+```yaml
+repos:
+  - repo: https://github.com/cpp-linter/cpp-linter-hooks
+    rev: v1.0.0  # Use the latest version
+    hooks:
+      - id: clang-format
+        args: [--style=Google]
+      - id: clang-tidy
+        args: [--checks=-*,readability-*]
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Issue: Tool not found after migration
+**Solution**: Clear your pre-commit cache:
+```bash
+pre-commit clean
+pre-commit install
+```
+
+#### Issue: Version mismatch errors
+**Solution**: Ensure you're using the latest version of `cpp-linter-hooks`:
+```yaml
+rev: v1.0.0  # Update to latest version
+```
+
+## Support
+
+If you encounter issues after migration:
+
+1. **Check this guide**: Review the troubleshooting section above
+2. **Search existing issues**: [GitHub Issues](https://github.com/cpp-linter/cpp-linter-hooks/issues)
+3. **Report new issues**: Include the following information:
+   - Operating system and version
+   - Python version
+   - `cpp-linter-hooks` version
+   - Complete error message/stack trace
+   - Your `.pre-commit-config.yaml` configuration
+
+## References
+
+### Official Packages
+- [clang-format Python wheel](https://pypi.org/project/clang-format/) - PyPI package
+- [clang-tidy Python wheel](https://pypi.org/project/clang-tidy/) - PyPI package
+
+### Source Repositories
+- [clang-format wheel source](https://github.com/ssciwr/clang-format-wheel) - GitHub repository
+- [clang-tidy wheel source](https://github.com/ssciwr/clang-tidy-wheel) - GitHub repository
+
+### Documentation
+- [cpp-linter-hooks Documentation](https://github.com/cpp-linter/cpp-linter-hooks) - Main repository
+- [Pre-commit Framework](https://pre-commit.com/) - Pre-commit documentation
+
+---
+
+**Happy linting!**
diff --git a/README.md b/README.md
@@ -29,7 +29,7 @@ Add this configuration to your `.pre-commit-config.yaml` file:
 ```yaml
 repos:
   - repo: https://github.com/cpp-linter/cpp-linter-hooks
-    rev: v0.8.3  # Use the tag or commit you want
+    rev: v1.0.0  # Use the tag or commit you want
     hooks:
       - id: clang-format
         args: [--style=Google] # Other coding style: LLVM, GNU, Chromium, Microsoft, Mozilla, WebKit.
@@ -44,7 +44,7 @@ To use custom configurations like `.clang-format` and `.clang-tidy`:
 ```yaml
 repos:
   - repo: https://github.com/cpp-linter/cpp-linter-hooks
-    rev: v0.8.3
+    rev: v1.0.0
     hooks:
       - id: clang-format
         args: [--style=file]  # Loads style from .clang-format file
@@ -54,19 +54,22 @@ repos:
 
 ### Custom Clang Tool Version
 
-To use specific versions of [clang-tools](https://github.com/cpp-linter/clang-tools-pip?tab=readme-ov-file#supported-versions):
+To use specific versions of clang-format and clang-tidy (using Python wheel packages):
 
 ```yaml
 repos:
   - repo: https://github.com/cpp-linter/cpp-linter-hooks
-    rev: v0.8.3
+    rev: v1.0.0
     hooks:
       - id: clang-format
         args: [--style=file, --version=18] # Specifies version
       - id: clang-tidy
         args: [--checks=.clang-tidy, --version=18] # Specifies version
 ```
 
+> [!NOTE]
+> Starting from version v1.0.0, this package uses Python wheel packages ([clang-format](https://pypi.org/project/clang-format/) and [clang-tidy](https://pypi.org/project/clang-tidy/)) instead of the previous clang-tools binaries. The wheel packages provide better cross-platform compatibility and easier installation. For more details, see the [Migration Guide](MIGRATION.md).
+
 ## Output
 
 ### clang-format Output
@@ -141,12 +144,12 @@ Use -header-filter=.* to display errors from all non-system headers. Use -system
 
 ### Performance Optimization
 
-> [!WARNING]
+> [!TIP]
 > If your `pre-commit` runs longer than expected, it is highly recommended to add `files` in `.pre-commit-config.yaml` to limit the scope of the hook. This helps improve performance by reducing the number of files being checked and avoids unnecessary processing. Here's an example configuration:
 
 ```yaml
 - repo: https://github.com/cpp-linter/cpp-linter-hooks
-  rev: v0.8.3
+  rev: v1.0.0
   hooks:
     - id: clang-format
       args: [--style=file, --version=18]
@@ -172,7 +175,7 @@ This approach ensures that only modified files are checked, further speeding up
 ```yaml
 repos:
   - repo: https://github.com/cpp-linter/cpp-linter-hooks
-    rev: v0.8.3
+    rev: v1.0.0
     hooks:
       - id: clang-format
         args: [--style=file, --version=18, --verbose]   # Add -v or --verbose for detailed output

diff --git a/cpp_linter_hooks/clang_format.py b/cpp_linter_hooks/clang_format.py
@@ -3,20 +3,20 @@
 from argparse import ArgumentParser
 from typing import Tuple
 
-from .util import ensure_installed, DEFAULT_CLANG_VERSION
+from .util import ensure_installed, DEFAULT_CLANG_FORMAT_VERSION
 
 
 parser = ArgumentParser()
-parser.add_argument("--version", default=DEFAULT_CLANG_VERSION)
+parser.add_argument("--version", default=DEFAULT_CLANG_FORMAT_VERSION)
 parser.add_argument(
     "-v", "--verbose", action="store_true", help="Enable verbose output"
 )
 
 
 def run_clang_format(args=None) -> Tuple[int, str]:
     hook_args, other_args = parser.parse_known_args(args)
-    path = ensure_installed("clang-format", hook_args.version)
-    command = [str(path), "-i"]
+    tool_name = ensure_installed("clang-format", hook_args.version)
+    command = [tool_name, "-i"]
 
     # Add verbose flag if requested
     if hook_args.verbose:

diff --git a/cpp_linter_hooks/clang_tidy.py b/cpp_linter_hooks/clang_tidy.py
@@ -2,17 +2,17 @@
 from argparse import ArgumentParser
 from typing import Tuple
 
-from .util import ensure_installed, DEFAULT_CLANG_VERSION
+from .util import ensure_installed, DEFAULT_CLANG_TIDY_VERSION
 
 
 parser = ArgumentParser()
-parser.add_argument("--version", default=DEFAULT_CLANG_VERSION)
+parser.add_argument("--version", default=DEFAULT_CLANG_TIDY_VERSION)
 
 
 def run_clang_tidy(args=None) -> Tuple[int, str]:
     hook_args, other_args = parser.parse_known_args(args)
-    path = ensure_installed("clang-tidy", hook_args.version)
-    command = [str(path)]
+    tool_name = ensure_installed("clang-tidy", hook_args.version)
+    command = [tool_name]
     command.extend(other_args)
 
     retval = 0