deb-mock/docs/SBUILD_INTEGRATION.md

# Deb-Mock Sbuild Integration

## Overview

The `deb-mock` sbuild integration provides a robust, production-ready interface to Debian's `sbuild` package building system. This integration enables `deb-mock` to build actual Debian packages using the same tooling that Debian developers use in production.

## Features

- **Automatic requirement checking** - Validates sbuild availability, user permissions, and configuration
- **Intelligent error handling** - Provides clear error messages and recovery suggestions
- **Dependency management** - Automatic checking and installation of build dependencies
- **Chroot management** - Update and query chroot information
- **Comprehensive CLI** - Full command-line interface for all sbuild operations
- **Integration with deb-orchestrator** - Seamless integration with the build orchestration system

## Architecture

### Core Components

1. **SbuildWrapper** - Main wrapper class for sbuild operations
2. **Automatic Configuration** - Self-configuring sbuild setup
3. **Error Handling** - Comprehensive error detection and reporting
4. **CLI Integration** - Full command-line interface

### Integration Points

- **deb-mock core** - Integrated into the main build system
- **Plugin system** - Hooks for customizing sbuild behavior
- **deb-orchestrator** - Task execution and result collection

## Requirements

### System Requirements

- **sbuild package** - Debian package building tool
- **schroot** - Chroot management system
- **User permissions** - User must be in the `sbuild` group

### Setup Commands

```bash
# Install sbuild
sudo apt-get install sbuild

# Add user to sbuild group
sudo sbuild-adduser $USER

# Start new shell session or use newgrp
newgrp sbuild
```

## Configuration

### Automatic Configuration

The sbuild integration automatically creates a minimal configuration file at `~/.config/sbuild/config.pl`:

```perl
#!/usr/bin/perl
# deb-mock sbuild configuration
$chroot_mode = "schroot";
$schroot = "schroot";
```

### Manual Configuration

You can override the automatic configuration by creating your own `~/.config/sbuild/config.pl` or `~/.sbuildrc` file.

## Usage

### CLI Commands

#### Chroot Management

```bash
# Show chroot information
deb-mock chroot-info debian-trixie-amd64

# Update chroot packages
deb-mock update-chroot debian-trixie-amd64
```

#### Dependency Management

```bash
# Check build dependencies
deb-mock check-deps /path/to/source-package

# Install build dependencies
deb-mock install-deps package1 package2
```

#### Package Building

```bash
# Build package with sbuild
deb-mock build-with-sbuild /path/to/source-package

# Build with custom options
deb-mock build-with-sbuild /path/to/source-package \
    --chroot debian-trixie-amd64 \
    --output-dir ./output \
    --verbose
```

### Programmatic Usage

```python
from deb_mock.config import Config
from deb_mock.sbuild import SbuildWrapper

# Create configuration
config = Config(
    chroot_name="debian-trixie-amd64",
    suite="trixie",
    architecture="amd64"
)

# Initialize wrapper
wrapper = SbuildWrapper(config)

# Check dependencies
deps = wrapper.check_dependencies("source-package")
if not deps["satisfied"]:
    wrapper.install_build_dependencies(deps["missing"])

# Build package
result = wrapper.build_package("source-package")
```

## Error Handling

### Common Issues and Solutions

#### 1. User Not in Sbuild Group

**Error**: `User joe is not currently an effective member of group sbuild`

**Solution**:
```bash
sudo sbuild-adduser $USER
newgrp sbuild  # or start new shell session
```

#### 2. Sbuild Not Found

**Error**: `sbuild not found. Please install sbuild package`

**Solution**:
```bash
sudo apt-get install sbuild
```

#### 3. Chroot Not Available

**Error**: `Chroot 'debian-trixie-amd64' not found`

**Solution**:
```bash
# Create chroot using deb-mock
deb-mock init-chroot debian-trixie-amd64

# Or use sbuild directly
sudo sbuild-createchroot --arch=amd64 trixie /var/lib/schroot/chroots/debian-trixie-amd64
```

#### 4. Build Dependencies Missing

**Error**: `Unmet build dependencies`

**Solution**:
```bash
# Check what's missing
deb-mock check-deps /path/to/source-package

# Install missing dependencies
deb-mock install-deps package1 package2
```

### Error Recovery

The integration provides automatic error recovery for common issues:

- **Missing dependencies** - Automatically attempts to install
- **Configuration issues** - Creates minimal working configuration
- **Permission problems** - Provides clear setup instructions

## Integration with deb-orchestrator

### Task Execution

The sbuild integration works seamlessly with `deb-orchestrator`:

1. **Task Creation** - Build tasks are created in the orchestrator
2. **Dependency Resolution** - Build dependencies are automatically checked
3. **Package Building** - sbuild executes the actual package build
4. **Result Collection** - Build artifacts and metadata are collected
5. **Status Reporting** - Build success/failure is reported back

### Example Workflow

```python
# In deb-orchestrator task
task = {
    "id": 123,
    "type": "build_package",
    "source_package": "test-package",
    "chroot": "debian-trixie-amd64",
    "architecture": "amd64"
}

# deb-mock executes the build
result = deb_mock.build_with_sbuild(
    source_package=task["source_package"],
    chroot=task["chroot"],
    arch=task["architecture"]
)

# Result is reported back to orchestrator
orchestrator.report_build_result(task["id"], result)
```

## Performance and Optimization

### Caching

- **Root cache** - Chroot state caching for faster rebuilds
- **Package cache** - APT package caching
- **ccache** - Compiler caching for faster compilation

### Parallelization

- **Multiple chroots** - Build multiple packages simultaneously
- **Worker processes** - Parallel task execution
- **Resource management** - Efficient resource utilization

## Security

### Isolation

- **Chroot isolation** - Complete filesystem isolation
- **User separation** - Dedicated build users
- **Network control** - Controlled network access

### Permissions

- **Minimal privileges** - Only necessary permissions granted
- **User mapping** - Proper UID/GID handling
- **Capability dropping** - Security capability management

## Monitoring and Debugging

### Logging

- **Build logs** - Complete sbuild output capture
- **Error logs** - Detailed error information
- **Performance metrics** - Build time and resource usage

### Debugging

```bash
# Enable verbose output
deb-mock build-with-sbuild package --verbose --debug

# Check chroot status
deb-mock chroot-info chroot-name

# Verify dependencies
deb-mock check-deps package
```

## Best Practices

### Configuration

1. **Use dedicated chroots** - Separate chroots for different distributions
2. **Regular updates** - Keep chroots updated with latest packages
3. **Resource limits** - Set appropriate memory and disk limits

### Build Process

1. **Dependency checking** - Always check dependencies before building
2. **Clean builds** - Use clean chroots for reproducible builds
3. **Artifact collection** - Properly collect and store build artifacts

### Error Handling

1. **Graceful degradation** - Handle errors without breaking the build system
2. **User feedback** - Provide clear error messages and solutions
3. **Recovery mechanisms** - Automatic recovery when possible

## Troubleshooting

### Debug Mode

Enable debug mode for detailed information:

```bash
export DEB_MOCK_DEBUG=1
deb-mock build-with-sbuild package --debug
```

### Common Problems

1. **Permission denied** - Check user group membership
2. **Chroot not found** - Verify chroot exists and is accessible
3. **Build failures** - Check build logs for specific errors
4. **Dependency issues** - Verify package availability in chroot

### Getting Help

- **Error messages** - Read error messages carefully for solutions
- **Build logs** - Check build logs for detailed error information
- **Documentation** - Refer to this documentation and sbuild man pages
- **Community** - Check deb-mock project issues and discussions

## Future Enhancements

### Planned Features

- **Multi-architecture support** - Cross-compilation and multi-arch builds
- **Advanced caching** - Intelligent cache management and optimization
- **Build profiling** - Performance analysis and optimization suggestions
- **Integration testing** - Automated testing of build workflows

### Extension Points

- **Plugin system** - Custom build hooks and modifications
- **Custom backends** - Alternative build system support
- **Monitoring integration** - Integration with monitoring and alerting systems
- **CI/CD integration** - Continuous integration and deployment support