Metadata-Version: 2.4
Name: wheelmonger
Version: 0.1.0a1
Summary: Linux wheel builder with custom library vendoring policy
Author-email: Christian Heimes <christian@python.org>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: auditwheel>=6.7
Requires-Dist: packaging
Description-Content-Type: text/markdown

# wheelmonger

Vendor shared libraries into Python wheels using a custom TOML policy,
producing `linux_<arch>` platform wheels.

wheelmonger wraps [auditwheel](https://github.com/pypa/auditwheel) and
gives you explicit control over which shared libraries are vendored into
the wheel, which are assumed to be system-provided, and which are
cross-wheel dependencies that should be left untouched.

## Installation

```bash
pip install wheelmonger
```

Requires Python 3.12+ and a glibc-based Linux system.

## Quick start

### 1. Write a policy file

Create a `policy.toml` that classifies your wheel's shared library
dependencies into three lists:

```toml
[policy]
vendor = [
    "libzmq.so.*",
    "libqhull_r.so.*",
]

skip = [
    "libtorch.so",
    "libtorch_cpu.so",
]

system = [
    "libcrypto.so.*",
    "libssl.so.*",
    "libcurl.so.*",
]
```

- **vendor** -- libraries to copy into the wheel and rewrite ELF references.
- **skip** -- cross-wheel dependencies to leave untouched (e.g. PyTorch).
- **system** -- libraries assumed present on the target system.

Patterns use fnmatch-style globbing. Libraries on the manylinux allow list
(e.g. `libc.so.6`, `libm.so.6`) are always treated as system-provided
automatically.

### 2. Inspect dependencies

```bash
wheelmonger show my_package-1.0-cp314-cp314-linux_x86_64.whl -p policy.toml
```

### 3. Repair the wheel

```bash
wheelmonger repair my_package-1.0-cp314-cp314-linux_x86_64.whl -p policy.toml
```

The repaired wheel is written to `wheelhouse/` by default.  A
[CycloneDX](https://cyclonedx.org/) SBOM (`wheelmonger.cdx.json`) is
generated automatically for vendored libraries and stored in the
wheel's `.dist-info/sboms/` directory.

## Usage

```
wheelmonger repair WHEEL -p POLICY [-w WHEEL_DIR] [-L LIB_SDIR] [--strip] [-v]
wheelmonger show WHEEL -p POLICY [-v]
```

### `repair`

| Option | Description |
|--------|-------------|
| `-p, --policy` | Path to the TOML policy file (or `$WHEELMONGER_POLICY`) |
| `-w, --wheel-dir` | Output directory (default: `wheelhouse/`) |
| `-L, --lib-sdir` | Subdirectory for vendored libs (default: `.libs`) |
| `--strip` | Strip symbols from vendored libraries |
| `--add-vendor PATTERN` | Additional library pattern to vendor (repeatable; or `$WHEELMONGER_VENDOR_LIBS`) |
| `-z, --zip-compression-level` | Zip compression level (default: zlib default) |
| `-v, --verbose` | Increase verbosity (repeatable) |

### `show`

Displays all shared library dependencies grouped by classification
(vendor, manylinux, system, skip, unknown) without modifying the wheel.

## Environment variables

| Variable | Description |
|----------|-------------|
| `WHEELMONGER_POLICY` | Default path to the TOML policy file. Overridden by `-p`/`--policy`. |
| `WHEELMONGER_VENDOR_LIBS` | Additional vendor patterns separated by `os.pathsep`. |

## License

[MIT](LICENSE)
