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

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

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

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

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

Dependency Management

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

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

Package Building

# 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

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:

sudo sbuild-adduser $USER
newgrp sbuild  # or start new shell session

2. Sbuild Not Found

Error: sbuild not found. Please install sbuild package

Solution:

sudo apt-get install sbuild

3. Chroot Not Available

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

Solution:

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

# 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

# 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

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

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