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:

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

Quick Build

Use the automated build script:

./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:

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

./test-deb.sh

This validates:

• Package structure
• File locations
• Dependencies
• Installation (dry run)

Manual Testing

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

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

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

Repository Distribution

For distribution via APT repositories:

1. Sign the package:

   dpkg-sig --sign builder deb-bootupd_*.deb
   

2. Upload to repository:

   reprepro -b /path/to/repo includedeb trixie deb-bootupd_*.deb
   

CI/CD Integration

Your Forgejo Actions workflow can now build .deb packages:

- 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
• Debian Policy Manual
• dh-cargo Documentation
• dh-systemd Documentation

🎯 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! 🎉