YourApp.app/Contents/
├── Info.plist           # Application metadata
├── MacOS/
│   ├── your-gui-binary  # Main executable (launches GUI)
│   └── bin/
│       └── your-cli-binary  # CLI tool (accessed via PATH)
└── Resources/
    └── AppIcon.icns     # Application icon

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleName</key><string>YourApp</string>
    <key>CFBundleDisplayName</key><string>Your App</string>
    <key>CFBundleIdentifier</key><string>com.yourcompany.yourapp</string>
    <key>CFBundleVersion</key><string>1.0.0</string>
    <key>CFBundleShortVersionString</key><string>1.0.0</string>
    <key>CFBundleExecutable</key><string>your-gui-binary</string>
    <key>CFBundleIconFile</key><string>AppIcon.icns</string>
    <key>CFBundlePackageType</key><string>APPL</string>
    <key>LSMinimumSystemVersion</key><string>10.13</string>
    <key>NSHighResolutionCapable</key><true/>
</dict>
</plist>

undefined

**Result**: Users drag YourApp.app to Applications, instantly getting both GUI and CLI.

undefined

**Why the retry logic?**
- macOS Finder may still be accessing the mounted DMG even after AppleScript completes
- This causes `hdiutil: couldn't eject "disk6" - Resource busy` errors
- The retry loop with delays solves this race condition
- Affects both Intel and Apple Silicon builds in GitHub Actions
- Without this fix, DMG creation randomly fails with exit code 16

**Result**: Users drag YourApp.app to Applications, instantly getting both GUI and CLI.

hdiutil: couldn't eject "disk2" - Resource busy
hdiutil: convert failed - Resource temporarily unavailable
Error: Process completed with exit code 1

undefined

**Why This Works**:
1. **Progressive escalation**: Starts with gentle unmount, escalates to force only if needed
2. **Verification between steps**: Uses `diskutil info` to check mount status before each strategy
3. **Multiple tools**: Combines `hdiutil detach` and `diskutil unmountDisk` (different unmount mechanisms)
4. **Diagnostic output**: Shows `lsof` output if unmount fails to help debug persistent issues
5. **Multiple sync calls**: Ensures filesystem writes complete before attempting unmount
6. **Longer delays**: Gives background processes time to release file handles

**Implementation Location**: `.github/workflows/release.yml` in the "Create DMG installer (macOS only)" step, lines ~328-377.

**Applies To**: Both Intel (x86_64-apple-darwin) and Apple Silicon (aarch64-apple-darwin) DMG builds.

**Testing**: After implementing this fix, DMG creation should succeed consistently even under system load. Monitor with:
```bash
gh run watch
gh run list --workflow=release.yml --limit 5

undefined

undefined

fn main() {
    #[cfg(windows)]  // Only run on Windows builds
    {
        let mut res = winres::WindowsResource::new();
        res.set_icon("assets/app.ico");  // Path to multi-resolution ICO file
        res.set("ProductName", "YourApp");  // Shown in Task Manager
        res.set("FileDescription", "Description");  // Shown in file properties
        res.set("LegalCopyright", "Copyright (c) 2025");
        res.compile().expect("Failed to compile Windows resources");
    }
}

undefined

**Why multi-resolution?** Windows picks different icon sizes depending on context (taskbar, file explorer, system tray). Single-size ICOs look pixelated when scaled.

// Fails during cargo package because ../../ escapes the package boundary
let logo = include_bytes!("../../assets/logo.png");

undefined

```rust
// Update code to use local path (within package)
let logo = include_bytes!("../assets/logo.png");  // ../assets relative to src/

undefined

**Why this works**: Each package becomes self-contained with its own assets, allowing `cargo package` and `cargo publish` to succeed.

undefined

**Expected output**: Should show `assets/logo.png` in the package contents.

dotnet tool install --global wix  # Microsoft's official installer framework

<Wix xmlns="http://wixtoolset.org/schemas/v4/wxs">
  <!-- Package metadata -->
  <Package Name="YourApp" Version="1.0.0" Manufacturer="Your Company"
           UpgradeCode="GUID-HERE" Language="1033">  <!-- UpgradeCode: NEVER CHANGE! Used to detect previous installations -->
    <MajorUpgrade DowngradeErrorMessage="Newer version installed." />  <!-- Auto-uninstall old version -->
    <MediaTemplate EmbeddingCompressionLevel="high" />  <!-- Compress to reduce file size -->

    <!-- What to install -->
    <Feature Id="ProductFeature" Title="YourApp" Level="1">
      <ComponentGroupRef Id="ProductComponents" />
    </Feature>

    <!-- Where to install -->
    <StandardDirectory Id="ProgramFiles6432Folder">  <!-- C:\Program Files\ -->
      <Directory Id="INSTALLFOLDER" Name="YourApp">  <!-- C:\Program Files\YourApp\ -->
        <Component Id="MainExecutable" Bitness="always64">
          <File Id="GUI" Source="target\release\yourapp-gui.exe" KeyPath="yes">
            <Shortcut Id="StartMenu" Directory="ProgramMenuFolder" Name="YourApp" />  <!-- Start Menu shortcut -->
          </File>
          <File Id="CLI" Source="target\release\yourapp.exe" />  <!-- CLI tool -->
        </Component>
        <Component Id="PathEnvironment" Bitness="always64">
          <!-- Add install dir to system PATH so CLI is accessible from any terminal -->
          <Environment Id="PATH" Name="PATH" Value="[INSTALLFOLDER]"
                       Permanent="no" Part="last" Action="set" System="yes" />
        </Component>
      </Directory>
    </StandardDirectory>
  </Package>

  <!-- Component registry -->
  <Fragment>
    <ComponentGroup Id="ProductComponents" Directory="INSTALLFOLDER">
      <ComponentRef Id="MainExecutable" />
      <ComponentRef Id="PathEnvironment" />
    </ComponentGroup>
  </Fragment>
</Wix>

wix build yourapp.wxs -o YourApp.msi

debian/
├── control          # Package metadata
├── rules            # Build script
├── changelog        # Version history
├── copyright        # License
├── compat           # Debian level (13)
├── yourapp.desktop  # Desktop entry
└── source/format    # "3.0 (quilt)"

undefined

**Best practice**: Match email in `Cargo.toml` authors.

Source: yourapp
Section: utils
Priority: optional
Maintainer: Your Name <your@email.com>
Build-Depends: debhelper-compat (= 13), cargo, rustc, pkg-config, libleptonica-dev, libtesseract-dev
Standards-Version: 4.6.0
Homepage: https://github.com/yourname/yourapp

Package: yourapp
Architecture: amd64
Depends: ${shlibs:Depends}, ${misc:Depends}, libimage-exiftool-perl, tesseract-ocr, ffmpeg
Description: Short description
 Long description.

#!/usr/bin/make -f
export DEB_BUILD_MAINT_OPTIONS = hardening=+all  # Enable security hardening (ASLR, stack protection, etc.)

%:
	dh $@  # Use debhelper to handle most packaging tasks

override_dh_auto_build:
	cargo build --release --workspace  # Build all workspace members

override_dh_auto_install:
	# Install binaries to /usr/bin with executable permissions
	install -D -m 755 target/release/yourapp-gui debian/yourapp/usr/bin/yourapp-gui
	install -D -m 755 target/release/yourapp debian/yourapp/usr/bin/yourapp

	# Install desktop entry for application menu integration
	install -D -m 644 debian/yourapp.desktop debian/yourapp/usr/share/applications/yourapp.desktop

	# Install icon to BOTH locations for maximum compatibility:
	# - /usr/share/pixmaps/ (legacy, used by older desktop environments)
	# - /usr/share/icons/hicolor/512x512/apps/ (freedesktop standard, preferred)
	install -D -m 644 yourapp-gui/assets/yourapp.png debian/yourapp/usr/share/pixmaps/yourapp.png
	install -D -m 644 yourapp-gui/assets/yourapp.png debian/yourapp/usr/share/icons/hicolor/512x512/apps/yourapp.png

[Desktop Entry]
Type=Application
Name=YourApp
Comment=Description
Exec=/usr/bin/yourapp-gui
Icon=yourapp
Terminal=false
Categories=Utility;

yourapp (1.0.0-1) unstable; urgency=medium

  * Initial release

 -- Your Name <your@email.com>  Mon, 01 Jan 2024 12:00:00 +0000

sudo apt-get install -y pkg-config libleptonica-dev libtesseract-dev libclang-dev clang

export PKG_CONFIG_PATH="/usr/lib/x86_64-linux-gnu/pkgconfig:$PKG_CONFIG_PATH"
cargo build --release

- run: sudo apt-get install -y pkg-config libleptonica-dev libtesseract-dev libclang-dev clang
- run: |
    export PKG_CONFIG_PATH="/usr/lib/x86_64-linux-gnu/pkgconfig:$PKG_CONFIG_PATH"
    cargo build --release

dpkg-buildpackage -us -uc -b
lintian ../yourapp_1.0.0-1_amd64.deb

name: Release
on:
  push:
    tags: ['v*.*.*']  # Triggers when you push v1.0.0, v0.5.1, etc.
  workflow_dispatch:  # Manual trigger fallback if needed
    inputs:
      tag: {required: true, type: string}

jobs:
  create-release:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.get_version.outputs.version }}  # Share version with build jobs
    steps:
      - uses: actions/checkout@v4
      - id: get_version
        run: |
          # Extract version from tag (v1.0.0 → 1.0.0)
          if [ "${{ github.event_name }}" = "push" ]; then
            echo "version=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
          else
            echo "version=${{ inputs.tag }}" >> $GITHUB_OUTPUT
          fi
      - run: gh release create ${{ steps.get_version.outputs.version }} --draft  # Create draft release
        env: {GH_TOKEN: ${{ github.token }}}

  build:
    needs: create-release  # Wait for release to be created
    strategy:
      matrix:  # Build all platforms in parallel
        include:
          - {os: macos-latest, target: x86_64-apple-darwin, archive: dmg}    # macOS Intel
          - {os: macos-latest, target: aarch64-apple-darwin, archive: dmg}   # macOS Apple Silicon
          - {os: windows-latest, target: x86_64-pc-windows-msvc, archive: msi}  # Windows
          - {os: ubuntu-latest, target: x86_64-unknown-linux-gnu, archive: deb}  # Linux
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with: {targets: ${{ matrix.target }}}

      # Platform-specific builds happen here (DMG, MSI, DEB creation)

      # Generate checksums with unique filenames to avoid artifact collisions
      - run: sha256sum * | tee checksums-${{ matrix.target }}.txt
      - uses: actions/upload-artifact@v4
        with:
          name: yourapp-${{ matrix.target }}  # Unique artifact name per platform
          path: |
            *.dmg
            *.msi
            ../*.deb
            checksums-*.txt

undefined

**What this adds**: Cryptographic proof that the artifact was built by this repo's workflow. Users can verify authenticity:
```bash
gh attestation verify yourapp.dmg --owner yourname

on:
  workflow_dispatch:
    inputs: {version: {required: true, type: string}}
  repository_dispatch:
    types: [update-formulae]

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - id: get-version
        run: |
          if [ "${{ github.event_name }}" = "repository_dispatch" ]; then
            echo "version=${{ github.event.client_payload.version }}" >> $GITHUB_OUTPUT
          else
            echo "version=${{ inputs.version }}" >> $GITHUB_OUTPUT
          fi
      - uses: actions/checkout@v4
      - run: gh release download "v${{ steps.get-version.outputs.version }}" --repo yourname/yourapp --pattern "checksums.txt"
        env: {GH_TOKEN: ${{ github.token }}}
      - id: checksums
        run: |
          echo "arm64_sha=$(grep aarch64-apple-darwin checksums.txt | awk '{print $1}')" >> $GITHUB_OUTPUT
          echo "x86_64_sha=$(grep x86_64-apple-darwin checksums.txt | awk '{print $1}')" >> $GITHUB_OUTPUT
      - run: |
          sed -i "s/version \".*\"/version \"${{ steps.get-version.outputs.version }}\"/" Formula/yourapp.rb
          # Update URLs and SHAs...
      - run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add Formula/ Casks/
          git commit -m "chore: update to v${{ steps.get-version.outputs.version }}"
          git push

update-homebrew:
  needs: [create-release, build, checksums]
  runs-on: ubuntu-latest
  if: ${{ !contains(needs.create-release.outputs.version, '-') }}  # Skip pre-releases
  steps:
    - run: |
        VERSION=${{ needs.create-release.outputs.version }}
        curl -L -X POST \
          -H "Authorization: Bearer ${{ secrets.HOMEBREW_DISPATCH_TOKEN }}" \
          https://api.github.com/repos/yourname/homebrew-yourapp/dispatches \
          -d "{\"event_type\":\"update-formulae\",\"client_payload\":{\"version\":\"${VERSION#v}\"}}"

cargo release patch --execute

git tag --sort=-version:refname | head -5

**Workaround**: Manually create and push the simple `vX.Y.Z` tag:
```bash

**Root cause**: cargo-release uses package names in tags for workspace members. The GitHub Actions workflow triggers on `v*.*.*` pattern which doesn't match `package-v*.*.*`.

**Alternative**: Configure `release.toml` to customize tag format (not yet tested).

**Checklist**:
- [ ] `on: push: tags: ['v*.*.*']` in release workflow
- [ ] Version extraction handles both `push` and `workflow_dispatch`
- [ ] Homebrew workflow listens for `repository_dispatch`
- [ ] Main workflow sends dispatch after successful build
- [ ] `release.toml` configured
- [ ] **After cargo-release, manually create `v*.*.*` tag**

**Monitor**:
```bash
gh run watch
gh run list --limit 5