APT-DNF Bridge

A DNF-like bridge around APT for apt-ostree integration. This workspace provides a transaction-based API that makes APT work like DNF.

🎯 Two-Crate Approach

This workspace implements the refined two-crate approach with feature flags:

• apt-dnf-bridge-core - Minimal shell-out implementation
• apt-dnf-bridge - Main crate that re-exports core + optional advanced features
• apt-dnf-bridge-advanced - Pluggable backends, caching, and enhanced features

🚀 Quick Start

Core (Minimal)

[dependencies]
apt-dnf-bridge = "0.1"

Advanced Features

[dependencies]
apt-dnf-bridge = { version = "0.1", features = ["advanced"] }

📁 Workspace Structure

apt-dnf-bridge-workspace/
├── Cargo.toml                    # Workspace root
├── apt-dnf-bridge-core/          # Minimal implementation
│   ├── Cargo.toml
│   └── src/
│       ├── lib.rs
│       ├── command.rs
│       ├── error.rs
│       ├── package.rs
│       ├── repository.rs
│       └── transaction.rs
├── apt-dnf-bridge/               # Main public crate
│   ├── Cargo.toml
│   └── src/
│       └── lib.rs
├── apt-dnf-bridge-advanced/      # Advanced features
│   ├── Cargo.toml
│   └── src/
│       ├── lib.rs
│       ├── backend.rs
│       ├── package_v2.rs
│       ├── transaction_v2.rs
│       └── backend/
│           ├── shell_backend.rs
│           ├── mock_backend.rs
│           └── libapt_backend.rs
└── examples/                     # Shared examples
    ├── basic_usage.rs
    ├── package_query.rs
    ├── atomicity_notes.rs
    └── backend_selection.rs

🔧 Usage Examples

Basic Usage (Core Only)

use apt_dnf_bridge::{Transaction, Package, Repository};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a transaction
    let mut tx = Transaction::new();
    
    // Add packages to install
    let vim = Package::new("vim", "2:8.1.2269-1ubuntu5.14", "amd64");
    tx.add_install(vim).await?;
    
    // Resolve dependencies (APT handles automatically)
    tx.resolve().await?;
    
    // Commit the transaction
    tx.commit().await?;
    
    Ok(())
}

Advanced Usage (With Backends)

use apt_dnf_bridge::{TransactionV2, PackageDatabaseV2, BackendFactory};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create transaction with auto-detected backend
    let mut tx = TransactionV2::new().await?;
    
    // Add packages
    let vim = Package::new("vim", "2:8.1.2269-1ubuntu5.14", "amd64");
    tx.add_install(vim).await?;
    
    // Resolve and commit
    tx.resolve().await?;
    tx.commit().await?;
    
    Ok(())
}

🏗️ Building and Testing

Build All Crates

cargo build

Test Core Features

cargo test -p apt-dnf-bridge-core

Test Advanced Features

cargo test -p apt-dnf-bridge-advanced

Run Examples

# Core examples
cargo run --example basic_usage
cargo run --example package_query

# Advanced examples (requires advanced feature)
cargo run --example backend_selection --features advanced

🎯 Feature Flags

Core Features (Default)

• Shell-out APT commands
• Basic transaction model
• Package querying
• Repository management
• Error handling

Advanced Features (advanced feature)

• Pluggable backends (shell, mock, libapt)
• Caching system
• Enhanced error handling
• Backend statistics
• Mock backend for testing

🔄 Migration Guide

From Single Crate to Workspace

1. Core users: No changes needed - same API
2. Advanced users: Add features = ["advanced"] to Cargo.toml
3. New users: Start with core, add advanced when needed

API Compatibility

• Core API remains unchanged
• Advanced API available via feature flag
• Gradual adoption path supported

📚 Documentation

• Core API: Focus on simplicity and reliability
• Advanced API: Focus on power and flexibility
• Examples: Demonstrate both core and advanced usage
• Migration: Guide for moving between feature levels

🚀 Benefits of This Approach

1. Single Crate - No confusion about which to use
2. Feature Flags - Users choose complexity level
3. Workspace - Easy version coordination
4. Re-exports - Clean API surface
5. Gradual Adoption - Start simple, add complexity when needed
6. Clear Documentation - One README with feature explanations

This approach gives us all the benefits of the two-crate strategy with much better UX and maintenance.