apt-ostree/docs/development/setup.md

Development Setup Guide

Project Status

✅ Current Achievements

apt-ostree has achieved significant milestones and is ready for development and testing:

• 100% rpm-ostree CLI Compatibility: All 21 core commands implemented with identical interfaces
• Real APT/OSTree Integration: Working package download, extraction, and commit creation
• OSTree Environment Detection: Comprehensive detection system with multiple validation methods
• Systemd Service Integration: Daemon and service management with D-Bus communication
• Atomic Operations: All changes are atomic with proper rollback support
• Error Handling: Robust error handling and user-friendly error messages

🔄 Current Focus Areas

• Systemd Services: Implementing additional service files (bootstatus, automatic updates)
• Testing Infrastructure: Building comprehensive test suite
• Performance Optimization: Optimizing package operations and filesystem assembly
• Documentation: Enhancing user and developer documentation

📋 Upcoming Features

• Container Support: Container and image support
• CI/CD Pipeline: Automated testing and release automation
• Advanced Features: Multi-arch support, security enhancements, performance optimizations

Prerequisites

System Requirements

• OS: Debian/Ubuntu-based system
• Rust: 1.70+ (edition 2021)
• Memory: 4GB+ RAM recommended
• Disk: 10GB+ free space

Required Dependencies

# Install system dependencies
sudo apt update
sudo apt install -y \
    build-essential \
    pkg-config \
    libapt-pkg-dev \
    libostree-dev \
    libdbus-1-dev \
    bubblewrap \
    systemd \
    git \
    curl

# Install Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
rustup default stable

Optional Development Tools

# Install development tools
sudo apt install -y \
    cargo-watch \
    cargo-audit \
    cargo-tarpaulin \
    clang-format \
    valgrind

# Install Rust development tools
cargo install cargo-watch
cargo install cargo-audit
cargo install cargo-tarpaulin

Project Setup

Clone Repository

git clone <repository-url>
cd apt-ostree

Build Project

# Build all targets
cargo build

# Build specific binary
cargo build --bin apt-ostree
cargo build --bin apt-ostreed

# Build with optimizations
cargo build --release

Run Tests

# Run all tests
cargo test

# Run specific test
cargo test test_name

# Run tests with output
cargo test -- --nocapture

# Run tests with logging
RUST_LOG=debug cargo test

Development Workflow

Code Quality

# Format code
cargo fmt

# Lint code
cargo clippy

# Check for security vulnerabilities
cargo audit

# Run code coverage
cargo tarpaulin

Development with Watch

# Watch for changes and rebuild
cargo watch -x build

# Watch for changes and run tests
cargo watch -x test

# Watch for changes and run specific binary
cargo watch -x 'run --bin apt-ostree -- status'

Debugging

Enable Debug Logging

# Set log level
export RUST_LOG=debug

# Run with debug logging
RUST_LOG=debug cargo run --bin apt-ostree -- status

Debug with GDB

# Build with debug symbols
cargo build

# Run with GDB
gdb target/debug/apt-ostree

Debug with LLDB

# Run with LLDB
lldb target/debug/apt-ostree

Testing

Unit Tests

# Run unit tests
cargo test

# Run specific module tests
cargo test apt
cargo test ostree
cargo test system

Integration Tests

# Run integration tests
cargo test --test integration

# Run with specific test data
RUST_TEST_DATA_DIR=/path/to/test/data cargo test

OSTree Detection Tests

# Run OSTree detection test script
./scripts/testing/test-ostree-detection.sh

Manual Testing

# Test CLI commands
cargo run --bin apt-ostree -- --help
cargo run --bin apt-ostree -- status
cargo run --bin apt-ostree -- daemon-ping

# Test daemon
cargo run --bin apt-ostreed

Daemon Development

Build and Install Daemon

# Build daemon
cargo build --bin apt-ostreed

# Install daemon
sudo cp target/debug/apt-ostreed /usr/bin/
sudo cp src/daemon/apt-ostreed.service /etc/systemd/system/
sudo cp src/daemon/org.aptostree.dev.conf /etc/dbus-1/system.d/

# Reload and start
sudo systemctl daemon-reload
sudo systemctl enable apt-ostreed
sudo systemctl start apt-ostreed

Test Daemon

# Check daemon status
sudo systemctl status apt-ostreed

# View daemon logs
sudo journalctl -u apt-ostreed -f

# Test D-Bus communication
cargo run --bin apt-ostree -- daemon-ping
cargo run --bin apt-ostree -- daemon-status

Debug Daemon

# Run daemon in foreground with debug logging
RUST_LOG=debug cargo run --bin apt-ostreed

# Test D-Bus interface
d-feet  # GUI D-Bus browser
gdbus introspect --system --dest org.aptostree.dev --object-path /org/aptostree/dev

Code Structure

Key Files

src/
├── main.rs              # CLI application entry point
├── lib.rs               # Library interface
├── apt.rs               # APT package management
├── ostree.rs            # OSTree operations
├── system.rs            # System integration
├── package_manager.rs   # High-level package operations
├── ostree_detection.rs  # Environment detection
├── permissions.rs       # Permission handling
├── error.rs             # Error types
└── bin/
    ├── apt-ostreed.rs   # D-Bus daemon
    └── test_runner.rs   # Test runner

Adding New Commands

1. Add command to Commands enum in src/main.rs
2. Add command options struct
3. Implement command logic in src/system.rs
4. Add tests in src/tests.rs
5. Update documentation

Adding New Modules

1. Create new module file in src/
2. Add module to src/lib.rs
3. Add module to src/main.rs if needed
4. Add tests
5. Update documentation

Troubleshooting

Common Issues

Build Errors

# Clean and rebuild
cargo clean
cargo build

# Update dependencies
cargo update
cargo build

Permission Errors

# Check file permissions
ls -la /usr/bin/apt-ostreed
ls -la /etc/systemd/system/apt-ostreed.service

# Fix permissions
sudo chmod 755 /usr/bin/apt-ostreed
sudo chmod 644 /etc/systemd/system/apt-ostreed.service

D-Bus Errors

# Check D-Bus policy
sudo cat /etc/dbus-1/system.d/org.aptostree.dev.conf

# Restart D-Bus
sudo systemctl restart dbus

# Restart daemon
sudo systemctl restart apt-ostreed

OSTree Errors

# Check OSTree installation
ostree --version

# Check OSTree repository
ostree log debian/stable/x86_64

# Initialize OSTree repository if needed
ostree init --repo=/path/to/repo

Debug Information

# Get system information
uname -a
lsb_release -a
rustc --version
cargo --version

# Check installed packages
dpkg -l | grep -E "(apt|ostree|dbus)"

# Check systemd services
systemctl list-units --type=service | grep apt-ostree

Performance Profiling

Memory Profiling

# Install memory profiler
cargo install memory-profiler

# Profile memory usage
cargo run --bin apt-ostree -- install package1 package2

CPU Profiling

# Install CPU profiler
cargo install flamegraph

# Generate flamegraph
cargo flamegraph --bin apt-ostree -- install package1 package2

Benchmarking

# Run benchmarks
cargo bench

# Run specific benchmark
cargo bench package_installation

Contributing

Code Style

• Follow Rust coding conventions
• Use cargo fmt for formatting
• Run cargo clippy for linting
• Add tests for new features
• Update documentation

Git Workflow

# Create feature branch
git checkout -b feature/new-feature

# Make changes
# ... edit files ...

# Add and commit changes
git add .
git commit -m "Add new feature"

# Push branch
git push origin feature/new-feature

# Create pull request
# ... create PR on GitHub ...

Testing Before Submission

# Run all tests
cargo test

# Run linting
cargo clippy

# Check formatting
cargo fmt --check

# Run security audit
cargo audit

# Build all targets
cargo build --all-targets