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

```bash
# Build the project
make

# Build with debug information
make debug

# Clean build artifacts
make clean

# Run tests
make test
```

### Windows

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

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

- [x] **CLI Interface** - Full argument parsing with getopt
- [x] **Logging System** - Colored output with different log levels
- [x] **Configuration Management** - Environment variables and config files
- [x] **Dependency Checking** - Verify required tools are available
- [x] **OSTree Operations** - Basic repository management
- [x] **Layer Creation** - Traditional and container-based approaches
- [x] **Package Management** - APT integration via chroot
- [x] **Container Support** - Podman/Docker integration
- [x] **OCI Export** - Export OSTree branches as container images
- [x] **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

```bash
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`:

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

## Testing

Run the basic test suite:

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

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