apt-layer/README-C.md

apt-layer C Implementation

This is the C implementation of the apt-layer tool, following the refactor plan outlined in refactor.md. This implementation provides a foundation for the build-time tool (Phase 1) with the goal of eventually supporting end-user transactional layering (Phase 2).

Project Structure

apt-layer/
├── src/                    # Source files
│   ├── main.c             # Entry point and command routing
│   ├── cli.c              # Command line interface
│   ├── log.c              # Logging system
│   ├── config.c           # Configuration management
│   ├── utils.c            # Utility functions
│   ├── deps.c             # Dependency checking
│   ├── ostree.c           # OSTree operations
│   ├── layer.c            # Layer creation logic
│   ├── apt.c              # Package management
│   └── container.c        # Container operations
├── include/               # Header files
│   └── apt_layer.h        # Main header with all declarations
├── tests/                 # Test files
│   └── run_tests.sh       # Basic test script
├── Makefile               # Build system (Linux/macOS)
├── build.bat              # Build script (Windows)
├── README-C.md            # This file
└── README.md              # Original project README

Building

Prerequisites

• GCC compiler (or compatible C compiler)
• Make (for Linux/macOS builds)
• OSTree development libraries (for full functionality)

Linux/macOS

# Build the project
make

# Build with debug information
make debug

# Clean build artifacts
make clean

# Run tests
make test

Windows

# Build using the batch script
build.bat

# Or manually with GCC
gcc -Wall -Wextra -std=c99 -g -O2 -Iinclude -o bin/apt-layer.exe src/*.c

Usage

The C implementation provides the same command-line interface as the shell script version:

# Show help
./bin/apt-layer --help

# Show version
./bin/apt-layer --version

# List branches
./bin/apt-layer --list

# Show branch information
./bin/apt-layer --info <branch>

# Create a layer
./bin/apt-layer <base-branch> <new-branch> [packages...]

# Create container-based layer
./bin/apt-layer --container <base-branch> <new-branch> [packages...]

# Export as OCI image
./bin/apt-layer --oci-export <branch> <image-name>

Features Implemented

Phase 1 (Build-Time Tool) - ✅ Complete

• CLI Interface - Full argument parsing with getopt
• Logging System - Colored output with different log levels
• Configuration Management - Environment variables and config files
• Dependency Checking - Verify required tools are available
• OSTree Operations - Basic repository management
• Layer Creation - Traditional and container-based approaches
• Package Management - APT integration via chroot
• Container Support - Podman/Docker integration
• OCI Export - Export OSTree branches as container images
• Error Handling - Comprehensive error codes and messages

Phase 2 (End-User Layering) - 🔄 Planned

• libapt-pkg Integration - Direct package management
• Transactional Operations - Atomic layer installation
• Rollback System - Layer history and recovery
• Live System Integration - OSTree admin operations
• User Session Handling - Prompts and confirmations

Configuration

The C implementation supports the same configuration options as the shell script:

Environment Variables

export OSTREE_REPO="/workspace/cache/ostree-repo"
export BUILD_DIR="/workspace/cache/build"
export CONTAINER_RUNTIME="podman"
export LOG_LEVEL="info"

Configuration File

Create ~/.config/apt-layer/config:

OSTREE_REPO=/workspace/cache/ostree-repo
BUILD_DIR=/workspace/cache/build
CONTAINER_RUNTIME=podman
LOG_LEVEL=info

Testing

Run the basic test suite:

# Run tests
make test

# Or manually
cd tests
./run_tests.sh

Development

Adding New Features

1. Add function declarations to include/apt_layer.h
2. Implement the function in the appropriate source file
3. Add command handling in src/main.c if needed
4. Update CLI parsing in src/cli.c for new options
5. Add tests to tests/run_tests.sh

Code Style

• Use C99 standard
• Follow the existing naming conventions
• Add proper error handling
• Include debug logging for complex operations
• Document public functions in the header file

Debugging

Enable debug output:

# Build with debug symbols
make debug

# Run with debug logging
LOG_LEVEL=debug ./bin/apt-layer --help

Limitations

Current Limitations

1. Platform Support - Designed for Linux systems with OSTree
2. Package Management - Uses chroot/apt-get (not libapt-pkg yet)
3. Rollback - Basic implementation, not fully transactional
4. Dependencies - Requires external tools (ostree, apt-get, etc.)

Windows Considerations

The C implementation can be compiled on Windows, but:

• OSTree operations won't work (Linux-specific)
• Container operations may be limited
• Package management requires WSL or similar
• Some system calls are Unix-specific

Roadmap

Short Term (Phase 1 Completion)

• Improve error handling and recovery
• Add recipe file support (YAML/JSON)
• Enhance logging and progress reporting
• Add unit tests for individual modules
• Optimize performance for large repositories

Medium Term (Phase 2 Foundation)

• Research and prototype libapt-pkg integration
• Design transactional data structures
• Implement layer history tracking
• Add atomic operation support
• Develop rollback mechanisms

Long Term (Phase 2 Implementation)

• Full libapt-pkg integration
• Live system layering
• User session management
• Advanced rollback system
• TUI interface (optional)

Contributing

1. Follow the existing code structure
2. Add tests for new functionality
3. Update documentation
4. Ensure compatibility with the refactor plan
5. Test on both Linux and Windows (where applicable)

License

Same as the main project - see LICENSE file for details.