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

# 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

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

#!/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:

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

# 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

# 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

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

# 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

# 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