Packaging

This document provides guidance for maintainers packaging Rivet for various distributions and package managers.

Prebuilt binaries

End users can install Rivet with install.sh (curl -sSf https://rivet.fobiat.workers.dev/install | sh), which fetches a static binary from the newest published GitHub Release, or falls back to cargo install --git when no matching binary exists for the resolved version yet.

Binaries are built and attached to a release by .github/workflows/release.yml, which runs when a maintainer publishes a GitHub Release (never automatically on every tag; releases mark deliberate milestones). It targets x86_64-unknown-linux-musl and aarch64-unknown-linux-musl (static, so one binary runs across every glibc version on every distro family in docs/MULTI_DISTRO.md), and uploads two files per target to the release:

rivet-<tag>-<target>.tar.gz          # rivet, README.md, CHANGELOG.md, LICENSE-MIT, LICENSE-APACHE
rivet-<tag>-<target>.tar.gz.sha256

Distribution packages (AUR, .deb/.rpm, Homebrew, etc.) should source the binary from these release assets rather than building from source, once a release has them attached.

Asset Sources

All branding assets for Rivet are located in assets/branding/:

Recommended icon sizes:
- 512px or 1024px — use png/app/rivet-app-icon-512.png or -1024.png as your primary source
- Light variant — png/app/rivet-app-icon-light-512.png for light-themed environments
- Multiple sizes — png/icon/rivet-icon-{16,32,48,64,128,256,512,1024}.png (transparent background)
Favicon — favicon.ico for any web-based tools, or individual sizes from png/favicon/

For more detailed asset information, see assets/branding/README.md.

Package Manager Guidelines

Linux Distributions

Arch / AUR

Icon: Use png/app/rivet-app-icon-512.png
Desktop file location: /usr/share/applications/rivet.desktop
Icon installation: Place in /usr/share/pixmaps/rivet.png

Example desktop file:

[Desktop Entry]
Type=Application
Name=Rivet
Comment=Git-native workstation snapshots
Exec=rivet about
Icon=rivet
Terminal=true
Categories=Utility;System;

Debian / Ubuntu

Icon: Use png/app/rivet-app-icon-256.png (or 512px if larger icons are supported)
Install location: /usr/share/pixmaps/rivet.png or /usr/share/icons/hicolor/256x256/apps/rivet.png
Desktop file: /usr/share/applications/rivet.desktop (see Arch example above)

Fedora / RHEL

Icon: Use png/app/rivet-app-icon-512.png
Install via %{_datadir}/pixmaps/rivet.png
Desktop file: /usr/share/applications/rivet.desktop

openSUSE

Icon: Place in /usr/share/pixmaps/ (512px variant recommended)
Use png/app/rivet-app-icon-512.png

Snap

snapcraft.yaml:

name: rivet
version: '0.4.0'
summary: Git-native workstation snapshots
description: |
  Rivet recreates a Linux or macOS workstation from reviewable, Git-versioned state.
  It tracks approved configuration and explicit packages, never secrets or disk images.

icon: snap/gui/rivet.png  # Place png/app/rivet-app-icon-512.png here

Flatpak

com.example.rivet.metainfo.xml:

<?xml version="1.0" encoding="UTF-8"?>
<component type="console-application">
  <id>com.example.rivet</id>
  <name>Rivet</name>
  <summary>Git-native workstation snapshots</summary>
  <icon type="remote" width="512" height="512">
    https://example.com/assets/rivet-app-icon-512.png
  </icon>
  <!-- ... more metadata ... -->
</component>

Place png/app/rivet-app-icon-512.png or -256.png in the appropriate directory for your Flatpak setup.

Homebrew (macOS/Linux)

For Homebrew, you’ll need to generate a macOS .icns format from the source PNG:

# Using ImageMagick
convert png/app/rivet-app-icon-512.png rivet.icns

# Or using sips (macOS built-in)
sips -s format icns png/app/rivet-app-icon-512.png --out rivet.icns

Then include the .icns in your Homebrew formula.

Windows (Future)

When packaging for Windows:

Generate .ico from png/app/rivet-app-icon-512.png:

# Using ImageMagick
convert png/app/rivet-app-icon-512.png rivet.ico

Include in your installer (MSI, NSIS, etc.)
Set the executable icon in your build system

Icon Specifications

Color & Transparency

Background: Dark teal/green (#0F1A17), transparent variants available
Transparent variant: Use png/icon/rivet-icon-*.png for toolbar icons or small UI elements
Filled variant: Use png/app/rivet-app-icon-*.png for app launcher/menu entries

Sizing Recommendations

App launcher: 48px–512px (use -512.png as source, let the system scale down)
Taskbar/dock: 32px–64px (use -64.png or -128.png)
Menu icon: 16px–24px (use -16.png or -32.png)
Splash/about screen: Already handled by CLI (rivet about)

Multi-Resolution Icons

For systems supporting multiple icon resolutions, Rivet provides:

Size	Transparent	Filled	Use Case
16px	✓	✗	Favicons, very small UI
32px	✓	✗	Taskbar, small menu icons
48px	✓	✗	Default toolbar size
64px	✓	✗	Medium icons
128px	✓	✗	Large icons
256px	✓	✓	App launchers (medium)
512px	✓	✓	App launchers (large), splash
1024px	✗	✓	High-DPI displays

When installing, consider your system’s conventions:

High-DPI systems (macOS Retina, GNOME, KDE on 4K): use -512.png or -1024.png
Standard displays: use -256.png or -512.png and let the system scale
Icon directories: use the hicolor structure (256x256/apps/, 512x512/apps/, etc.)

If Rivet is featured on your package repository website or social media:

Use png/social/rivet-social-banner.png (1280×640)
Or the horizontal logo from png/logo/rivet-logo-horizontal.png / -dark.png

Verification

After packaging, verify:

Icon displays correctly in your package manager
Icon is crisp and properly sized
Desktop shortcut (if applicable) uses the icon
rivet --help and rivet about display correctly
Splash screen and CLI output are visible
Man page (if included) is properly formatted

Updating

When a new version of Rivet is released:

Rebuild/repackage the binary
Icons and branding do not change unless explicitly noted in release notes
Check BRANDING.md for any icon/asset updates
Re-run asset generation if the design files changed:
Terminal window
```
python3 assets/branding/generate.py
```

Support

For issues with packaging or asset usage, see:

assets/branding/README.md — detailed asset guide
docs/BRANDING.md — branding strategy and implementation
GitHub Issues — report packaging-specific problems

Last updated: 2026-07-24
Asset version: 0.4.0 (aligned with Rivet v0.4.0)