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
```bash
# 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
```bash
# 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
```bash
git clone <repository-url>
cd apt-ostree
```

### Build Project
```bash
# 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
```bash
# 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
```bash
# Format code
cargo fmt

# Lint code
cargo clippy

# Check for security vulnerabilities
cargo audit

# Run code coverage
cargo tarpaulin
```

### Development with Watch
```bash
# 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
```bash
# Set log level
export RUST_LOG=debug

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

#### Debug with GDB
```bash
# Build with debug symbols
cargo build

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

#### Debug with LLDB
```bash
# Run with LLDB
lldb target/debug/apt-ostree
```

## Testing

### Unit Tests
```bash
# Run unit tests
cargo test

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

### Integration Tests
```bash
# 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
```bash
# Run OSTree detection test script
./scripts/testing/test-ostree-detection.sh
```

### Manual Testing
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Clean and rebuild
cargo clean
cargo build

# Update dependencies
cargo update
cargo build
```

#### Permission Errors
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Install memory profiler
cargo install memory-profiler

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

### CPU Profiling
```bash
# Install CPU profiler
cargo install flamegraph

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

### Benchmarking
```bash
# 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
```bash
# 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
```bash
# 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
```