deb-mock/docs/API.md

Deb-Mock API Reference

Overview

This document provides a comprehensive reference for the deb-mock API, including all classes, methods, and their usage. The API is designed to be intuitive and follows Python best practices.

Table of Contents

1. Core Classes
2. Configuration
3. Chroot Management
4. Cache Management
5. Sbuild Integration
6. Plugin System
7. Performance Monitoring
8. Benchmarking
9. Exceptions
10. CLI Interface
11. Examples

Core Classes

DebMock

The main class that orchestrates the build process.

from deb_mock.core import DebMock

# Initialize with configuration
deb_mock = DebMock(config)

# Build a package
result = deb_mock.build("package-name", "source-path")

# Get status
status = deb_mock.get_status()

# Cleanup
deb_mock.cleanup()

Methods

__init__(config)

Initialize a new DebMock instance.

Parameters:

• config: Configuration object or path to config file

Example:

from deb_mock.config import Config

config = Config.from_file("deb-mock.yaml")
deb_mock = DebMock(config)

build(package_name, source_path, **kwargs)

Build a package from source.

Parameters:

• package_name: Name of the package to build
• source_path: Path to the source package
• **kwargs: Additional build options

Options:

• chroot_name: Custom chroot name
• keep_chroot: Whether to keep chroot after build
• parallel: Enable parallel building
• clean_cache: Clean cache before building

Returns:

• BuildResult: Object containing build results

Example:

result = deb_mock.build(
    "my-package",
    "/path/to/source",
    chroot_name="custom-chroot",
    keep_chroot=True,
    parallel=True
)

print(f"Build successful: {result.success}")
print(f"Build duration: {result.duration:.2f}s")
print(f"Output files: {result.output_files}")

build_chain(packages, **kwargs)

Build multiple packages sequentially.

Parameters:

• packages: List of package specifications
• **kwargs: Additional build options

Example:

packages = [
    {"name": "package1", "source": "/path/to/pkg1"},
    {"name": "package2", "source": "/path/to/pkg2"},
    {"name": "package3", "source": "/path/to/pkg3"}
]

results = deb_mock.build_chain(packages, parallel=False)

build_parallel(packages, **kwargs)

Build multiple packages in parallel.

Parameters:

• packages: List of package specifications
• `kwargs: Additional build options

Example:

packages = [
    {"name": "package1", "source": "/path/to/pkg1"},
    {"name": "package2", "source": "/path/to/pkg2"},
    {"name": "package3", "source": "/path/to/pkg3"}
]

results = deb_mock.build_parallel(packages, max_workers=4)

get_status()

Get current status of the deb-mock instance.

Returns:

• dict: Status information

Example:

status = deb_mock.get_status()
print(f"Active chroots: {status['chroot_manager']['chroots']}")
print(f"Cache status: {status['cache_manager']['caches']}")
print(f"Performance monitoring: {status['performance_monitor']['enabled']}")

cleanup()

Clean up resources and temporary files.

Example:

deb_mock.cleanup()

Configuration

Config

Configuration management class.

from deb_mock.config import Config

# Load from file
config = Config.from_file("deb-mock.yaml")

# Load from dictionary
config = Config.from_dict({
    "chroot": {"suite": "trixie", "architecture": "amd64"},
    "cache": {"enabled": True}
})

# Access configuration values
suite = config.chroot.suite
cache_enabled = config.cache.enabled

Configuration Schema

chroot:
  base_dir: /var/lib/deb-mock/chroots
  suite: trixie
  architecture: amd64
  mirror: http://deb.debian.org/debian/
  components: [main, contrib, non-free]

cache:
  enabled: true
  base_dir: /var/cache/deb-mock
  ccache_size_mb: 2048
  root_cache_size_mb: 5120
  package_cache_size_mb: 1024

sbuild:
  enabled: true
  user: sbuild
  group: sbuild
  chroot_suffix: -sbuild
  build_user: buildd

performance:
  enable_performance_monitoring: true
  performance_metrics_dir: ./performance-metrics
  performance_retention_days: 30
  performance_auto_optimization: true
  performance_benchmark_iterations: 10
  performance_reporting: true

plugins:
  enabled: true
  plugin_dir: ./plugins
  auto_load: true

parallel:
  enabled: true
  max_parallel_builds: 4
  max_parallel_chroots: 8

mounts:
  proc: true
  sys: true
  dev: true
  tmpfs: true
  bind_mounts:
    - source: /var/cache/apt/archives
      target: /var/cache/apt/archives
      options: [ro]
  overlay_mounts:
    - source: /var/cache/deb-mock/overlay
      target: /var/cache/deb-mock/overlay

uid_management:
  enabled: true
  create_users: true
  copy_host_users: true
  privilege_escalation: true

Chroot Management

ChrootManager

Manages chroot environments for builds.

from deb_mock.chroot import ChrootManager

chroot_manager = ChrootManager(config)

# Create a new chroot
chroot = chroot_manager.create_chroot("trixie-amd64")

# List existing chroots
chroots = chroot_manager.list_chroots()

# Clean up chroot
chroot_manager.cleanup_chroot("trixie-amd64")

Methods

create_chroot(name, suite=None, architecture=None)

Create a new chroot environment.

Parameters:

• name: Name for the chroot
• suite: Debian suite (defaults to config)
• architecture: Architecture (defaults to config)

Returns:

• Chroot: Chroot instance

Example:

chroot = chroot_manager.create_chroot(
    "trixie-amd64",
    suite="trixie",
    architecture="amd64"
)

get_chroot(name)

Get an existing chroot by name.

Parameters:

• name: Chroot name

Returns:

• Chroot: Chroot instance or None

Example:

chroot = chroot_manager.get_chroot("trixie-amd64")
if chroot:
    print(f"Chroot exists: {chroot.path}")

list_chroots()

List all available chroots.

Returns:

• list: List of chroot names

Example:

chroots = chroot_manager.list_chroots()
for chroot_name in chroots:
    print(f"Available chroot: {chroot_name}")

cleanup_chroot(name)

Remove a chroot environment.

Parameters:

• name: Chroot name

Example:

chroot_manager.cleanup_chroot("trixie-amd64")

Cache Management

CacheManager

Manages build caches for improved performance.

from deb_mock.cache import CacheManager

cache_manager = CacheManager(config)

# Create cache
cache = cache_manager.create_cache("package-name")

# Restore cache
success = cache_manager.restore_cache("package-name")

# Clean cache
cache_manager.clean_cache("package-name")

Methods

create_cache(package_name)

Create a cache for a package.

Parameters:

• package_name: Name of the package

Returns:

• Cache: Cache instance

Example:

cache = cache_manager.create_cache("my-package")

restore_cache(package_name)

Restore cache for a package.

Parameters:

• package_name: Name of the package

Returns:

• bool: True if restoration was successful

Example:

if cache_manager.restore_cache("my-package"):
    print("Cache restored successfully")
else:
    print("Cache restoration failed")

clean_cache(package_name)

Clean cache for a package.

Parameters:

• package_name: Name of the package

Example:

cache_manager.clean_cache("my-package")

Sbuild Integration

SbuildWrapper

Wrapper for sbuild integration.

from deb_mock.sbuild import SbuildWrapper

sbuild = SbuildWrapper(config)

# Check sbuild availability
if sbuild.is_available():
    print("Sbuild is available")
else:
    print("Sbuild is not available")

# Build a package
result = sbuild.build_package("source.dsc", chroot_name="trixie-amd64")

Methods

is_available()

Check if sbuild is available and properly configured.

Returns:

• bool: True if sbuild is available

Example:

if sbuild.is_available():
    print("Sbuild is ready to use")
else:
    print("Sbuild needs configuration")

build_package(source_path, chroot_name=None, **kwargs)

Build a package using sbuild.

Parameters:

• source_path: Path to source package
• chroot_name: Chroot to use for building
• **kwargs: Additional build options

Returns:

• SbuildResult: Build result

Example:

result = sbuild.build_package(
    "/path/to/package.dsc",
    chroot_name="trixie-amd64",
    verbose=True
)

if result.success:
    print(f"Build successful: {result.output_files}")
else:
    print(f"Build failed: {result.error}")

update_chroot(chroot_name)

Update a chroot with latest packages.

Parameters:

• chroot_name: Name of the chroot to update

Returns:

• bool: True if update was successful

Example:

if sbuild.update_chroot("trixie-amd64"):
    print("Chroot updated successfully")

Plugin System

PluginManager

Manages plugins and their lifecycle.

from deb_mock.plugin import PluginManager

plugin_manager = PluginManager(config)

# Load plugins
plugin_manager.load_plugins()

# Get plugin information
plugins = plugin_manager.list_plugins()

# Enable/disable plugins
plugin_manager.enable_plugin("ccache_plugin")
plugin_manager.disable_plugin("debug_plugin")

Methods

load_plugins()

Load all available plugins.

Example:

plugin_manager.load_plugins()
print(f"Loaded {len(plugin_manager.plugins)} plugins")

list_plugins()

List all available plugins.

Returns:

• list: List of plugin information

Example:

plugins = plugin_manager.list_plugins()
for plugin in plugins:
    print(f"Plugin: {plugin['name']} - Status: {plugin['status']}")

enable_plugin(plugin_name)

Enable a specific plugin.

Parameters:

• plugin_name: Name of the plugin to enable

Returns:

• bool: True if plugin was enabled

Example:

if plugin_manager.enable_plugin("ccache_plugin"):
    print("CCache plugin enabled")

disable_plugin(plugin_name)

Disable a specific plugin.

Parameters:

• plugin_name: Name of the plugin to disable

Returns:

• bool: True if plugin was disabled

Example:

if plugin_manager.disable_plugin("debug_plugin"):
    print("Debug plugin disabled")

BasePlugin

Base class for creating custom plugins.

from deb_mock.plugin import BasePlugin, HookStages

class MyCustomPlugin(BasePlugin):
    name = "my_custom_plugin"
    version = "1.0.0"
    description = "A custom plugin for deb-mock"
    
    def __init__(self):
        super().__init__()
        self.register_hook(HookStages.PRE_BUILD, self.pre_build_hook)
        self.register_hook(HookStages.POST_BUILD, self.post_build_hook)
    
    def pre_build_hook(self, context):
        print("Pre-build hook executed")
        return context
    
    def post_build_hook(self, context):
        print("Post-build hook executed")
        return context

Hook Stages

• PRE_CHROOT_CREATE: Before chroot creation
• POST_CHROOT_CREATE: After chroot creation
• PRE_BUILD: Before build starts
• POST_BUILD: After build completes
• PRE_CACHE_RESTORE: Before cache restoration
• POST_CACHE_RESTORE: After cache restoration
• PRE_CLEANUP: Before cleanup
• POST_CLEANUP: After cleanup

Performance Monitoring

PerformanceMonitor

Monitors and tracks performance metrics.

from deb_mock.performance import PerformanceMonitor

monitor = PerformanceMonitor(config)

# Start monitoring
monitor.start_monitoring()

# Monitor an operation
with monitor.monitor_operation("build_operation"):
    # Your operation here
    pass

# Get performance summary
summary = monitor.get_performance_summary()

Methods

start_monitoring()

Start system monitoring.

Example:

monitor.start_monitoring()

stop_monitoring()

Stop system monitoring.

Example:

monitor.stop_monitoring()

monitor_operation(operation_name)

Context manager for monitoring operations.

Parameters:

• operation_name: Name of the operation to monitor

Example:

with monitor.monitor_operation("package_build"):
    # Build operation
    result = build_package()

get_performance_summary()

Get a summary of performance metrics.

Returns:

• dict: Performance summary

Example:

summary = monitor.get_performance_summary()
print(f"Total operations: {summary['total_operations']}")
print(f"Average duration: {summary['average_duration']:.2f}s")

create_build_profile(build_id, package_name, architecture, suite)

Create a build performance profile.

Parameters:

• build_id: Unique build identifier
• package_name: Name of the package
• architecture: Build architecture
• suite: Debian suite

Returns:

• BuildProfile: Build profile instance

Example:

profile = monitor.create_build_profile(
    "build-123",
    "my-package",
    "amd64",
    "trixie"
)

PerformanceOptimizer

Provides optimization suggestions based on performance data.

from deb_mock.performance import PerformanceOptimizer

optimizer = PerformanceOptimizer(config)

# Analyze build performance
analysis = optimizer.analyze_build_performance(profile)

# Get optimization suggestions
suggestions = optimizer.get_optimization_suggestions(profile)

Methods

analyze_build_performance(profile)

Analyze build performance for optimization opportunities.

Parameters:

• profile: BuildProfile instance

Returns:

• dict: Performance analysis

Example:

analysis = optimizer.analyze_build_performance(profile)
print(f"Optimization score: {analysis['optimization_score']}")

get_optimization_suggestions(profile)

Get optimization suggestions for a build profile.

Parameters:

• profile: BuildProfile instance

Returns:

• list: List of optimization suggestions

Example:

suggestions = optimizer.get_optimization_suggestions(profile)
for suggestion in suggestions:
    print(f"Suggestion: {suggestion}")

PerformanceReporter

Generates performance reports and visualizations.

from deb_mock.performance import PerformanceReporter

reporter = PerformanceReporter(config)

# Generate performance report
report_path = reporter.generate_performance_report(monitor)

# Generate build profile report
profile_report = reporter.generate_build_profile_report(profile)

Methods

generate_performance_report(monitor, output_file=None)

Generate a comprehensive performance report.

Parameters:

• monitor: PerformanceMonitor instance
• output_file: Output file path (optional)

Returns:

• str: Path to generated report

Example:

report_path = reporter.generate_performance_report(monitor)
print(f"Report generated: {report_path}")

generate_build_profile_report(profile, output_file=None)

Generate a build profile report.

Parameters:

• profile: BuildProfile instance
• output_file: Output file path (optional)

Returns:

• str: Path to generated report

Example:

profile_report = reporter.generate_build_profile_report(profile)
print(f"Profile report generated: {profile_report}")

Benchmarking

BenchmarkRunner

Runs performance benchmarks for operations.

from deb_mock.benchmarking import BenchmarkRunner

runner = BenchmarkRunner(config)

# Run a benchmark
result = runner.run_benchmark(
    "build_benchmark",
    build_function,
    iterations=20
)

# Compare benchmarks
comparison = runner.compare_benchmarks(["benchmark1", "benchmark2"])

Methods

run_benchmark(benchmark_name, operation_func, **kwargs)

Run a benchmark for a specific operation.

Parameters:

• benchmark_name: Name of the benchmark
• operation_func: Function to benchmark
• **kwargs: Benchmark configuration

Returns:

• BenchmarkResult: Benchmark result

Example:

def build_operation():
    # Build operation to benchmark
    pass

result = runner.run_benchmark(
    "build_benchmark",
    build_operation,
    iterations=50,
    parallel_runs=4
)

print(f"Average duration: {result.average_duration:.3f}s")
print(f"Standard deviation: {result.standard_deviation:.3f}s")

compare_benchmarks(benchmark_names)

Compare multiple benchmark results.

Parameters:

• benchmark_names: List of benchmark names to compare

Returns:

• dict: Comparison results

Example:

comparison = runner.compare_benchmarks(["quick", "standard", "comprehensive"])
print(f"Fastest benchmark: {comparison['analysis']['fastest_benchmark']}")
print(f"Most stable: {comparison['analysis']['most_stable_benchmark']}")

Exceptions

DebMockError

Base exception for deb-mock errors.

from deb_mock.exceptions import DebMockError

try:
    # Some operation
    pass
except DebMockError as e:
    print(f"Deb-mock error: {e}")

ChrootError

Exception raised for chroot-related errors.

from deb_mock.exceptions import ChrootError

try:
    chroot_manager.create_chroot("invalid-name")
except ChrootError as e:
    print(f"Chroot error: {e}")

CacheError

Exception raised for cache-related errors.

from deb_mock.exceptions import CacheError

try:
    cache_manager.restore_cache("package-name")
except CacheError as e:
    print(f"Cache error: {e}")

PerformanceError

Exception raised for performance monitoring errors.

from deb_mock.exceptions import PerformanceError

try:
    monitor.start_monitoring()
except PerformanceError as e:
    print(f"Performance error: {e}")

PluginError

Exception raised for plugin-related errors.

from deb_mock.exceptions import PluginError

try:
    plugin_manager.load_plugins()
except PluginError as e:
    print(f"Plugin error: {e}")

CLI Interface

The deb-mock command-line interface provides access to all functionality.

Basic Commands

# Get help
deb-mock --help

# Show version
deb-mock --version

# Show status
deb-mock status

# Build a package
deb-mock build package-name source-path

# List chroots
deb-mock list-chroots

# Create chroot
deb-mock create-chroot --suite trixie --architecture amd64

# Cleanup
deb-mock cleanup

Performance Commands

# Performance summary
deb-mock performance-summary

# Performance report
deb-mock performance-report

# Run benchmark
deb-mock benchmark --template standard

# Performance analysis
deb-mock performance-analysis

Plugin Commands

# List plugins
deb-mock plugin list

# Enable plugin
deb-mock plugin enable ccache_plugin

# Disable plugin
deb-mock plugin disable debug_plugin

# Plugin info
deb-mock plugin info ccache_plugin

Sbuild Commands

# Check sbuild status
deb-mock sbuild status

# Update chroot
deb-mock sbuild update-chroot trixie-amd64

# Build package
deb-mock sbuild build-package source.dsc

Examples

Complete Build Example

from deb_mock.core import DebMock
from deb_mock.config import Config

# Load configuration
config = Config.from_file("deb-mock.yaml")

# Initialize deb-mock
deb_mock = DebMock(config)

try:
    # Build a package
    result = deb_mock.build(
        "my-package",
        "/path/to/source",
        chroot_name="trixie-amd64",
        parallel=True
    )
    
    if result.success:
        print(f"Build successful in {result.duration:.2f}s")
        print(f"Output files: {result.output_files}")
    else:
        print(f"Build failed: {result.error}")
        
finally:
    # Cleanup
    deb_mock.cleanup()

Performance Monitoring Example

from deb_mock.performance import PerformanceMonitor, PerformanceReporter

monitor = PerformanceMonitor(config)
reporter = PerformanceReporter(config)

# Start monitoring
monitor.start_monitoring()

try:
    # Monitor build operation
    with monitor.monitor_operation("package_build"):
        # Build operation
        result = build_package()
    
    # Generate performance report
    report_path = reporter.generate_performance_report(monitor)
    print(f"Performance report: {report_path}")
    
finally:
    # Stop monitoring
    monitor.stop_monitoring()

Plugin Development Example

from deb_mock.plugin import BasePlugin, HookStages

class BuildNotificationPlugin(BasePlugin):
    name = "build_notification"
    version = "1.0.0"
    description = "Sends notifications on build completion"
    
    def __init__(self):
        super().__init__()
        self.register_hook(HookStages.POST_BUILD, self.notify_build_complete)
    
    def notify_build_complete(self, context):
        if context.get('build_success'):
            print(f"✅ Build completed successfully for {context['package_name']}")
        else:
            print(f"❌ Build failed for {context['package_name']}")
        return context

# Plugin will be automatically loaded if placed in plugin directory

Benchmarking Example

from deb_mock.benchmarking import BenchmarkRunner

runner = BenchmarkRunner(config)

def build_operation():
    # Simulate build operation
    import time
    time.sleep(1)
    return {"success": True}

# Run comprehensive benchmark
result = runner.run_benchmark(
    "build_benchmark",
    build_operation,
    iterations=100,
    parallel_runs=4
)

print(f"Benchmark completed:")
print(f"  Iterations: {result.iterations}")
print(f"  Average duration: {result.average_duration:.3f}s")
print(f"  Standard deviation: {result.standard_deviation:.3f}s")
print(f"  Performance stability: {result.analysis['performance_stability']}")

Conclusion

This API reference provides comprehensive coverage of all deb-mock functionality. For additional examples and advanced usage patterns, refer to the main documentation and plugin examples.

The API is designed to be intuitive and follows Python best practices, making it easy to integrate deb-mock into existing build systems and workflows.