deb-osbuild/docs/DEVELOPMENT.md

# Development Guide

This document provides guidance for developers working on the particle-os project.

## Development Environment Setup

### Prerequisites

- Python 3.8 or higher
- Debian-based system (Ubuntu, Debian, etc.)
- Root access for package installation
- Git

### Quick Setup

```bash
# Clone the repository
git clone <repository-url>
cd particle-os

# Run the development setup script
./scripts/dev-setup.sh

# Activate virtual environment
source venv/bin/activate
```

### Manual Setup

```bash
# Install system dependencies
sudo apt update
sudo apt install -y python3 python3-pip python3-venv python3-dev debootstrap chroot

# Install built packages
sudo dpkg -i debs/*.deb
sudo apt-get install -f

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install Python dependencies
pip install -r requirements.txt

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

## Project Structure

```
particle-os/
├── src/                     # Source code
│   ├── osbuild/            # Core osbuild implementation
│   ├── stages/             # Debian-specific stages
│   ├── assemblers/         # Output format handlers
│   └── schemas/            # JSON schemas
├── examples/                # Example manifests
├── tests/                   # Test suite
├── docs/                    # Documentation
└── scripts/                 # Build scripts
```

## Adding New Stages

### Stage Implementation

1. Create a new Python file in `src/stages/`
2. Follow the naming convention: `org.osbuild.debian.<name>`
3. Implement the required interface:

```python
#!/usr/bin/python3

import os
import sys
import osbuild.api

def main(tree, options):
    """Stage description"""
    # Implementation here
    return 0

if __name__ == '__main__':
    args = osbuild.api.arguments()
    ret = main(args["tree"], args["options"])
    sys.exit(ret)
```

### Stage Metadata

Create a corresponding `.meta.json` file:

```json
{
  "name": "org.osbuild.debian.<name>",
  "version": "1",
  "description": "Stage description",
  "stages": {
    "org.osbuild.debian.<name>": {
      "type": "object",
      "additionalProperties": false,
      "required": [],
      "properties": {
        "option1": {
          "type": "string",
          "description": "Option description"
        }
      }
    }
  },
  "capabilities": {
    "CAP_SYS_ADMIN": "Required capability"
  },
  "external_tools": ["required-tool"]
}
```

### Testing

1. Add tests to `tests/test_<name>.py`
2. Run tests: `make test`
3. Ensure good test coverage

## Building and Testing

### Common Commands

```bash
# Install in development mode
make install

# Run tests
make test

# Run linting
make lint

# Format code
make format

# Clean build artifacts
make clean

# Full rebuild
make rebuild
```

### Testing Stages

```bash
# Test individual stage
python3 src/stages/org.osbuild.debian.debootstrap

# Run with test data
python3 src/stages/org.osbuild.debian.debootstrap /tmp/test-tree '{"suite": "trixie"}'
```

## Manifest Development

### Basic Structure

```json
{
  "version": "2",
  "pipelines": [
    {
      "name": "build",
      "runner": "org.osbuild.linux",
      "stages": [
        {
          "name": "org.osbuild.debian.debootstrap",
          "options": {
            "suite": "trixie"
          }
        }
      ]
    }
  ],
  "assembler": {
    "name": "org.osbuild.tar",
    "options": {
      "filename": "output.tar.gz"
    }
  }
}
```

### Testing Manifests

```bash
# Build with manifest
particle-os examples/debian-basic.json

# Debug mode
particle-os --debug examples/debian-basic.json
```

## Contributing

### Code Style

- Follow PEP 8 guidelines
- Use type hints where possible
- Write docstrings for all functions
- Keep functions small and focused

### Testing Requirements

- All new code must have tests
- Maintain test coverage above 80%
- Include integration tests for complex features

### Pull Request Process

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Ensure all tests pass
6. Submit a pull request

## Troubleshooting

### Common Issues

#### Stage Not Found
- Check stage is in correct directory
- Verify metadata file exists
- Check stage permissions (should be executable)

#### Permission Denied
- Ensure stage has correct capabilities
- Check if running as root when required
- Verify external tool availability

#### Build Failures
- Check manifest syntax
- Verify all required stages are available
- Check external tool dependencies

### Debug Mode

```bash
# Enable debug output
export OSBUILD_DEBUG=1

# Run with verbose logging
particle-os --verbose manifest.json
```

## External Dependencies

### Required Tools

- `debootstrap`: Base system construction
- `chroot`: Filesystem isolation
- `apt-get`: Package management
- `ostree`: OSTree operations
- `bootc`: Bootloader management

### Package Versions

- Python: 3.8+
- jsonschema: 4.0.0+
- pytest: 7.0.0+

## Performance Considerations

- Use appropriate debootstrap variants
- Minimize package installations
- Leverage caching when possible
- Consider parallel stage execution

## Security

- Validate all inputs
- Use minimal required capabilities
- Sanitize file paths
- Implement proper error handling