{"id":7081,"library":"clang-tidy","title":"Clang-tidy","description":"The `clang-tidy` Python package provides pre-built binaries of the LLVM-based code analyser tool `clang-tidy`, making the executable available in Python environments. It is currently at version 22.1.0.1, primarily reflecting the packaged LLVM version. Releases typically follow major LLVM releases, with additional patches for packaging updates.","status":"active","version":"22.1.0.1","language":"en","source_language":"en","source_url":"https://github.com/ssciwr/clang-tidy-wheel","tags":["code analysis","linting","LLVM","C++","executable wrapper"],"install":[{"cmd":"pip install clang-tidy","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"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.","symbol":"No direct Python API","correct":"import subprocess\n# Or use: python -m clang_tidy"}],"quickstart":{"code":"import subprocess\nimport os\n\ndef run_clang_tidy(args):\n    try:\n        # Option 1: Using subprocess directly with the executable\n        # Requires 'clang-tidy' to be in PATH or specified with full path\n        # For this package, 'clang-tidy' should be in PATH after install\n        result = subprocess.run(['clang-tidy'] + args, capture_output=True, text=True, check=True)\n        print(f\"Stdout:\\n{result.stdout}\")\n        if result.stderr:\n            print(f\"Stderr:\\n{result.stderr}\")\n        return result.returncode\n    except FileNotFoundError:\n        print(\"Error: 'clang-tidy' command not found. Ensure the package is installed and accessible.\")\n        return 1\n    except subprocess.CalledProcessError as e:\n        print(f\"Error running clang-tidy: {e.returncode}\")\n        print(f\"Stdout:\\n{e.stdout}\")\n        print(f\"Stderr:\\n{e.stderr}\")\n        return e.returncode\n\n# Example 1: Check clang-tidy version\nprint(\"\\n--- Running clang-tidy --version ---\")\nrun_clang_tidy(['--version'])\n\n# Example 2: Run clang-tidy as a Python module (alternative)\n# This is often more reliable in environments where PATH might be tricky\ndef run_clang_tidy_module(args):\n    try:\n        # Ensure the script running this has access to the python executable\n        # that installed clang-tidy.\n        result = subprocess.run(['python', '-m', 'clang_tidy'] + args, capture_output=True, text=True, check=True)\n        print(f\"Stdout:\\n{result.stdout}\")\n        if result.stderr:\n            print(f\"Stderr:\\n{result.stderr}\")\n        return result.returncode\n    except FileNotFoundError:\n        print(\"Error: 'python' command not found, or module path issue.\")\n        return 1\n    except subprocess.CalledProcessError as e:\n        print(f\"Error running clang-tidy via module: {e.returncode}\")\n        print(f\"Stdout:\\n{e.stdout}\")\n        print(f\"Stderr:\\n{e.stderr}\")\n        return e.returncode\n\nprint(\"\\n--- Running clang-tidy via 'python -m clang_tidy --version' ---\")\nrun_clang_tidy_module(['--version'])\n\n# To run actual analysis, you typically need a 'compile_commands.json'\n# This example is illustrative and won't work without a compiled C++ project.\n# For example:\n# if os.path.exists('compile_commands.json'):\n#     print(\"\\n--- Running clang-tidy on a C++ file (illustrative) ---\")\n#     run_clang_tidy(['my_source.cpp', '-p', '.'])\n# else:\n#     print(\"\\nSkipping C++ file analysis: 'compile_commands.json' not found.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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>`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The `clang-tidy` executable is not in your system's PATH, or the pip installation failed to link it correctly.","error":"clang-tidy: command not found"},{"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`.","cause":"You ran `clang-tidy` without specifying any C++ source files to analyze.","error":"Error: no input files"},{"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>`.","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.","error":"No compilation database found in directory [directory path]"}]}