PieBuild

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

pip install piebuild

Quick Start

1. Bake your application

# 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

# 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

# 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

# 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+)

# 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.

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.

piebuild run BUNDLE_PATH

extract

Extract a PieBuild bundle for inspection.

piebuild extract BUNDLE_PATH [OPTIONS]

Options:

• --output, -o: Output directory for extraction

formats

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

piebuild formats

inspect

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

piebuild inspect app.pie
piebuild inspect app.exe
piebuild inspect app.AppDir

validate

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

piebuild validate app.pie
piebuild validate app.exe
piebuild validate app.AppImage

backends

List available build backends.

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

{
  "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

# 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

# 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 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
• 🐛 Issues
• 💬 Discussions
• 📧 Email

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.

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

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

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:

  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)