extbpy 0.2.0
A powerful CLI tool for building Blender extensions with Python dependencies
Requires Python: >=3.11
Keywords: blender, extension, addon, build, wheels

# 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

```bash
# 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:

```bash
# 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`:

```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:

```bash
# 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`:

```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

```bash
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

```bash
extbpy download [OPTIONS]
```

Download Python wheels without building the extension.

### `info` - Project Information

```bash
extbpy info
```

Display project metadata, configured platforms, and dependencies.

### `clean` - Clean Temporary Files

```bash
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

```bash
# 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](LICENSE) file for details.