build-emacs-for-macos/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

macOS Emacs building system with Ruby and Go components:

• Ruby script (build-emacs-for-macos): Main build script for creating self-contained Emacs.app bundles
• Go CLI tool (emacs-builder): Packaging, signing, notarization, and release management
• Dual dependency management: Nix (preferred) or Homebrew

Common Commands

# Environment setup (Nix preferred)
nix develop                       # Default macOS 11 SDK
nix develop .#macos{11-15,26}     # Target specific SDK version

# Go development
make build                        # Build emacs-builder CLI
make test                         # Run tests with race detection
make lint                         # Run golangci-lint
make format                       # Format with gofumpt

# Ruby development
bundle exec rubocop               # Lint (with development group)

# Build Emacs
./build-emacs-for-macos           # Build from master
./build-emacs-for-macos emacs-29.4

Architecture

Ruby Build Script (build-emacs-for-macos)

Single-file Ruby script (~2500 lines) that:

• Downloads source tarballs from emacs-mirror/emacs on GitHub
• Configures and compiles Emacs with native-comp, tree-sitter support
• Creates self-contained .app bundles by embedding/relinking dependencies
• Uses ruby-macho gem for Mach-O binary manipulation (RPATH handling)

Go CLI (cmd/emacs-builder/)

Uses urfave/cli/v2 framework. Key packages in pkg/:

• cli/: Commands (plan, sign, sign-files, notarize, package, release, cask)
• sign/: macOS code signing via codesign
• notarize/: Apple notarization workflow via notarytool
• release/: GitHub release management
• dmgbuild/: DMG creation using Python dmgbuild
• plan/: Build plan JSON parsing and management

Nix Environment (flake.nix)

• Multi-SDK support: macOS 11-15, 26 via .#macos{11,12,13,14,15,26}
• Excludes ncurses intentionally (links against system version for TUI)
• Sets MACOSX_DEPLOYMENT_TARGET, DEVELOPER_DIR, NIX_LIBGCCJIT_*

Testing

make test                         # All Go tests
go test ./pkg/release/...         # Single package
go test -run TestName ./pkg/...   # Single test

Tests use _test.go suffix alongside source files.

Working Directories

• sources/: Downloaded/extracted Emacs source (gitignored)
• builds/: Build outputs and .app bundles (gitignored)
• patches/: Emacs patches applied during build
• bin/: Built Go binaries (gitignored)