kodegen-bundler-bundle

Multi-platform package bundler for Rust applications.

Overview

kodegen-bundler-bundle is a standalone binary that creates platform-specific installation packages for Rust applications. It supports Linux (.deb, .rpm, AppImage), macOS (.app, .dmg), and Windows (.msi, .exe) package formats.

This bundler is designed to be called programmatically by release workflows (like kodegen-bundler-release) with explicit output path contracts.

Features

• 📦 Multi-Platform Support - Linux (deb/rpm/AppImage), macOS (app/dmg), Windows (msi/exe)
• 🎯 Caller-Specified Output Paths - Full control over artifact location and naming
• 🔒 Contract-Based Interface - Exit code 0 guarantees artifact exists at specified path
• 🚀 Fast Execution - Optimized bundling with minimal overhead
• 🛡️ Directory Management - Automatic parent directory creation
• 📊 Diagnostic Output - Detailed stdout/stderr for debugging

Installation

# Install from crates.io
cargo install kodegen_bundler_bundle

# OR build from source
git clone https://github.com/cyrup-ai/kodegen-bundler-bundle
cd kodegen-bundler-bundle
cargo install --path .

Basic Usage

The bundler accepts exactly three arguments and handles everything else internally:

# Bundle from local repository (reads Cargo.toml for GitHub URL, clones to tmp, builds, bundles)
kodegen_bundler_bundle \
  --source . \
  --platform deb \
  --output-binary /tmp/artifacts/myapp_1.0.0_arm64.deb

# Bundle from GitHub org/repo (clones to tmp, builds, bundles)
kodegen_bundler_bundle \
  --source cyrup-ai/kodegen \
  --platform dmg \
  --output-binary /tmp/artifacts/kodegen_0.1.2_arm64.dmg

# Bundle from GitHub URL (clones to tmp, builds, bundles)
kodegen_bundler_bundle \
  --source https://github.com/cyrup-ai/kodegen \
  --platform nsis \
  --output-binary C:\builds\kodegen_setup.exe

Exit code 0 = artifact guaranteed to exist at --output-binary path.

Output Path Contract

The --output-binary Flag

When --output-binary is specified, the bundler establishes a strict contract with the caller:

Bundler Responsibilities

1. Create parent directories - All directories in the output path are created if they don't exist
2. Move artifact - The created artifact is moved (not copied) to the exact specified path
3. Verify existence - Before returning, bundler verifies the file exists at the specified path
4. Return exit code 0 - Exit code 0 guarantees the file exists at the specified path

Contract Guarantees

If bundler returns exit code 0:
  ✓ File exists at --output-binary path
  ✓ File is complete and valid
  ✓ All parent directories created
  ✓ Original artifact removed from temp location

If bundler returns non-zero exit code:
  ✗ File may not exist at specified path
  ✗ Check stderr for error details

Communication Protocol

• Exit codes: Contractual communication (0 = success, file exists; non-zero = failure)
• stdout: Diagnostic information only (artifact paths, progress messages)
• stderr: Error details and warnings (diagnostic only, not contractual)

Important: Callers should only rely on exit codes for contract enforcement. stdout and stderr are for human consumption and debugging, not programmatic parsing.

CLI Reference

The Three Required Arguments

--source <SOURCE>           # Where to get the code (3 formats):
                           # 1. Local path: . or /path/to/repo
                           #    → Reads Cargo.toml repository field
                           #    → Clones from GitHub to /tmp/kodegen-bundle-{uuid}
                           # 2. GitHub org/repo: cyrup-ai/kodegen
                           #    → Clones from GitHub to /tmp/kodegen-bundle-{uuid}
                           # 3. GitHub URL: https://github.com/cyrup-ai/kodegen
                           #    → Clones from GitHub to /tmp/kodegen-bundle-{uuid}
                           # 
                           # ALL sources clone to tmp - NEVER builds in-place

--platform <PLATFORM>       # Target platform: deb, rpm, appimage, dmg, nsis

--output-binary <PATH>      # Full output path for final artifact
                           # Example: /tmp/artifacts/myapp_1.0.0_arm64.deb
                           # Bundler creates parent dirs automatically
                           # Exit code 0 guarantees file exists at this path

What the Bundler Handles Internally

The bundler automatically:

• Clones repository to tmp directory (/tmp/kodegen-bundle-{uuid})
• Reads binary name from Cargo.toml
• Reads version from Cargo.toml
• Detects target architecture
• Builds the binary (cargo build --release)
• Creates the platform package
• Moves artifact to --output-binary path
• Cleans up tmp directory
• Returns exit code 0 only if artifact exists

Caller responsibilities: Specify source, platform, output path Bundler responsibilities: Everything else

Supported Platforms

Platform	Extension	Description
deb	.deb	Debian/Ubuntu packages
rpm	.rpm	RedHat/Fedora/CentOS packages
appimage	.AppImage	Portable Linux executables
dmg	.dmg	macOS disk image installers
app	.app	macOS application bundles
nsis	.exe	Windows NSIS installers

Usage Examples

Bundle from Local Repository

# Reads repository URL from Cargo.toml, clones to tmp, builds, bundles
kodegen_bundler_bundle \
  --source /path/to/project \
  --platform deb \
  --output-binary /tmp/artifacts/myapp_1.0.0_amd64.deb

# Exit code 0 = file guaranteed at /tmp/artifacts/myapp_1.0.0_amd64.deb

Bundle from GitHub Org/Repo

# Clones cyrup-ai/kodegen from GitHub to tmp, builds, bundles
kodegen_bundler_bundle \
  --source cyrup-ai/kodegen \
  --platform deb \
  --output-binary /tmp/artifacts/kodegen_2.0.0_arm64.deb

# Exit code 0 = file guaranteed at /tmp/artifacts/kodegen_2.0.0_arm64.deb

Bundle from GitHub URL

# Clones from full GitHub URL to tmp, builds, bundles
kodegen_bundler_bundle \
  --source https://github.com/cyrup-ai/kodegen \
  --platform dmg \
  --output-binary ./dist/kodegen-3.1.4-arm64.dmg

# Bundler automatically creates ./dist/ directory

Cross-Platform Bundling

# Build Linux package from macOS (uses Docker internally)
kodegen_bundler_bundle \
  --source . \
  --platform deb \
  --output-binary /tmp/myapp.deb

# Build Windows installer from Linux (uses Docker with Wine)
kodegen_bundler_bundle \
  --source cyrup-ai/myapp \
  --platform nsis \
  --output-binary C:\builds\myapp_setup.exe

Integration with Release Workflows

The bundler is designed to integrate seamlessly with release automation tools like kodegen-bundler-release.

Typical Workflow Integration

1. Release workflow detects target architecture (compile-time cfg attributes)
2. Release constructs output path with explicit architecture in filename
3. Release invokes bundler with --output-binary flag
4. Bundler creates directories and moves artifact to specified path
5. Bundler returns exit 0 only if file exists
6. Release verifies contract by checking file existence

Example: Release Workflow Calling Bundler

// In kodegen-bundler-release/src/cli/commands/release/impl.rs

// Release workflow constructs output path with architecture
let arch = detect_target_architecture()?;  // "arm64", "amd64", etc.
let version = "2.0.0";  // From Cargo.toml (bundler reads this internally too)
let filename = format!("kodegen_{}_{}.deb", version, arch);
let output_path = artifacts_dir.join(&filename);

// Call bundler with three arguments
let output = Command::new("kodegen_bundler_bundle")
    .arg("--source").arg("cyrup-ai/kodegen")  // ← GitHub org/repo
    .arg("--platform").arg("deb")
    .arg("--output-binary").arg(&output_path)
    .output()?;

// Contract enforcement: exit 0 = file exists
if output.status.success() {
    if !output_path.exists() {
        return Err("Bundler contract violation: exit 0 but file missing");
    }
    // File guaranteed to exist at output_path
    // Bundler handled: cloning, building, bundling, cleanup
}

Architecture Handling

Caller Responsibility

The caller (e.g., release workflow) is responsible for:

• Specifying source (local path, GitHub org/repo, or GitHub URL)
• Specifying target platform (deb, rpm, dmg, etc.)
• Constructing the output filename with architecture (e.g., myapp_1.0.0_arm64.deb)
• Passing the complete output path to bundler

Bundler Responsibility

The bundler handles everything else:

• Cloning repository to /tmp/kodegen-bundle-{uuid} from GitHub
• Reading binary name from Cargo.toml
• Reading version from Cargo.toml
• Detecting target architecture
• Building the binary (cargo build --release)
• Creating the platform package
• Creating parent directories in the output path
• Moving the artifact to the specified location
• Cleaning up tmp directory
• Verifying the file exists before returning exit 0

Why This Design?

This separation ensures:

• Caller only needs to know: source location, platform, and output path
• Bundler is completely self-contained and handles all implementation details
• Contract is enforced through exit codes: 0 = file exists, non-zero = failure
• Future-proof for new platforms and architectures (no caller changes needed)
• Isolation - builds always happen in tmp, never modifies source directory

Error Handling

Exit Codes

Exit Code	Meaning
0	Success - if --output-binary specified, file guaranteed to exist
1	General error - check stderr
Non-zero	Specific error - check stderr for details

Common Errors

Directory Creation Failed

Error: Failed to create output directory /path/to/output: Permission denied

Solution: Check write permissions on the parent directory.

Artifact Move Failed

Error: Failed to move artifact from /tmp/bundle.deb to /output/app.deb: No such file or directory

Solution: Verify source artifact was created successfully. Check bundler logs.

Contract Violation

Error: Move reported success but file does not exist at /output/app.deb

Solution: This indicates a bundler bug. Report to maintainers.

Required Project Structure

For bundling to work, your project must have:

your-project/
├── Cargo.toml                    # [package.metadata.bundle] section
├── src/
│   └── main.rs
├── assets/
│   └── img/
│       ├── icon.icns             # macOS
│       ├── icon.ico              # Windows
│       └── icon_*x*.png          # Linux (multiple sizes)
└── target/
    └── release/
        └── your-binary           # Built binary

See kodegen-bundler-release README for detailed asset requirements.

Configuration

TOML Configuration Structure

Bundle settings are configured in your project's Cargo.toml under [package.metadata.bundle]. The configuration uses a flat structure where platform-specific settings are direct children of the bundle section.

Important: Platform settings like deb, rpm, appimage, macos, and windows are direct fields under [package.metadata.bundle], not nested under intermediate sections like .linux.

Complete Configuration Example

[package.metadata.bundle]
# Universal settings
identifier = "com.example.myapp"
publisher = "Example Inc."
icon = ["assets/img/icon_32x32.png", "assets/img/icon_128x128.png"]
resources = ["assets/data"]
copyright = "Copyright © 2025 Example Inc."
category = "Utility"
short_description = "My awesome application"
long_description = "A detailed description of my application"

# Linux: Debian/Ubuntu packages
[package.metadata.bundle.deb]
depends = ["libc6 (>= 2.31)", "libssl3"]
section = "utils"
priority = "optional"

# Linux: RedHat/Fedora/CentOS packages
[package.metadata.bundle.rpm]
depends = ["glibc >= 2.31", "openssl-libs"]
release = "1"

# Linux: AppImage portable executables
[package.metadata.bundle.appimage]
bins = ["myapp"]

# macOS: Application bundles and disk images
[package.metadata.bundle.macos]
frameworks = []
minimum_system_version = "10.13"
signing_identity = "Developer ID Application: Example Inc. (TEAM123)"

[package.metadata.bundle.macos.dmg]
background = "assets/dmg-background.png"
window_size = { width = 660, height = 400 }

# Windows: MSI and NSIS installers
[package.metadata.bundle.windows]
wix_language = "en-US"

[package.metadata.bundle.windows.nsis]
installer_mode = "perUser"
compression = "lzma"

Platform-Specific Configuration Details

Debian Packages ([package.metadata.bundle.deb])

[package.metadata.bundle.deb]
depends = ["libc6 (>= 2.31)"]    # Runtime dependencies
section = "utils"                 # Package category
priority = "optional"             # Installation priority

Note: The path is [package.metadata.bundle.deb], not [package.metadata.bundle.linux.deb].

RPM Packages ([package.metadata.bundle.rpm])

[package.metadata.bundle.rpm]
depends = ["glibc >= 2.31"]      # Runtime dependencies
release = "1"                     # RPM release number

Note: The path is [package.metadata.bundle.rpm], not [package.metadata.bundle.linux.rpm].

AppImage ([package.metadata.bundle.appimage])

[package.metadata.bundle.appimage]
bins = ["myapp", "myapp-cli"]    # Binaries to include

Note: The path is [package.metadata.bundle.appimage], not [package.metadata.bundle.linux.appimage].

macOS Bundles ([package.metadata.bundle.macos])

[package.metadata.bundle.macos]
frameworks = []                                    # Additional frameworks
minimum_system_version = "10.13"                   # Minimum macOS version
signing_identity = "Developer ID Application: ..." # Code signing identity

[package.metadata.bundle.macos.dmg]
background = "assets/dmg-background.png"           # DMG background image
window_size = { width = 660, height = 400 }        # DMG window size

Windows Installers ([package.metadata.bundle.windows])

[package.metadata.bundle.windows]
wix_language = "en-US"           # MSI installer language

[package.metadata.bundle.windows.nsis]
installer_mode = "perUser"        # "perUser" or "perMachine"
compression = "lzma"              # "none", "zlib", or "lzma"

Minimal Configuration

The bundler works with minimal configuration, using sensible defaults:

[package.metadata.bundle]
identifier = "com.example.myapp"
publisher = "Example Inc."
icon = ["assets/img/icon.png"]

All platform-specific sections are optional and will use defaults if not specified.

TOML Path Reference

Correct paths for platform-specific configuration:

• ✅ [package.metadata.bundle.deb] - Debian settings
• ✅ [package.metadata.bundle.rpm] - RPM settings
• ✅ [package.metadata.bundle.appimage] - AppImage settings
• ✅ [package.metadata.bundle.macos] - macOS settings
• ✅ [package.metadata.bundle.macos.dmg] - DMG-specific settings
• ✅ [package.metadata.bundle.windows] - Windows settings
• ✅ [package.metadata.bundle.windows.nsis] - NSIS-specific settings

Incorrect paths (do not use):

• ❌ [package.metadata.bundle.linux.deb] - Wrong, no .linux parent
• ❌ [package.metadata.bundle.linux.rpm] - Wrong, no .linux parent
• ❌ [package.metadata.bundle.linux.appimage] - Wrong, no .linux parent

Building from Source

Prerequisites

• Rust nightly (edition 2024): rustup install nightly && rustup default nightly
• Platform-specific tools:
  • Linux: dpkg-dev, rpm, fakeroot
  • macOS: Xcode Command Line Tools
  • Windows: WiX Toolset, NSIS

Build Commands

# Build release binary
cargo build --release

# Run tests
cargo test

# Format and lint
cargo fmt
cargo clippy -- -D warnings

License

Dual-licensed under Apache-2.0 OR MIT.

See LICENSE.md for details.

Credits

Part of the KODEGEN.ᴀɪ project - blazing-fast MCP tools for AI-powered code generation.

Support

• Issues: GitHub Issues
• Documentation: docs.rs
• Website: kodegen.ai