How to Build the Hallelujah Input Method from Xcode and Install It to /Library/Input Methods/

Open the hallelujah.xcworkspace file in Xcode, build the project with ⌘B, then copy the resulting hallelujah.app bundle to /Library/Input Methods/ using sudo cp -R to install the input method system-wide.

Hallelujah IM is a native macOS input method engine developed in the dongyuwei/hallelujahim repository that provides intelligent English word completion and phonetic fuzzy matching. Building the project from source requires Xcode and produces a .app bundle that must be manually installed to /Library/Input Methods/ or ~/Library/Input Methods/ to function as a system input method. This guide walks through the complete build and installation workflow using the actual project structure and build settings defined in the source code.

Prerequisites for Building

Before compiling, ensure you have Xcode installed with support for Objective-C++ and Swift-compatible code. The repository uses CocoaPods for dependency management, evidenced by the hallelujah.xcworkspace file, so you must open the workspace rather than the standalone project file to link the static libmarisa.a library and other dependencies correctly.

Building the Input Method from Xcode

Open the Workspace File

Navigate to the repository root and open hallelujah.xcworkspace in Xcode. Do not open hallelujah.xcodeproj directly, as this will fail to link the Marisa trie library and other CocoaPods-managed dependencies required by src/ConversionEngine.mm and src/InputController.mm.

Select Build Configuration

In the Xcode toolbar, select the "hallelujah" scheme. Choose Debug for development builds (which enable verbose logging in src/main.mm) or Release for optimized performance. The build settings in hallelujah.xcodeproj/project.pbxproj define INSTALL_PATH = "$(LOCAL_LIBRARY_DIR)/Input Methods/", which prepares the bundle for installation to the system input methods directory.

Compile the Source

Press ⌘B to build. Xcode compiles the Objective-C++ source files including src/main.mm (application entry point), src/InputController.mm (IMK input controller), and src/ConversionEngine.mm (spelling correction engine), linking them against the static libmarisa.a trie library. Upon successful completion, the product hallelujah.app appears in the Products group.

Installing to /Library/Input Methods/

Locate the Compiled Bundle

After building, find hallelujah.app in the Derived Data folder, typically at ~/Library/Developer/Xcode/DerivedData/<project-id>/Build/Products/Debug/ (or Release). Alternatively, right-click the product in Xcode’s Products folder and select "Show in Finder".

System-Wide Installation

To install the input method for all users, copy the bundle to the system library directory. This requires administrator privileges:

sudo cp -R hallelujah.app /Library/Input\ Methods/

This path corresponds to the INSTALL_PATH build setting defined in the Xcode project configuration.

Per-User Installation

For a single-user install without sudo, copy the bundle to your home library:

cp -R hallelujah.app ~/Library/Input\ Methods/

Note that system-wide installation (/Library/Input Methods/) is generally preferred for input methods to ensure availability across all user accounts.

Enabling the Input Method in macOS

After installation, macOS must reload the input method cache. The most reliable method is to log out and log back in. Alternatively, open System Settings → Keyboard → Input Sources, click the "+" button, scroll to "Hallelujah" under the English language section, and add it. The input method will then appear in the menu bar input source selector.

Command-Line Build Automation

For CI/CD pipelines or automated testing, use xcodebuild to compile and stage the product:

# Clean build

xcodebuild -workspace hallelujah.xcworkspace \
           -scheme hallelujah \
           -configuration Release \
           clean build

# The built product path

BUILT_PRODUCT="build/Release/hallelujah.app"

After building, copy the resulting hallelujah.app from the build products directory to /Library/Input Methods/ as shown in the manual installation steps.

Summary

• Open hallelujah.xcworkspace (not the .xcodeproj) to ensure CocoaPods dependencies link correctly.
• Build the hallelujah scheme with ⌘B; the INSTALL_PATH setting targets /Library/Input Methods/.
• Copy hallelujah.app to /Library/Input Methods/ using sudo cp -R for system-wide availability.
• Enable the input method via System Settings → Keyboard → Input Sources or by restarting the login session.

Frequently Asked Questions

Why must I open the .xcworkspace instead of the .xcodeproj?

The hallelujah.xcworkspace file includes the CocoaPods dependency management configuration required to link the static libmarisa.a library and other external dependencies. Opening the standalone hallelujah.xcodeproj file results in linker errors because the Marisa trie library and pod headers referenced by src/ConversionEngine.mm will not be found.

What is the difference between Debug and Release builds?

Debug builds include optimization disabled and verbose logging enabled in src/main.mm, making them suitable for development and troubleshooting. Release builds enable compiler optimizations and strip debug symbols, producing a smaller, faster bundle intended for distribution. Both configurations set INSTALL_PATH to $(LOCAL_LIBRARY_DIR)/Input Methods/, preparing the bundle for the correct installation directory.

Do I need to restart my Mac after installing the input method?

A full restart is not required, but you must either log out and back in or manually add the input method via System Settings → Keyboard → Input Sources. macOS caches the available input methods at login; simply copying the bundle to /Library/Input Methods/ does not immediately register it with the Text Input Menu without refreshing the session or explicitly adding it in System Settings.

Can I install the input method only for my user account without using sudo?

Yes. Instead of copying to /Library/Input Methods/, install to ~/Library/Input Methods/ (the user-specific Library folder). This does not require administrator privileges:

cp -R hallelujah.app ~/Library/Input\ Methods/

However, system-wide installation is generally recommended for input methods to ensure consistency across all user accounts and to follow macOS conventions for third-party input method bundles.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}