# PymergeticOS Builder

Modular Python-based OS builder for creating Debian-based live ISOs.

## Features

- **Python-based**: Flexible and maintainable
- **Modular**: Plugin system for adding components
- **Fire CLI**: Easy-to-use command-line interface
- **Namespace package**: PEP 420 compliant, allows extending `pymergetic` namespace
- **PyPI package**: Installable via `pip install pymergetic-os-builder`

## Installation

### From PyPI

```bash
pip install pymergetic-os-builder
```

### From Source

```bash
# Clone the repository
git clone https://github.com/pymergetic/os-builder.git
cd os-builder

# Install in development mode
pip install -e .
```

## Quick Start

```bash
# Build ISO (uses pymergetic_os.yaml from current directory or config path)
pymergetic-build build

# Build with custom config file
pymergetic-build build --config=/path/to/config.yaml

# Or use environment variable
export PYMERGETIC_OS_BUILD_CONFIG=/path/to/config.yaml
pymergetic-build build

# Clean build artifacts
pymergetic-build clean

# Or use Python module directly
python -m pymergetic.os.builder.cli build
```

## Configuration

Edit your configuration YAML file to customize:
- Debian release (trixie, bookworm, etc.)
- Hostname
- Packages (YAML list)
- Desktop environment
- Build directories

**Config file:**
- Must be provided via `--config` parameter or `PYMERGETIC_OS_BUILD_CONFIG` environment variable
- If not provided, uses default configuration
- No automatic file discovery

The configuration uses Pydantic for type safety and validation. See `USAGE.md` for detailed usage instructions.

## Modules

Modules are pluggable components that can be added to the build:
- `base/` - Base OS (always included)
- `provision/` - Provisioning scripts
- Future: `uv/`, `python/`, `app/`

## Architecture

- `pymergetic/` - PEP 420 namespace package
- `pymergetic.os.builder/` - OS builder subpackage
  - `pymergetic.os.builder.builder.py` - Main builder class
  - `pymergetic.os.builder.config.py` - Configuration management
  - `pymergetic.os.builder.modules/` - Plugin modules
  - `pymergetic.os.builder.cli.py` - Fire CLI interface

This is structured as a namespace package, allowing other packages to be added to the `pymergetic` namespace later (e.g., `pymergetic.core`, `pymergetic.app`).

## Development

### Building and Publishing

```bash
# Build package
make build

# Publish to PyPI
make publish

# Full release (tag, build, publish)
make release
```

See `Makefile` for all available targets.

## Documentation

See `USAGE.md` for detailed usage instructions.

