Metadata-Version: 2.4
Name: compitum
Version: 0.1.0
Summary: The universal ARM64 compatibility layer: classify ARM64 Windows binaries and decide how they can be executed.
Author: The COMPITUM Project
License: MIT OR Apache-2.0
Project-URL: Homepage, https://github.com/compitum-dev/compitum
Project-URL: Repository, https://github.com/compitum-dev/compitum
Project-URL: Issues, https://github.com/compitum-dev/compitum/issues
Project-URL: Changelog, https://github.com/compitum-dev/compitum/commits/main
Keywords: arm64,aarch64,arm64ec,arm64x,abi,pe,coff,windows-on-arm,compatibility
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Emulators
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# COMPITUM

**The universal ARM64 compatibility layer.**

Answers the question no tool answers today — *will this Windows ARM64 binary run natively
on this machine, or does it need translation?* — and routes it accordingly.

## The problem it solves

"ARM64 binary" names three structurally different things, and mistaking one for another
produces either a crash or a large performance loss:

| Flavour | Machine type in a **linked** image | How it is *actually* identified | Contains |
|---|---|---|---|
| ARM64   | `0xAA64` | machine type alone | pure AArch64 |
| ARM64EC | `0x8664` | `0x8664` **plus CHPE metadata** | AArch64 **and x86-64** |
| ARM64X  | `0xAA64` | `0xAA64` **plus CHPE metadata** | both slices |

Read that middle column carefully, because it is the part almost every tool gets wrong.
`0xA641` and `0xA64E` look like the obvious machine types for ARM64EC and ARM64X, and they
appear in toolchain output — but Microsoft states they are *internal MSVC object-file
identifiers* and **not valid final PE machine types**.

A linked ARM64EC executable therefore reports `0x8664`, indistinguishable from plain x86-64
by machine type alone. The distinction lives in CHPE metadata, reached through the
load-configuration directory.

Every other tool in this space collapses that table to a single row, which is wrong in one
direction or the other on almost every real binary.

## What it decides

| Route | What gets translated | Expected throughput |
|---|---|---|
| `native` | nothing | 100% |
| `pick_native_slice` | nothing, after slice selection | 100% |
| `fex_partial` | only the x86-64 blocks | 70-90% |
| `box64_full` / `fex_full` | every instruction | 20-60% |
| `refused` | nothing — impossible, with a reason naming the obstacle | — |

Keeping `fex_partial` distinct from `fex_full` is where the performance comes from.

## This package

The classifier is implemented in Rust and ships as a native binary. This Python package
reserves the PyPI name and provides a stable entry point; see the repository for the
Rust crates, which are published separately on crates.io.

Source: <https://github.com/compitum-dev/compitum>

## Licence

MIT OR Apache-2.0, at your option.
