apt-ostree/docs/apt-ostree-daemon-plan/implementation/getting-started.md

🚀 Getting Started with apt-ostree Development

📋 Prerequisites

Before you begin developing apt-ostree, ensure you have the following installed:

System Requirements

• Operating System: Debian 13 (Trixie) or Ubuntu 25.04 (Plucky Puffin)
• Architecture: x86_64 (amd64)
• Kernel: Linux 6.12+ (for OSTree support)

Development Tools

# Essential build tools
sudo apt update
sudo apt install build-essential pkg-config cmake

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

# OSTree development libraries
sudo apt install libostree-dev libgirepository1.0-dev

# APT development libraries
sudo apt install libapt-pkg-dev libapt-pkg5.0

# DBus and Polkit development
sudo apt install libdbus-1-dev libpolkit-gobject-1-dev

# Additional dependencies
sudo apt install libsystemd-dev libseccomp-dev libcap-dev

Optional Tools

# Development utilities
sudo apt install git clang-format rustfmt cargo-audit

# Documentation tools
sudo apt install pandoc graphviz

# Testing tools
sudo apt install valgrind gdb

🏗️ Project Structure Overview

apt-ostree/
├── src/                          # Source code
│   ├── main.rs                   # CLI client entry point
│   ├── commands/                 # Command implementations
│   ├── daemon/                   # Daemon implementation
│   ├── client/                   # Client library
│   └── lib/                      # Shared library code
├── daemon/                       # Daemon-specific files
├── docs/                         # Documentation
└── tests/                        # Test suites

🚀 Quick Start Development

1. Clone and Setup

# Clone the repository
git clone <repository-url>
cd apt-ostree

# Install dependencies
cargo build --dependencies

# Verify setup
cargo check

2. First Build

# Build the project
cargo build

# Run basic tests
cargo test

# Check for issues
cargo clippy
cargo audit

3. Development Environment

# Set up development environment
export APT_OSTREE_DEV=1
export RUST_LOG=debug

# Run with development configuration
cargo run -- --help

🔧 Development Workflow

Understanding the Codebase

1. Start with the CLI: Review src/main.rs to understand command structure
2. Explore Commands: Check src/commands/ for specific command implementations
3. Daemon Architecture: Review src/daemon/ for server-side logic
4. Library Code: Examine src/lib/ for shared functionality

Key Development Patterns

Command Implementation

// src/commands/example.rs
use crate::BaseCommand;

pub struct ExampleCommand;

impl BaseCommand for ExampleCommand {
    fn name(&self) -> &'static str { "example" }
    
    fn description(&self) -> &'static str {
        "Example command implementation"
    }
    
    async fn execute(&self, args: &[String]) -> AptOstreeResult<()> {
        // Command implementation
        Ok(())
    }
}

Daemon Integration

// src/daemon/example.rs
use crate::daemon::DaemonManager;

impl DaemonManager {
    pub async fn handle_example_request(
        &self,
        request: ExampleRequest,
    ) -> Result<ExampleResponse, Error> {
        // Handle request
        Ok(ExampleResponse::new())
    }
}

🧪 Testing Your Changes

Unit Tests

# Run all tests
cargo test

# Run specific test
cargo test test_example_command

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

Integration Tests

# Run integration tests
cargo test --test integration

# Run with specific features
cargo test --features integration-tests

System Tests

# Run system tests (requires root)
sudo cargo test --test system

# Run in container
cargo test --test container

🔍 Debugging and Troubleshooting

Common Issues

Build Failures

# Clean and rebuild
cargo clean
cargo build

# Check dependencies
cargo tree

# Verify Rust version
rustc --version

Runtime Errors

# Enable debug logging
export RUST_LOG=debug
export RUST_BACKTRACE=1

# Run with verbose output
cargo run -- --verbose

Permission Issues

# Check Polkit policies
pkaction --action org.projectatomic.aptostree.status

# Verify systemd service
systemctl status aptostreed

Debugging Tools

GDB Integration

# Build with debug symbols
cargo build --debug

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

Valgrind Memory Checking

# Run with Valgrind
valgrind --leak-check=full cargo run -- --help

📚 Learning Resources

Core Concepts

• OSTree Documentation - OSTree fundamentals
• APT Development - APT package management
• DBus Tutorial - DBus communication
• Polkit Documentation - Authorization framework

Related Projects

• rpm-ostree - Reference implementation
• debian-atomic - Debian OSTree images
• systemd - System and service management

Rust Ecosystem

• Rust Book - Rust programming language
• Tokio - Async runtime
• Serde - Serialization framework

🎯 Next Steps

For New Developers

1. Complete the tutorial: Follow this guide step by step
2. Explore the codebase: Review the architecture documents
3. Run examples: Try the provided examples and tests
4. Join the community: Participate in discussions and reviews

For Experienced Developers

1. Review architecture: Understand the system design
2. Identify areas: Find areas for improvement or new features
3. Submit proposals: Propose enhancements or new features
4. Contribute code: Submit pull requests and patches

For System Administrators

1. Test deployment: Try deploying apt-ostree in test environments
2. Provide feedback: Report issues and suggest improvements
3. Document usage: Share deployment experiences and best practices

🤝 Getting Help

Development Questions

• Architecture: Check the relevant architecture documents
• Implementation: Review the implementation guides
• Code Examples: Look at existing command implementations

Community Support

• Issues: Report bugs and feature requests
• Discussions: Participate in design discussions
• Contributions: Submit patches and improvements

Documentation

• This Guide: Start here for development setup
• Architecture Docs: Detailed system architecture
• API Reference: Complete interface documentation

---

This getting started guide provides the foundation for developing apt-ostree. Follow the steps, explore the codebase, and don't hesitate to ask questions or contribute improvements.