Migration: From Clang Tools Binaries to Python Wheels (#87)

* Migrate from clang-tools binaries to wheels

* allow run in parallel and pin clang-tools version

* update run.sh

* fix utils.py tests and others

* fix: add missing package

* revert mian.c change

* docs: update docs

* add @pytest.mark.benchmark to test

* pre-commit autoupdate

* update docs

* increase test coverage

Author: shenxianpeng

.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*

.pre-commit-config.yaml

@@ -14,7 +14,7 @@ repos:
     hooks:
       - id: pyupgrade
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.12.1
+    rev: v0.12.2
     hooks:
       - id: ruff
       - id: ruff-format

.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

MIGRATION.md

@@ -0,0 +1,73 @@
+# 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**
+
+## What Changed
+
+### Core Changes
+
+| Aspect | Before (< v1.0.0) | After (≥ v1.0.0) |
+|--------|-------------------|-------------------|
+| **Installation** | Install from GitHub release | Install with from PyPI |
+| **Distribution** | Binary packages | Python wheel packages |
+| **Performance** | Run serially | Run in parallel |
+
+### 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
+
+**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
+
+**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
+
+## 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!**

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

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:

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