deb-bootupd/PACKAGING.md

# 📦 Debian Packaging Guide for deb-bootupd

This guide explains how to build, test, and distribute proper Debian packages for `deb-bootupd`.

## **🏗️ Package Structure**

Your Debian package now includes all required components:

```
debian/
├── control          # Package metadata and dependencies
├── rules            # Build instructions
├── changelog        # Version history
├── copyright        # License information
├── install          # File installation mapping
├── dirs             # Directory creation
├── postinst         # Post-installation script
├── prerm            # Pre-removal script
└── postrm           # Post-removal script
```

## **🔨 Building the Package**

### **Prerequisites**

Install required build tools:

```bash
sudo apt-get update
sudo apt-get install build-essential devscripts dh-cargo dh-systemd lintian
```

### **Quick Build**

Use the automated build script:

```bash
./build-deb.sh
```

This will:
1. Clean previous builds
2. Build the Rust binary
3. Create the Debian package
4. Validate with lintian (if available)

### **Manual Build**

Or build manually:

```bash
# Clean previous builds
rm -rf target/ debian/deb-bootupd/ *.deb *.changes *.buildinfo *.dsc

# Build the package
dpkg-buildpackage -b -uc -us
```

## **🧪 Testing the Package**

### **Package Validation**

Test the built package:

```bash
./test-deb.sh
```

This validates:
- Package structure
- File locations
- Dependencies
- Installation (dry run)

### **Manual Testing**

```bash
# Check package info
dpkg-deb -I ../deb-bootupd_*.deb

# View package contents
dpkg-deb -c ../deb-bootupd_*.deb

# Test installation
sudo dpkg -i ../deb-bootupd_*.deb
sudo apt-get install -f  # Fix dependencies if needed
```

## **📋 Package Contents**

Your package installs:

- **Binary**: `/usr/libexec/bootupd` (multicall executable)
- **Symlink**: `/usr/bin/bootupctl` → `/usr/libexec/bootupd`
- **Documentation**: README, changelog, and version info
- **No Services**: `bootupd` is NOT a daemon - it's a CLI tool

## **🔧 Package Configuration**

### **Dependencies**

- **Build**: `rustc`, `cargo`, `dh-cargo`
- **Runtime**: `efibootmgr`, `grub-common`, `ostree` (recommended)

### **Multicall Binary Architecture**

- **Main Binary**: `/usr/libexec/bootupd` (multicall binary)
- **CLI Client**: `/usr/bin/bootupctl` → `/usr/libexec/bootupd` (symlink)
- **Command Dispatch**: Based on argv[0] (how the binary is invoked)
- **No Daemon**: `bootupd` is NOT a service - it's a CLI tool

**How it works:**
- When invoked as `bootupd` → Shows **backend commands** (`generate-update-metadata`, `install`)
- When invoked as `bootupctl` → Shows **CLI commands** (`status`, `update`, `validate`, `adopt-and-update`)
- The binary automatically detects which interface to show based on the command name used to invoke it

## **📊 Quality Assurance**

### **Lintian Checks**

Run comprehensive validation:

```bash
lintian ../deb-bootupd_*.changes
```

### **Common Issues to Check**

- [ ] Binary is executable
- [ ] Symlinks are correct
- [ ] Systemd files are present
- [ ] Documentation is included
- **Dependencies are accurate**
- **Package follows Debian policy**

## **🚀 Distribution**

### **Local Installation**

```bash
sudo dpkg -i deb-bootupd_*.deb
sudo apt-get install -f  # Fix dependencies
```

### **Repository Distribution**

For distribution via APT repositories:

1. **Sign the package**:
   ```bash
   dpkg-sig --sign builder deb-bootupd_*.deb
   ```

2. **Upload to repository**:
   ```bash
   reprepro -b /path/to/repo includedeb trixie deb-bootupd_*.deb
   ```

### **CI/CD Integration**

Your Forgejo Actions workflow can now build `.deb` packages:

```yaml
- name: Build Debian Package
  run: |
    ./build-deb.sh
    
- name: Upload Package
  uses: actions/upload-artifact@v3
  with:
    name: deb-bootupd-package
    path: ../deb-bootupd_*.deb
```

## **🔍 Troubleshooting**

### **Build Failures**

- **Missing dependencies**: Install required build packages
- **Rust compilation errors**: Check `Cargo.toml` and dependencies
- **Permission errors**: Ensure scripts are executable

### **Package Issues**

- **Installation fails**: Check dependencies with `dpkg-deb -I`
- **Service not starting**: Verify systemd files and permissions
- **Binary not found**: Check file paths in `debian/install`

### **Validation Errors**

- **Lintian warnings**: Address policy violations
- **Missing files**: Verify `debian/install` mapping
- **Wrong permissions**: Check file modes in rules

## **📚 Resources**

- [Debian Packaging Guide](https://wiki.debian.org/HowToPackageForDebian)
- [Debian Policy Manual](https://www.debian.org/doc/debian-policy/)
- [dh-cargo Documentation](https://docs.rs/dh-cargo/)
- [dh-systemd Documentation](https://manpages.debian.org/dh-systemd)

## **🎯 Next Steps**

1. **Test the package** on a clean Debian Trixie system
2. **Validate with lintian** and fix any issues
3. **Set up a package repository** for distribution
4. **Integrate with CI/CD** for automated builds
5. **Publish to Debian repositories** (if desired)

---

**Happy Packaging! 🎉**