Metadata-Version: 2.4
Name: clang_tools
Version: 2.0.0
Summary: Install clang-tools (clang-format, clang-tidy, clang-query, clang-apply-replacements, clang-include-cleaner) with pip
Author-email: Xianpeng Shen <xianpeng.shen@gmail.com>, Brendan Doherty <2bndy5@gmail.com>
License-Expression: MIT
Project-URL: source, https://github.com/cpp-linter/clang-tools-pip
Project-URL: tracker, https://github.com/cpp-linter/clang-tools-pip/issues
Keywords: clang,clang-tools,clang-extra,clang-tidy,clang-format,clang-query,clang-apply-replacements,clang-include-cleaner
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Information Technology
Classifier: Natural Language :: English
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: coverage; extra == "dev"
Requires-Dist: pre-commit; python_version >= "3.11" and extra == "dev"
Requires-Dist: pygments>=2.20.0; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Provides-Extra: docs
Requires-Dist: markdown-gfm-admonition>=0.1.1; extra == "docs"
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocs-gen-files>=0.5; extra == "docs"
Requires-Dist: mkdocs-include-markdown-plugin>=7.3.0; extra == "docs"
Requires-Dist: pygments>=2.20.0; extra == "docs"
Dynamic: license-file

# clang-tools

[![PyPI](https://img.shields.io/pypi/v/clang-tools?labelColor=454a63&color=007ec6)](https://pypi.org/project/clang-tools/)
[![ci](https://img.shields.io/github/actions/workflow/status/cpp-linter/clang-tools-pip/test.yml?branch=main&label=ci&labelColor=454a63)](https://github.com/cpp-linter/clang-tools-pip/actions/workflows/test.yml)
[![coverage](https://img.shields.io/codecov/c/github/cpp-linter/clang-tools-pip?labelColor=454a63)](https://codecov.io/gh/cpp-linter/clang-tools-pip)
[![part of cpp-linter](https://img.shields.io/badge/part%20of-cpp--linter-ffc20a?labelColor=454a63)](https://cpp-linter.github.io/)

Install `clang-format`, `clang-tidy` and other LLVM tools without building LLVM, as static binaries
or Python wheels, using the `clang-tools` CLI.

[Website](https://cpp-linter.github.io/) ·
[Documentation](https://cpp-linter.github.io/clang-tools-pip/) ·
[Get started](https://cpp-linter.github.io/getting-started/#just-the-clang-tools) ·
[Discussions](https://github.com/orgs/cpp-linter/discussions)

## Quick start

```bash
pip install clang-tools
clang-tools install clang-format clang-tidy --version 21
```

This installs the LLVM 21 static binaries `clang-format-21` and `clang-tidy-21`. Without
`--version`, it installs the newest LLVM version. Without
`--directory`, they go to `~/.local/bin` on Linux, and on macOS and Windows to the folder that
holds the Python executable (the `bin` or `Scripts` folder of a virtual environment).
A `--directory` that doesn't exist is created, but the parent folder(s) must exist.

> [!TIP]
> It is recommended to use this package in a virtual environment.
>
> ```bash
> python -m venv env-name
> source env-name/bin/activate  # Linux and macOS
> ./env-name/Scripts/activate   # Windows
> ```

## Usage

`clang-tools install` installs the static binary of each tool. It falls back to the tool's wheel
from PyPI when there is no static binary for that version, tool or platform, or when the download
fails; any other error stops the command. Without `--version`, it installs the newest version. For a
full list of CLI options, see the [CLI reference](https://cpp-linter.github.io/clang-tools-pip/cli_args/).

`--version` can be a major version (`21`) or a full one (`21.1.8`). Either way the binary is named
by its major version (`clang-format-21`). A full version must match exactly: if the static binary of
LLVM 21 is another patch release, the wheel of that exact version is installed instead.

### Install binaries

```bash
# Install the newest version
clang-tools install clang-format

# Install a specific version (binary first, falls back to the wheel)
clang-tools install clang-format --version 21

# Install to a specified directory
clang-tools install clang-format --version 21 --directory .
```

If the installed directory is in your path:

```bash
clang-format-21 --version
# clang-format version 21.1.0
```

To uninstall, give the tool names and the version:

```bash
clang-tools uninstall clang-format --version 21 --directory .
```

- Uses SHA512 checksums to verify downloaded binaries.
- Keeps each downloaded binary in a data directory, one folder per release, and puts a link
  to it (e.g., `clang-format-21`) in the install directory. Installing the same version again,
  in any directory, doesn't download it again.
- Installs clang's builtin headers (`stddef.h`, `stdarg.h`, ...) next to clang-tidy, clang-query,
  clang-include-cleaner and clang-scan-deps, so they can parse code that includes system headers.
- Creates unversioned symlinks (e.g., `clang-format`) alongside versioned binaries (`clang-format-21`) for convenience.
- If the versioned binary (e.g., `clang-format-21`) is already on your PATH, links to it instead of downloading.

The data directory is `~/.local/share/clang-tools` on Linux (or `$XDG_DATA_HOME/clang-tools`),
`~/Library/Application Support/clang-tools` on macOS and `%LOCALAPPDATA%\clang-tools` on Windows.
Set `CLANG_TOOLS_DATA_DIR` to use another directory. `clang-tools uninstall` removes the links, not
the data directory; delete it to free the space.

An install directory outside your home directory, such as `/usr/local/bin` with `sudo` or in a
Docker image, gets a copy of each tool instead of a link, because other users may not be able to
read your home directory. The builtin headers then go to `<install directory>/../lib/clang` (such
as `/usr/local/lib/clang`), where clang looks for them. Setting `CLANG_TOOLS_DATA_DIR` keeps the
links.

A static binary installed by `clang-tools` is checked against the index each time it is installed
again. If the index can't be reached (for example, offline), the installed binary is kept. A wheel
of the version asked for is kept as it is, without checking the package index.

> [!NOTE]
> To create symbolic links on Windows, you must enable
> [Developer Mode](https://learn.microsoft.com/en-us/windows/advanced-settings/developer-mode).
> Without it, the binaries are copied to the install directory. On Windows, clang's builtin
> headers are also copied to `<install directory>\..\lib\clang`, because clang (LLVM 12 to 17 at
> least) looks for them next to the link rather than next to the binary it points to.

> [!IMPORTANT]
> This package only manages binary executables
> (& corresponding symbolic links) that are installed using this
> package's executable script. It does not intend to change or modify
> any binary executable installed from other sources (like LLVM
> releases).

### Install wheels

When there is no static binary, `clang-tools` downloads the tool's wheel from PyPI, checks its
SHA256 checksum and installs it like a static binary: a link in the install directory (e.g.
`clang-format-10`) to the executable kept in the data directory. pip is not needed, so this works
in environments made by `uv`, `uvx` and `pipx`, and `--directory` and `clang-tools uninstall` work
the same as for binaries.

```bash
# clang-format 10 has no static binary, so its wheel is installed
clang-tools install clang-format --version 10
```

Wheels are found with the simple repository API of the package index (PEP 691 or PEP 503), so a
mirror of PyPI works too. The index is `CLANG_TOOLS_PYPI_URL`, else the one set with
`UV_DEFAULT_INDEX`, `UV_INDEX_URL` or `PIP_INDEX_URL` (default: `https://pypi.org/simple`). The URL
may hold a user name and password, which are only sent to that server (not after a redirect to
another URL). Configuration files such as `pip.conf` and `uv.toml` are not read, and neither are
extra indexes, so an index that doesn't have the tools needs `CLANG_TOOLS_PYPI_URL` set to
`https://pypi.org/simple` or a mirror of it.

### Install the development version

```bash
pip install git+https://github.com/cpp-linter/clang-tools-pip.git@main
```

## Supported versions

### clang tools binaries

Every LLVM version listed in the
[index](https://cpp-linter.github.io/clang-tools-static-binaries/index.json) (LLVM 12 to 23 today),
for Linux, macOS and Windows on x86-64 and ARM64:

- clang-format
- clang-tidy
- clang-query
- clang-apply-replacements
- clang-include-cleaner (LLVM 18 and later)
- llvm-cov
- llvm-profdata
- llvm-symbolizer
- clang-scan-deps

For more details, visit [clang-tools-static-binaries](https://github.com/cpp-linter/clang-tools-static-binaries).

### clang tools Python wheels

- [clang-format](https://pypi.org/project/clang-format/#history)
- [clang-tidy](https://pypi.org/project/clang-tidy/#history)
- [clang-include-cleaner](https://pypi.org/project/clang-include-cleaner/#history) (LLVM 22)
- [clang-apply-replacements](https://pypi.org/project/clang-apply-replacements/#history) (LLVM 16 and later)

Wheels are used for versions and platforms that have no static binary, such as clang-format 10,
32-bit Windows, or Linux on i686 and ARMv7 (and on ppc64le and s390x for clang-format). Check the
respective PyPI pages for available versions and platform support.

## Contributing

See the [contributing guide](https://github.com/cpp-linter/clang-tools-pip/blob/main/CONTRIBUTING.md)
and [open an issue](https://github.com/cpp-linter/clang-tools-pip/issues) for bugs and feature requests.

## License

This project is licensed under the [MIT License](https://github.com/cpp-linter/clang-tools-pip/blob/main/LICENSE).
