README.packaging

# Debian Packaging for bssh

## Launchpad PPA Build Requirements

### Important: Internet Access Restriction
Launchpad build environments do NOT have internet access. This means:
- You cannot download Rust or any other dependencies during build
- All build dependencies must be declared in debian/control
- The build must use system-provided packages only

### Build Dependencies
The following packages are required and must be available to Launchpad through the Ubuntu archive or a configured dependency PPA:
- `rustc-1.85` or `rustc (>= 1.85)` - Rust compiler (Rust edition 2024 requires Rust 1.85+)
- `cargo-1.85` or `cargo (>= 1.85)` - Rust package manager
- `pkg-config` - For finding system libraries
- `cmake` - Build system

### Rust Version Requirements
This project requires Rust 1.85 or newer because it uses Rust edition 2024. This means:
- Ubuntu 22.04 (Jammy): requires a versioned Rust 1.85 toolchain from the PPA itself or a dependent PPA
- Ubuntu 24.04 (Noble): requires a versioned Rust 1.85 toolchain from the PPA itself or a dependent PPA
- Ubuntu 26.04 (Resolute): can use the archive's default Rust toolchain

If building for older Ubuntu versions, you may need to:
1. Add a Launchpad PPA dependency that provides `rustc-1.85` and `cargo-1.85`
2. Limit support to distributions with Rust 1.85+

### Build Process
1. GitHub Actions vendors crates into `vendor/` and generates `.cargo/config.toml`
2. The `debian/rules` file requires Rust/Cargo 1.85+ and enables offline cargo mode
3. Launchpad builds the project with `cargo build --release --frozen --workspace`
4. The binary is installed to `/usr/bin/bssh`

### Troubleshooting Build Failures
If the build fails on Launchpad:
1. Check the build log for the exact error
2. Common issues:
   - Missing build dependencies: Add them to debian/control
   - Rust version incompatibility: Ensure Rust 1.85+ is available
   - Missing PPA dependency: Jammy/Noble need access to `rustc-1.85` and `cargo-1.85`
   - Missing vendored crates: Ensure `vendor/` and `.cargo/config.toml` are included in the source package
   - Cargo registry access: The build will fail if it tries to download crates

### Automatic Version Incrementing
The packaging scripts support automatic version incrementing to avoid conflicts with existing PPA versions:

1. **get-next-ppa-version.sh**: Queries the PPA to find existing versions and calculates the next revision
2. **update-changelog.sh**: Supports `--auto-increment` flag to use the next available version
3. **GitHub Actions**: Automatically uses version incrementing when uploading to PPA

Version format: `{version}-1~{distro}{revision}`
- Example: `0.7.2-1~noble1` → `0.7.2-1~noble2` → `0.7.2-1~noble3`