ContextQMD
Back to Codexbar

Icon pipeline (macOS .icon → .icns without Xcodebuild)

docs/icon.md

0.241.3 KB
Original Source

Icon pipeline (macOS .icon → .icns without Xcodebuild)

We use the new macOS 26 “glass” .icon bundle from Icon Composer/IconStudio and convert it to .icns via Xcode’s hidden CLI (ictool/icontool), without an Xcode project.

Script

Scripts/build_icon.sh ICON.icon CodexBar [outdir]

What it does:

  1. Finds ictool (or icontool) in /Applications/Xcode.app/Contents/Applications/Icon Composer.app/Contents/Executables/.
  2. Renders the macOS Default appearance of the .icon to an 824×824 PNG (inner art, glass applied).
  3. Pads to 1024×1024 with transparency (restores Tahoe squircle margin, avoids “white plate”).
  4. Downscales to all required sizes into an .iconset.
  5. Runs iconutil -c icns → Icon.icns.

Requirements:

  • Xcode 26+ installed (IC tool lives inside the Xcode bundle).
  • sips and iconutil (system tools).

Usage:

bash
./Scripts/build_icon.sh Icon.icon CodexBar

Outputs Icon.icns at repo root.

Why this approach:

  • Naive sips/iconutil from raw PNGs often leaves a white/grey plate because the inner art is full-bleed. The ictool render + transparent padding matches Xcode’s asset-pipeline output.

Notes:

  • If Xcode is in a nonstandard location, set XCODE_APP=/path/to/Xcode.app before running.
  • Script is CI-friendly; no Xcode project needed.