Metadata-Version: 2.5
Name: piebuild
Version: 3.1.0
Summary: Modern Python application build platform
Project-URL: Homepage, https://github.com/ThatByteGuy/PieBuild
Project-URL: Documentation, https://github.com/ThatByteGuy/PieBuild#readme
Project-URL: Repository, https://github.com/ThatByteGuy/PieBuild
Project-URL: Bug Tracker, https://github.com/ThatByteGuy/PieBuild/issues
Author-email: ThatByteGuy <12aa44edsta@gmail.com>
License: GPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Software Distribution
Requires-Python: >=3.9
Requires-Dist: click>=8.0.0
Requires-Dist: packaging>=21.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: black>=22.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: gui
Requires-Dist: pyside6>=6.5.0; extra == 'gui'
Provides-Extra: signing
Requires-Dist: cryptography>=41.0.0; extra == 'signing'
Description-Content-Type: text/markdown

# PieBuild

[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

PieBuild is a modern Python application build platform that bakes your Python applications into delicious, portable bundles.

## Features

- 🥧 **Simple CLI**: Easy-to-use command-line interface
- 🎯 **Targeted Builds**: Build for different platforms (Windows, Linux, macOS, Native)
- 🔧 **Plugin System**: Extensible architecture for custom backends and formats
- 📦 **Canonical Bundle**: Native `.pie` bundle format (deterministic, portable)
- 🔍 **Multi-Format**: AppImage for Linux, PE `.exe` for Windows (extensible to `.app` via format plugins)
- 🔍 **Bundle Inspection**: Extract and inspect bundled applications
- 🚀 **Direct Execution**: Run bundles directly from the command line
- 📋 **Recipes**: Pre-built templates for common application types

## Installation

```bash
pip install piebuild
```

## Quick Start

### 1. Bake your application

```bash
# Create a simple Python app
echo 'print("Hello from PieBuild!")' > hello.py

# Bake it into a bundle
piebuild bake hello.py

# Run the bundle
piebuild run hello.pie
```

### 2. Build for different targets

```bash
# Build for Windows
piebuild bake app.py --target windows

# Build for Linux
piebuild bake app.py --target linux

# Build for macOS
piebuild bake app.py --target macos
```

### 3. Extract and inspect bundles

```bash
# Extract a bundle for inspection
piebuild extract my_app.pie

# Inspect manifest
piebuild inspect my_app.pie

# View available formats (with capability report)
piebuild formats

# View available backends
piebuild backends
```

### 4. Build AppImage for Linux

```bash
# AppImage is a format adapter over the canonical .pie
piebuild bake app.py --format appimage --target linux

# Formats truthfully report tooling requirements
piebuild formats
# pie        Native PieBuild bundle       linux/windows/macos  Available
# appimage   Linux portable AppImage   linux                Requires: appimagetool
```

### 5. Build Windows EXE (PE32+)

```bash
# EXE is a format adapter over the canonical .pie — genuine PE via MinGW
piebuild bake app.py --format exe --target windows --backend docker  # cross-build via Docker
# or native Windows host:
piebuild bake app.py --format exe --target windows

# Requires MinGW-w64: x86_64-w64-mingw32-gcc + windres for icon/version
piebuild formats
# exe        Windows executable (PE32+)  windows/x86_64  Requires: x86_64-w64-mingw32-gcc
# Code signing: not yet implemented (future: cert, timestamp, CI)
```

## Project Structure

```
piebuild/
├── __init__.py          # Package initialization
├── __main__.py          # CLI entry point
├── config.py            # Configuration models
├── context.py           # Build context utilities
├── core/                # Core build engine
│   ├── __init__.py      # BuildEngine and BuildResult
│   └── bundle.py        # Bundle building logic
├── backends/            # Build backends
│   ├── __init__.py      # Backend registry
│   └── native.py        # Native build backend
├── formats/             # Output formats (plugin architecture)
│   ├── __init__.py      # Format registry & OutputFormat ABC
│   ├── pie.py           # PieBuild native format (canonical)
│   ├── appimage.py      # AppImage format (Linux x86_64)
│   └── exe.py           # Windows PE executable (windows x86_64, MinGW)
├── cli/                 # Command-line interface
│   ├── __init__.py      # CLI package
│   └── main.py          # Main CLI commands
└── tests/               # Test suite
    └── test_core.py      # Core functionality tests
```

## CLI Reference

### bake

Build a Python application into a bundle.

```bash
piebuild bake SOURCE [OPTIONS]
```

**Options:**
- `--output, -o`: Output directory (default: ./dist)
- `--target`: Target platform (native, windows, linux, macos)
- `--backend`: Build backend (default: native)
- `--format`: Output format (default: pie)
- `--onefile`: Create single-file bundle (default: true)
- `--console-mode`: Run in console mode (no GUI)
- `--icon`: Icon file path
- `--recipe`: Build recipe to use

### run

Run a PieBuild bundle.

```bash
piebuild run BUNDLE_PATH
```

### extract

Extract a PieBuild bundle for inspection.

```bash
piebuild extract BUNDLE_PATH [OPTIONS]
```

**Options:**
- `--output, -o`: Output directory for extraction

### formats

List available output formats with capability report (extension, targets, availability, toolchain).

```bash
piebuild formats
```

### inspect

Inspect artifact metadata (pie, exe, AppImage) — target, runtime, dependencies, provenance.

```bash
piebuild inspect app.pie
piebuild inspect app.exe
piebuild inspect app.AppDir
```

### validate

Validate artifact structure and provenance (VALID / VALID_WITH_WARNINGS / INVALID).

```bash
piebuild validate app.pie
piebuild validate app.exe
piebuild validate app.AppImage
```

### backends

List available build backends.

```bash
piebuild backends
```

## Bundle Format

PieBuild bundles are ZIP archives with the following structure:

```
bundle.pie
├── manifest.json      # Bundle metadata
├── launch.sh          # Linux/macOS launcher
├── launch.bat         # Windows launcher
├── source/            # Source files
│   └── app.py
└── bytecode/          # Compiled Python files
    └── app.pyc
```

### Manifest Format

```json
{
  "app_name": "My App",
  "version": "1.0.0",
  "source": "/path/to/source.py",
  "entry_point": "app.py",
  "target_os": "native",
  "target_arch": "native",
  "build_mode": "native",
  "analysis": {
    "imports": ["sys", "os"],
    "missing": []
  },
  "resources": [],
  "bundle_name": "app"
}
```

## Development

### Setup

```bash
# Clone the repository
git clone https://github.com/ThatByteGuy/PieBuild.git
cd PieBuild

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run linting
ruff check piebuild/
black piebuild/
```

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=piebuild

# Run specific test file
pytest tests/test_core.py
```

### Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

## License

This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.

## Roadmap

- [ ] Recipe system with pre-built templates
- [ ] Docker build backend
- [ ] Remote build execution
- [ ] GUI interface
- [ ] VSCode extension
- [ ] Marketplace for recipes and plugins
- [ ] Code signing integration
- [ ] Advanced security scanning
- [ ] Performance optimization
- [ ] Cross-platform packaging (AppImage, macOS app)

## Support

- 📖 [Documentation](https://github.com/ThatByteGuy/PieBuild#readme)
- 🐛 [Issues](https://github.com/ThatByteGuy/PieBuild/issues)
- 💬 [Discussions](https://github.com/ThatByteGuy/PieBuild/discussions)
- 📧 [Email](mailto:12aa44edsta@gmail.com)
## Release Workflow (Phase 11)

### Checksums

Every distributable has a deterministic SHA-256 over final artifact bytes (`piebuild inspect` shows `SHA-256`). Use `piebuild release` to generate `SHA256SUMS` and `release.json` with stable ordering and normalized paths.

### Signing

Local development signer uses Ed25519 via `cryptography` (optional `pip install piebuild[signing]`). Keys are stored outside bundles (`~/.cache/piebuild/signing-keys` or `PIEBUILD_SIGNING_KEY_DIR`), never inside `.pie`.

```bash
piebuild sign app.pie --generate-key
piebuild sign app.pie
piebuild verify app.pie   # ✓ Valid / ⚠ Valid with warnings / ❌ Invalid
```

Tampered artifacts are detected via checksum mismatch before signature verification.

### Release

```bash
piebuild release app.py --output dist/
piebuild release app.py --output dist/ --sign
# generates: app.pie, app.pie.sig (if --sign), release.json, SHA256SUMS
```

Release manifest (`release.json`) is deterministic JSON (sorted keys) describing app, version, artifacts, checksums, provenance, signing state. No absolute paths, usernames, or temp directories are embedded.

### Verify

```bash
piebuild verify app.pie
piebuild verify app.exe
piebuild verify MyApp.AppDir
```

Exit codes: 0 valid (with or without warnings), 2 invalid. Warnings include unsigned artifacts for production.

### Reproducibility

Deterministic portions with `SOURCE_DATE_EPOCH`:
- ZIP metadata (timestamps fixed to 2020-01-01 or SOURCE_DATE_EPOCH)
- File ordering (sorted)
- Manifest ordering (sorted keys)
- Launcher generation
- Bytecode now uses relative `dfile` to avoid absolute build-path leakage (fixed in Phase 11)

Non-reproducible boundaries:
- PE `.exe` via MinGW: PE header timestamp not normalized (byte variance)
- AppImage: requires external `appimagetool`/`mksquashfs` with squashfs timestamps
- `release.json` `built_at` is wall-clock (excluded for deterministic comparison)

### Windows Signing

PieBuild generates legitimate PE via MinGW-w64 (`x86_64-w64-mingw32-gcc` + `windres`). This is **not** Authenticode signed. Authenticode is a separate future provider: `PE generation → PE validation → Authenticode provider → signed EXE`. We do not fake Authenticode.

### Security Boundaries

- No `shell=True`, argument arrays only
- No private keys in bundles
- Path traversal/symlink checks in validation and format extraction
- No environment secrets leaked in provenance/attestation

## Supported Targets (3.1.0 — True Cross, Honest Matrix)

| Target | Arch | Backend | Format | Status |
|--------|------|---------|--------|--------|
| Linux | x86_64 | native | .pie | ✅ verified (system+bundled) — system 37M, bundled uses host |
| Linux | x86_64 | docker | .pie | ✅ verified (linux containers) |
| Linux | x86_64 | native | AppDir | ✅ verified (AppImage needs appimagetool) |
| Windows | x86_64 | native+downloaded | .pie / .exe | ✅ verified **from Linux** — `runtime=bundled` fetches real Windows PE Python (`astral-sh/python-build-standalone`, HTTPS+SHA256), `runtime=system` cross via launcher warning; `.exe` is genuine PE (MinGW) with bundled `python.exe`+`Lib` |
| macOS | x86_64 | native+downloaded | .pie / .app | ✅ verified **from Linux** — `Mach-O x86_64` via downloaded |
| macOS | arm64 | native+downloaded | .pie / .app | ✅ verified **from Linux** — `Mach-O arm64` via downloaded |
| Linux | arm64 | native+downloaded | .pie | ✅ verified **from x86_64 Linux** — `ELF aarch64` via downloaded |
| Linux musl | x86_64 | downloaded | .pie | ✅ `x86_64-unknown-linux-musl` via downloaded (glibc vs musl recorded) |
| Remote | any | remote | any | Future — requires `PIEBUILD_REMOTE_ENDPOINT` |

- `piebuild formats` shows toolchain + bundled-runtime availability (`downloaded` for cross); `piebuild backends`/`runtimes` report target-native cache (`~/.cache/piebuild/runtimes`, validated, corrupt discarded).
- `piebuild runtimes` shows `host_libc` (glibc/musl) and downloaded target runtimes (`windows/x86_64`, `macos/x86_64+arm64`, `linux/aarch64`).
- Cross `runtime=bundled` **never** silently falls back to `system`; fails with actionable `Downloaded provider` hint if unavailable.
- Examples:
  ```bash
  piebuild bake app.py --target linux --runtime bundled                         # host-native
  piebuild bake app.py --target windows --runtime bundled --format exe          # Linux → Windows PE (real python.exe, no Wine)
  piebuild bake app.py --target macos --arch x86_64 --runtime bundled --format app  # Linux → macOS Intel
  piebuild bake app.py --target macos --arch arm64 --runtime bundled           # Linux → macOS Apple Silicon
  piebuild bake app.py --target linux --arch arm64 --runtime bundled            # Linux x86_64 → Linux aarch64
  piebuild bake app.py --target windows --runtime system                        # cross without bundled (needs target Python)
  ```
