# AKMODS and DKMS Integration Architecture

## Overview

This document clarifies the role of DKMS in the AKMODS architecture, addressing the relationship between AKMODS (which creates pre-built packages) and DKMS (which builds modules on-demand).

## AKMODS vs DKMS: Complementary Approaches

### AKMODS Approach (Primary)
- **Pre-built Packages**: AKMODS creates fully compiled `.deb` packages with kernel modules
- **OCI Distribution**: Packages are distributed via container registry
- **Atomic Installation**: Direct installation via `dpkg` with atomic operations
- **No Runtime Compilation**: Modules are pre-compiled and ready to use

### DKMS Approach (Fallback)
- **On-demand Building**: DKMS builds modules when needed on the target system
- **Source Distribution**: Distributes source code and build instructions
- **Runtime Compilation**: Compiles modules against the running kernel
- **Traditional Method**: Standard approach for kernel modules

## AKMODS Architecture Clarification

### Build-Time DKMS Usage
```bash
# AKMODS build container uses DKMS for compilation
FROM ubuntu:24.04

# Install build dependencies including DKMS
RUN apt-get update && apt-get install -y \
    build-essential \
    linux-headers-generic \
    dkms \                    # ← DKMS used during build
    debhelper \
    dh-dkms \                 # ← DKMS packaging tools
    kernel-package \
    fakeroot

# AKMODS uses DKMS to compile modules in container
akmods-apt-daemon build-nvidia-akmods nvidia-driver-535 6.8.0-25-generic
├── 1. Extract .run file contents
├── 2. Apply kernel compatibility patches
├── 3. Use DKMS to compile modules    # ← DKMS used here
├── 4. Extract compiled .ko files
├── 5. Create DEB package
└── 6. Upload to registry
```

### Runtime Package Structure
```bash
# Final AKMODS package (NO DKMS runtime dependency)
kmod-nvidia-535-6.8.0-25-generic_535.154.05-1_amd64.deb
├── control.tar.gz
│   ├── control              # Package metadata
│   ├── postinst            # Post-installation script
│   └── prerm               # Pre-removal script
├── data.tar.gz
│   └── lib/modules/6.8.0-25-generic/extra/
│       ├── nvidia.ko       # ← Pre-compiled kernel module
│       ├── nvidia-modeset.ko
│       ├── nvidia-drm.ko
│       ├── nvidia-uvm.ko
│       └── nvidia-peermem.ko
└── debian-binary
```

### Corrected debian/control
```bash
# Corrected debian/control (removed DKMS runtime dependency)
Package: kmod-nvidia-535
Version: 535.154.05-1
Architecture: amd64
Depends: 
  linux-headers-generic,    # ← For module loading verification
  nvidia-settings,          # ← User-space utilities
  nvidia-prime              # ← GPU switching support
# Removed: dkms (not needed at runtime)
Description: NVIDIA proprietary drivers (535.154.05)
  Pre-compiled kernel modules for NVIDIA graphics drivers version 535.154.05.
  Supports RTX 40/30 series and compatible hardware.
```

## AKMODS Build Process with DKMS

### Step 1: DKMS Source Package Creation
```bash
# AKMODS creates DKMS-compatible source structure
akmods-apt-daemon create-dkms-source nvidia-driver-535 535.154.05
├── 1. Extract .run file contents
├── 2. Create DKMS source structure
│   ├── /usr/src/nvidia-driver-535-535.154.05/
│   │   ├── dkms.conf
│   │   ├── Makefile
│   │   ├── nvidia.c
│   │   ├── nvidia-modeset.c
│   │   └── ...
│   └── Apply kernel compatibility patches
└── 3. Prepare for DKMS compilation
```

### Step 2: DKMS Compilation in Container
```bash
# AKMODS uses DKMS to compile modules
akmods-apt-daemon compile-with-dkms nvidia-driver-535 6.8.0-25-generic
├── 1. Set up DKMS environment
│   ├── Install kernel headers
│   ├── Configure DKMS
│   └── Set up build environment
├── 2. DKMS compilation
│   ├── dkms add nvidia-driver-535/535.154.05
│   ├── dkms build nvidia-driver-535/535.154.05 -k 6.8.0-25-generic
│   └── dkms install nvidia-driver-535/535.154.05 -k 6.8.0-25-generic
├── 3. Extract compiled modules
│   ├── Copy .ko files from DKMS build directory
│   ├── Verify module compilation
│   └── Generate module metadata
└── 4. Clean up DKMS environment
    ├── dkms remove nvidia-driver-535/535.154.05 -k 6.8.0-25-generic
    └── Clean build artifacts
```

### Step 3: Package Creation (No DKMS)
```bash
# AKMODS creates DEB package without DKMS dependency
akmods-apt-daemon create-deb-package nvidia-driver-535
├── 1. Create DEB package structure
│   ├── Package compiled .ko files
│   ├── Add post-installation scripts
│   ├── Generate package metadata
│   └── Create package manifest
├── 2. Add installation scripts
│   ├── postinst: Load modules, update initramfs
│   ├── prerm: Unload modules, cleanup
│   └── triggers: Handle kernel updates
└── 3. Final package
    ├── kmod-nvidia-535-6.8.0-25-generic_535.154.05-1_amd64.deb
    └── Ready for distribution
```

## AKMODS vs DKMS: When to Use Each

### AKMODS (Recommended)
```bash
# Use AKMODS for:
# - Pre-built, tested packages
# - Fast installation
# - Atomic operations
# - Immutable system compatibility

apt-layer --akmods-install nvidia-driver-535
├── Download pre-built package from registry
├── Install via dpkg
├── Load kernel modules
└── Configure system
```

### DKMS (Fallback)
```bash
# Use DKMS for:
# - Custom kernel modules
# - Experimental drivers
# - Hardware not supported by AKMODS
# - Development and testing

apt-layer --dkms-install custom-module
├── Install DKMS source package
├── Build module on target system
├── Install compiled module
└── Configure module loading
```

## Hybrid Approach: AKMODS with DKMS Fallback

### Primary: AKMODS Pre-built Packages
```bash
# AKMODS primary workflow
akmods-apt-daemon install-nvidia nvidia-driver-535
├── 1. Check for pre-built package
│   ├── Query OCI registry
│   ├── Check kernel compatibility
│   └── Verify package availability
├── 2. Install pre-built package
│   ├── Download kmod-nvidia-535 package
│   ├── Install via dpkg
│   ├── Load kernel modules
│   └── Configure system
└── 3. Verify installation
    ├── Test module loading
    ├── Verify GPU functionality
    └── Log success
```

### Fallback: DKMS On-demand Building
```bash
# DKMS fallback when no pre-built package available
akmods-apt-daemon install-nvidia-fallback nvidia-driver-535
├── 1. Check for pre-built package (failed)
├── 2. Fall back to DKMS
│   ├── Install nvidia-driver-535-dkms package
│   ├── Build module with DKMS
│   ├── Install compiled module
│   └── Configure system
├── 3. Create AKMODS package for future use
│   ├── Extract compiled modules
│   ├── Create DEB package
│   ├── Upload to registry
│   └── Update package index
└── 4. Verify installation
    ├── Test module loading
    ├── Verify GPU functionality
    └── Log success
```

## AKMODS Configuration for DKMS Integration

### AKMODS Configuration
```yaml
# akmods.yaml with DKMS integration
module: nvidia-driver-535
version: "535.154.05"
description: "NVIDIA proprietary drivers (RTX 40/30 series)"

build:
  method: "dkms"              # ← Use DKMS for compilation
  dependencies:
    - "build-essential"
    - "linux-headers-generic"
    - "dkms"                  # ← Build-time dependency
    - "fakeroot"
    - "debhelper"
  
  dkms_config:
    enabled: true
    source_structure: "nvidia-run"
    patch_method: "kernel-compatibility"
    build_timeout: 3600
  
  runtime_dependencies:       # ← Runtime dependencies (no DKMS)
    - "linux-headers-generic"
    - "nvidia-settings"
    - "nvidia-prime"

distribution:
  method: "pre-built-deb"     # ← Distribute as pre-built package
  registry: "registry.particle-os.org/akmods"
  fallback: "dkms"            # ← Fallback to DKMS if needed
```

### DKMS Configuration File
```bash
# dkms.conf for AKMODS build process
PACKAGE_NAME="nvidia-driver-535"
PACKAGE_VERSION="535.154.05"
BUILT_MODULE_NAME[0]="nvidia"
BUILT_MODULE_NAME[1]="nvidia-modeset"
BUILT_MODULE_NAME[2]="nvidia-drm"
BUILT_MODULE_NAME[3]="nvidia-uvm"
BUILT_MODULE_NAME[4]="nvidia-peermem"

DEST_MODULE_LOCATION[0]="/kernel/drivers/video"
DEST_MODULE_LOCATION[1]="/kernel/drivers/video"
DEST_MODULE_LOCATION[2]="/kernel/drivers/gpu/drm"
DEST_MODULE_LOCATION[3]="/kernel/drivers/gpu"
DEST_MODULE_LOCATION[4]="/kernel/drivers/gpu"

AUTOINSTALL="yes"
MAKE[0]="make -C ${kernel_source_dir} M=${dkms_tree}/${PACKAGE_NAME}/${PACKAGE_VERSION}/build modules"
CLEAN="make -C ${kernel_source_dir} M=${dkms_tree}/${PACKAGE_NAME}/${PACKAGE_VERSION}/build clean"
```

## Benefits of This Architecture

### 1. **Best of Both Worlds**
- **AKMODS**: Fast, reliable, pre-built packages
- **DKMS**: Flexible, on-demand building when needed

### 2. **Reduced Complexity**
- **Build-time**: Use DKMS for reliable compilation
- **Runtime**: Simple package installation without DKMS overhead

### 3. **Fallback Safety**
- **Primary**: AKMODS pre-built packages
- **Fallback**: DKMS when pre-built packages unavailable

### 4. **Community Compatibility**
- **Leverage**: Existing DKMS infrastructure and expertise
- **Extend**: With AKMODS pre-built distribution

## Conclusion

The AKMODS architecture uses DKMS as a **build-time tool** for reliable kernel module compilation, but distributes **pre-built packages** that don't require DKMS at runtime. This approach:

1. **Leverages DKMS expertise** for compilation
2. **Eliminates runtime DKMS dependency** for faster installation
3. **Provides fallback mechanisms** when pre-built packages aren't available
4. **Maintains compatibility** with existing DKMS workflows

This clarification resolves the ambiguity identified by the reviewer and provides a clear, practical architecture that combines the strengths of both approaches.