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

> Learn to build and install Hallelujah Input Method from Xcode to /Library/Input Methods/. Follow these steps to easily integrate custom input methods into your macOS system.

- Repository: [dongyuwei/hallelujahim](https://github.com/dongyuwei/hallelujahim)
- Tags: how-to-guide
- Published: 2026-02-28

---

**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:

```bash
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:

```bash
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:

```bash

# 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:

```bash
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.