emacs-plus Homebrew Tap

The Emacs Client.app is a macOS application bundle that allows you to interact with emacsclient through standard macOS interfaces like Finder, Spotlight, and the Dock.

Key capabilities include:

• Finder Integration: Right-click files and select "Open With → Emacs Client" or drag and drop files onto the app icon.
• Default Application: Set Emacs Client as the default handler for text and code files.
• Spotlight/Dock: Launch new Emacs frames directly from Spotlight or the Dock.
• URL Handling: Supports org-protocol:// URLs for integrations like org-capture and org-roam.

The homebrew-emacs-plus repository provides a collection of community-contributed Emacs icons in .icns format. These icons can be used to customize the appearance of Emacs on macOS.

Note on macOS 26+ (Tahoe): Standard .icns icons may appear in an "icon jail," where they are displayed smaller within a rounded square container.

To use the Emacs Client.app functionality, install emacs-plus@30 using Homebrew and specify an icon variant using the --with-<your-icon>-icon flag.

brew install emacs-plus@30 --with-<your-icon>-icon

To contribute a new patch to the registry, follow these steps:

1. Run the helper script to generate the directory structure, metadata, and test application:

   ./scripts/create-community-patch.rb

2. Ensure the patch includes a metadata.json (with name, description, maintainer GitHub username, and compatible Emacs versions), version-specific patch files (e.g., emacs-30.patch), and a README.md.
3. Add an entry to registry.json.
4. Submit a Pull Request.

To enable macOS frame transparency and background blur support, you must apply the frame-transparency patch during the build process.

1. Add the patch to your ~/.config/emacs-plus/build.yml:

patches:
  - frame-transparency

2. Rebuild Emacs using Homebrew:

brew reinstall emacs-plus@31

Compatibility Note: This patch currently supports Emacs version 31.

patches:
  - frame-transparency

# Then run:
brew reinstall emacs-plus@31

To enable org-protocol:// URL handling (for org-capture, org-roam, etc.) with the Emacs Client app, follow these steps:

1. Emacs Configuration: Add (require 'org-protocol) to your Emacs init file.
2. Browser Extension: Install a compatible extension, such as org-capture-extension.
3. App Placement: Copy the app to /Applications to ensure reliable URL registration:

   cp -r "$(brew --prefix)/opt/emacs-plus@30/Emacs Client.app" /Applications/

4. Test: Try a sample URL in your browser: org-protocol://capture?template=t&url=https://example.com&title=Test

To contribute a new icon to the registry:

1. Run the helper script:

   ./scripts/create-community-icon.rb

2. Ensure the icon is a valid .icns file and includes metadata.json and a preview image.
3. Add an entry to registry.json.
4. Submit a Pull Request.

Use this patch to fix line height calculation issues for CJK (Chinese, Japanese, Korean) fonts. It forces Emacs to read typographic metrics from the OS/2 font table instead of the hhea table, which prevents text clipping or overlapping in pixel-sensitive modes like vterm.

When to use:

• If you see partial screen rendering in vterm with mixed CJK and English text.
• If text lines are being clipped or overlapping.
• If content is misaligned in terminal emulators.

Caveat: This patch may cause reduced line height (cramped vertical spacing) for some Latin-only fonts (e.g., PragmataPro) that do not set the USE_TYPO_METRICS flag.

patches:
  - mac-font-use-typo-metrics

To apply a community icon to your Emacs+ installation, add the icon key with the desired icon name to your ~/.config/emacs-plus/build.yml file. This configuration is supported for both formula and cask installation methods.

icon: dragon-plus

If you are maintaining or extending other emacs-plus formulas (such as emacs-plus@29, emacs-plus@31, or emacs-plus@32), you can include the Emacs Client.app by calling the create_emacs_client_app method after the icon installation step. This method is designed to automatically resolve the correct prefix, version, and buildpath from the current formula context. Ensure the installation logic is wrapped in a check for cocoa support and the absence of x11.

def install
  # ... existing installation code ...

  if (build.with? "cocoa") && (build.without? "x11")
    # ... icon installation code ...

    # Create Emacs Client.app
    create_emacs_client_app(icons_dir)

    # Install both apps
    prefix.install "nextstep/Emacs.app"
    prefix.install "nextstep/Emacs Client.app"

    # ... rest of installation ...
  end
end

After installation via Homebrew, you should create an alias in your /Applications folder to ensure reliable URL handling and system-wide availability. Use the following command (replacing #{prefix} with your actual Emacs installation prefix, e.g., /opt/homebrew/opt/emacs-plus@30):

osascript -e 'tell application "Finder" to make alias file to posix file "#{prefix}/Emacs Client.app" at posix file "/Applications" with properties {name:"Emacs Client.app"}'