Metadata-Version: 2.4
Name: xppb
Version: 1.0.0
Summary: A blazing-fast cross-platform Python bundling pipeline tool.
Author-email: nulsie <donotemailme@mail.com>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: modulegraph>=0.17.4

# xppb (cross-platform python bundler)

xppb is a blazing-fast truly cross-platform binary bundler designed to compile, prune, and package Python applications into standalone, production-ready executables for Windows, macOS, and Linux from a single host machine.

Unlike traditional bundlers that are severely limited by their host operating system, xppb natively supports **true cross-compilation**. By temporarily spoofing the Python interpreter's global state and relying on standard archives, a developer on Linux can seamlessly build a signed Windows `.exe` and a fully notarized macOS `.app` bundle simultaneously in a single execution in a matter of seconds(takes a lot configuration and 20-30 min in Nuitka for reference).

---

While tools like PyInstaller, Nuitka, and cx_Freeze are industry standards, xppb bypasses their historical limitations through a modern, aggressive architecture:

* **True Single-Host Cross-Compilation**: PyInstaller and Nuitka require you to build Windows binaries on a Windows host. xppb utilizes a `mock_target_environment` context manager to trick the host Python environment and `modulegraph` into evaluating code paths as if they were running natively on the target operating system.


* **Radical "Default-Deny" Bloat Pruning**: Traditional bundlers pull in massive directories based on exclusion lists. xppb uses a strict surgical whitelist, deleting every file in `site-packages` and the standard library that is not explicitly resolved by the dependency graph. It safely preserves only the structural `__init__.py` files, compiled extensions, and active metadata blocks (like `.dist-info`).


* **Host-Agnostic Apple Code-Signing**: You no longer need an Xcode-equipped Mac to notarize macOS software. xppb automatically fetches Indygreg’s cross-platform `rcodesign` tool to cryptographically sign bundles and submit them directly to the Apple Notary API from Linux or Windows environments.


* **Lightning Fast Dependency Resolution**: xppb searches the host for Astral's `uv` binary. If found, it routes dependency installation through `uv`, utilizing its `--platform` and `--abi` flags to download platform-specific wheels in a fraction of the time standard `pip` would take.


* **Zero-Flash Windows Launchers**: Instead of relying solely on slow script wrappers, xppb scans the host for native C compilers (`gcc`, `cl`, etc.) and dynamically templates and compiles a C-based executable (`launcher_stub.c`) to launch the application silently without console flashes.



---

## Core Features Under the Hood

### 1. The Environment Spoofer (`mock_target_environment`)

To trace platform-specific dependencies (like `winreg` on Windows or `termios` on Linux) without crashing the host machine, xppb temporarily intercepts and rewrites Python's core system identifiers.

```python
# Modifies global state thread-safely before ModuleGraph execution
if "windows" in target_os:
    sys.platform = "win32"
    os.name = "nt"
    sys.builtin_module_names = tuple(set(orig_builtins) | {"winreg", "msvcrt", "_winapi", "nt"})

```

### 2. C-Extension Binary Rescuer

Compiled modules (`.so` / `.pyd`) often hide dynamic imports in their C code that standard AST tracers miss. xppb sweeps compiled extensions, reading them as binary data and matching valid ASCII strings against available system modules to rescue hidden dependencies.

```python
with open(file_path, "rb") as f:
    data = f.read()
for s in data.split(b'\0'):
    # Look for strings that match the active environment file map
    if 2 < len(s) < 50 and s.replace(b'.', b'').replace(b'_', b'').isalnum():
        # ...rescues missing modules...

```

### 3. Persistent Runtime Caching

To save bandwidth across frequent builds, xppb downloads massive standard standard-library `.tar.gz` runtimes into a persistent user-level directory (`~/.core_bundler_cache/runtimes`). Subsequent cross-compilations pull locally from the cache instantly.

---

## On Using It

## Through uv:
```
uv pip install xppb
```

## Through pip:
just remove the uv from the above command.

## Git Clone:
```
git clone https://codeberg.org/nulsie/xppb.git
cd xppb
```

### Prerequisites

* Python 3.11+
* `pip install modulegraph`

* *(Optional but Recommended)*: Install `uv` for drastically accelerated wheel downloads.



### Configuration (`projconf.toml`)

xppb is entirely configuration-driven. Create a file named `projconf.toml` in your project root. Here is a complete reference of the required layout:

```toml
[project]
name = "MyAwesomeApp"
version = "1.0.0"
python_version = "3.11"
entry_point = "main.py"
source_files = ["main.py", "assets/"]
dependencies = ["requests", "rich", "numpy"]
hidden_imports = ["pkg_resources.extern"]
collect_all = []
preserve_extensions = [".png", ".ico"]
launch_command = "{ENTRY_POINT}"

[runtimes]
# URLs pointing to standalone python standard libraries (.tar.gz)
windows-x64 = "https://example.com/python-3.11-win64.tar.gz"
macos-arm64 = "https://example.com/python-3.11-macos-arm64.tar.gz"
linux-x64 = "https://example.com/python-3.11-linux64.tar.gz"

[windows]
hide_console = true
pfx_certificate = "certs/win_cert.pfx"
pfx_password = "SuperSecretPassword123"
hidden_imports = ["winreg"]

[macos]
p12_certificate = "certs/mac_cert.p12"
p12_password = "SuperSecretPassword123"
api_key_path = "certs/AuthKey_ABCD123.p8"
api_issuer_id = "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxx"
api_key_id = "ABCD123"

```

### Usage

Once your `projconf.toml` is configured, simply run `xppb` in your working directory and execute it:

```bash
xppb

```

xppb utilizes a `ProcessPoolExecutor` to spin up a concurrent build thread for every OS target defined in your `[runtimes]` configuration block.

* Build artifacts are processed temporarily in a `build/` directory.

* Final, compressed distribution assets (ready to be uploaded to GitHub Releases or S3) are deposited into `dist/`.

-----

**Author:** nulsie **License:** MIT License
