extbpy

A minimal CLI tool for building Blender extensions with Python dependencies using uv for fast, reliable dependency resolution.

Features

• Easy Extension Building - Build Blender extensions with a simple command
• Fast Dependency Resolution - Uses uv.lock for precise, reproducible builds
• Cross-Platform Support - Build for Windows, macOS (Intel & ARM), and Linux
• Platform Configuration - Configure target platforms in pyproject.toml
• Rich CLI Interface - Clean command-line interface with progress indicators
• Smart Cleanup - Automatic removal of temporary files and excluded packages

Installation

# Install uv (recommended package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install extbpy
uv add extbpy

Quick Start

1. Set up your project with uv:

# Initialize a new project
uv init my-blender-extension
cd my-blender-extension

# Add dependencies
uv add numpy requests

# Generate lock file for reproducible builds
uv lock

2. Configure platforms in your pyproject.toml:

[project]
name = "my-extension"
dependencies = [
    "numpy>=1.20.0",
    "requests>=2.25.0",
]

[tool.extbpy]
platforms = ["windows-x64", "macos-arm64", "linux-x64"]

3. Build your extension:

# Uses configured platforms from uv.lock
uv run extbpy build

# Or specify platforms manually
uv run extbpy build --platform windows-x64 --platform macos-arm64

# Or build for all supported platforms
uv run extbpy build --platform all

Platform Configuration

Configure your target platforms in pyproject.toml:

[tool.extbpy]
platforms = ["windows-x64", "linux-x64", "macos-arm64", "macos-x64"]

Platform Selection Priority:

1. Explicit platforms (--platform windows-x64) → Uses specified platforms
2. "all" flag (--platform all) → Uses configured platforms or all supported
3. No platforms (extbpy build) → Uses configured platforms or current platform

Supported Platforms:

• windows-x64 - Windows 64-bit
• linux-x64 - Linux 64-bit
• macos-arm64 - macOS Apple Silicon
• macos-x64 - macOS Intel

Commands

build - Build Extension

extbpy build [OPTIONS]

Build a complete Blender extension with Python dependencies.

Key Options:

• -p, --platform - Target platforms (windows-x64, linux-x64, macos-arm64, macos-x64, all)
• -s, --source-dir - Source directory containing extension files
• -o, --output-dir - Output directory for built extensions
• --clean/--no-clean - Clean wheel directory before downloading (default: true)

download - Download Wheels Only

extbpy download [OPTIONS]

Download Python wheels without building the extension.

info - Project Information

extbpy info

Display project metadata, configured platforms, and dependencies.

clean - Clean Temporary Files

extbpy clean

Remove temporary files like .blend1 and .MNSession files.

How it Works

extbpy uses uv for fast, reliable dependency resolution:

1. Lock File Based - Reads from uv.lock for exact dependency versions
2. Cross-Platform Wheels - Downloads platform-specific wheels from the lock file
3. Reproducible Builds - Same lock file produces identical builds across environments
4. Fast Resolution - Leverages uv's speed for dependency resolution

Project Structure

my-blender-extension/
├── pyproject.toml          # Python project configuration  
├── uv.lock                 # Locked dependencies (generated by uv)
├── my-extension/           # Extension directory
│   ├── blender_manifest.toml  # Blender extension manifest
│   ├── __init__.py            # Extension code
│   └── wheels/                # Downloaded wheels (auto-generated)
└── README.md

Examples

# Build using configured platforms
uv run extbpy build

# Build for specific platforms  
uv run extbpy build -p windows-x64 -p macos-arm64

# Build for all supported platforms
uv run extbpy build -p all

# Download wheels only
uv run extbpy download -p linux-x64

# Show project info
uv run extbpy info

# Clean temporary files
uv run extbpy clean

License

MIT License - see the LICENSE file for details.