Clang-tidy

Common errors

• clang-tidy: command not found

  cause The `clang-tidy` executable is not in your system's PATH, or the pip installation failed to link it correctly.
  fix Ensure `pip install clang-tidy` completed successfully. If using a virtual environment, ensure it's activated. Alternatively, invoke the tool using `python -m clang_tidy` which directly calls the installed Python module.

• Error: no input files

  cause You ran `clang-tidy` without specifying any C++ source files to analyze.
  fix Provide one or more C++ source files as arguments (e.g., `clang-tidy my_file.cpp`). For a whole project, use a compilation database and target files: `clang-tidy path/to/source.cpp -p path/to/build_dir`.

• No compilation database found in directory [directory path]

  cause Clang-tidy requires a `compile_commands.json` file to understand how to build and analyze your C++ project, and it couldn't find one in the current directory or the specified path.
  fix Generate `compile_commands.json` using your build system (e.g., CMake, Meson, etc.). Place it in your project's build directory or root, and then call `clang-tidy -p <path_to_directory_containing_compile_commands.json>`.

Warnings

• gotcha The `clang-tidy` Python package primarily serves as a wrapper to distribute the `clang-tidy` executable. It does NOT provide a direct Python API for programmatic analysis. If you expect to import `clang_tidy` and call functions, this package is not for that purpose.
  Fix: Interact with `clang-tidy` via `subprocess` calls or `python -m clang_tidy` as you would with any command-line tool. If you need a Python API for C++ tooling, consider `libclang` or other specialized libraries.
• gotcha The package version (e.g., `22.1.0.1`) reflects the underlying LLVM/Clang version it ships, not a distinct Python package versioning scheme. The first three digits (e.g., `22.1.0`) directly correspond to the bundled `clang-tidy` tool's version. This can be confusing if you expect standard Python semantic versioning.
  Fix: Always check the `clang-tidy --version` output to confirm the exact tool version being used, especially when debugging behavior or expecting features from a specific LLVM release.
• gotcha For `clang-tidy` to perform meaningful code analysis on C++ projects, it typically requires a compilation database (a `compile_commands.json` file) in the project root or specified via the `-p` flag. This file lists compilation commands for each source file, allowing `clang-tidy` to correctly resolve headers and build settings.
  Fix: Generate `compile_commands.json` using your build system (e.g., `cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ..` for CMake, or `bear -- make` for Make-based projects). Place it in your project root or pass its parent directory using `clang-tidy -p <path_to_build_dir>`.

Install

• pip install clang-tidy Install latest version

Imports

• No direct Python API

  import subprocess
  # Or use: python -m clang_tidy

  This library primarily provides the `clang-tidy` executable. It does not expose a Python API for programmatic access to clang-tidy's analysis functionality within Python code. Usage is via `subprocess` or by executing it as a Python module.

Quickstart

This quickstart demonstrates how to execute the `clang-tidy` command-line tool after installing the Python package. Since there's no direct Python API, you interact with `clang-tidy` using `subprocess` or by running it as a Python module. A common use case is to check its version or to run analysis on C++ code, which usually requires a `compile_commands.json` file generated by a build system like CMake.

import subprocess
import os

def run_clang_tidy(args):
    try:
        # Option 1: Using subprocess directly with the executable
        # Requires 'clang-tidy' to be in PATH or specified with full path
        # For this package, 'clang-tidy' should be in PATH after install
        result = subprocess.run(['clang-tidy'] + args, capture_output=True, text=True, check=True)
        print(f"Stdout:\n{result.stdout}")
        if result.stderr:
            print(f"Stderr:\n{result.stderr}")
        return result.returncode
    except FileNotFoundError:
        print("Error: 'clang-tidy' command not found. Ensure the package is installed and accessible.")
        return 1
    except subprocess.CalledProcessError as e:
        print(f"Error running clang-tidy: {e.returncode}")
        print(f"Stdout:\n{e.stdout}")
        print(f"Stderr:\n{e.stderr}")
        return e.returncode

# Example 1: Check clang-tidy version
print("\n--- Running clang-tidy --version ---")
run_clang_tidy(['--version'])

# Example 2: Run clang-tidy as a Python module (alternative)
# This is often more reliable in environments where PATH might be tricky
def run_clang_tidy_module(args):
    try:
        # Ensure the script running this has access to the python executable
        # that installed clang-tidy.
        result = subprocess.run(['python', '-m', 'clang_tidy'] + args, capture_output=True, text=True, check=True)
        print(f"Stdout:\n{result.stdout}")
        if result.stderr:
            print(f"Stderr:\n{result.stderr}")
        return result.returncode
    except FileNotFoundError:
        print("Error: 'python' command not found, or module path issue.")
        return 1
    except subprocess.CalledProcessError as e:
        print(f"Error running clang-tidy via module: {e.returncode}")
        print(f"Stdout:\n{e.stdout}")
        print(f"Stderr:\n{e.stderr}")
        return e.returncode

print("\n--- Running clang-tidy via 'python -m clang_tidy --version' ---")
run_clang_tidy_module(['--version'])

# To run actual analysis, you typically need a 'compile_commands.json'
# This example is illustrative and won't work without a compiled C++ project.
# For example:
# if os.path.exists('compile_commands.json'):
#     print("\n--- Running clang-tidy on a C++ file (illustrative) ---")
#     run_clang_tidy(['my_source.cpp', '-p', '.'])
# else:
#     print("\nSkipping C++ file analysis: 'compile_commands.json' not found.")