구름입력기 소스 빌드 설치 가이드 — Caps Lock 한영 전환까지

macOS에서 세벌식을 쓰거나, 한영 전환을 Caps Lock에 물려두고 싶다면 선택지가 많지 않다. 구름입력기는 그 좁은 선택지 중에서 가장 완성도 높은 오픈소스다.

공식 배포 패키지의 마지막 버전은 1.13.2 (2023년 4월)다. Homebrew Cask나 공식 사이트에서 받을 수 있는 버전이 이쪽이다. 그런데 GitHub 메인 브랜치를 보면 얘기가 다르다. Caps Lock 한영 전환 개선, 유니코드 16.0 이모지 사전 최신화 등 실사용에 바로 와닿는 패치들이 꾸준히 병합돼 왔다.

공식 릴리즈를 기다리는 대신 소스를 직접 빌드해서 쓰는 게 현재로서는 최신을 쓰는 유일한 방법이다.

릴리즈 이후 메인 브랜치에 추가된 것들

빌드를 결심하기 전에, 어떤 게 달라졌는지 먼저 확인해 보자.

Caps Lock으로 한/영 전환 (2026년 5월)

macOS 시스템 설정의 ‘Caps Lock 키로 입력 소스 전환’ 옵션을 구름입력기와 함께 쓰면 전환이 매끄럽지 않은 경우가 있었다. 서드파티 입력기가 macOS 네이티브 전환 플래그(TICapsLockLanguageSwitchCapable)를 명시적으로 선언하지 않으면 OS가 Caps Lock 이벤트를 제대로 전달하지 않기 때문이다.

최근 패치로 구름입력기가 지원하는 모든 16개 입력 소스(두벌식, 세벌식 계열, 쿼티, 드보락 등)에 이 플래그가 적용됐다. 이제 Caps Lock 한영 전환이 Apple 기본 입력기와 동일하게 동작한다.

유니코드 16.0 이모지 사전 최신화 (2026년 1월)

CLDR(Common Locale Data Repository)을 release-46-1 버전으로 업그레이드했다. 한자/이모지 후보 창에서 최신 이모티콘과 피부색 조합 이모지를 한국어 키워드로 바로 검색할 수 있다.

macOS Ventura 이상 시스템 설정 호환성

macOS 13부터 ‘시스템 환경설정’이 ‘시스템 설정’으로 개편되면서 깨졌던 AppleScript 연동이 수정됐다.

CocoaPods 제거

오래된 CocoaPods 의존성과 관련 빌드 스크립트를 완전히 걷어냈다. 빌드 속도가 빨라지고, make init 이후 설치해야 할 도구도 줄었다.

직접 빌드해서 설치하기

준비물

macOS Catalina(10.15) 이상
Xcode — App Store에서 설치 후 최초 실행(라이선스 동의)까지 완료
Homebrew — make init 내부에서 shellcheck, swiftformat을 brew로 설치

Xcode Command Line Tools만으로는 부족하다. 반드시 Xcode 앱 전체가 설치돼 있어야 한다.

1단계: 저장소 클론

git clone https://github.com/gureum/gureum.git
cd gureum

2단계: 개발 환경 초기화

make init

내부적으로 세 가지를 처리한다.

shellcheck, swiftformat Homebrew 설치
xcpretty 루비 젬 설치 (빌드 로그 포매터)
libhangul 서브모듈 클론 및 초기화 (한글 조합 엔진)

각 도구는 이미 설치된 경우 자동으로 건너뛴다. shellcheck, swiftformat, xcpretty가 모두 설치되어 있다면 git submodule update 한 줄만 실행되고 바로 끝난다. 처음 세팅하는 환경이라면 5~10분 정도 걸리며, 중간에 macOS 암호를 묻는 경우 잠금 해제 암호를 입력하면 된다.

3단계: 빌드 & 자동 설치

입력기를 Xcode에서 직접 실행하지 말 것

macOS 입력기(Input Method)는 OS가 생명주기를 관리하는 시스템 데몬이다. Xcode에서 ▶ Run을 누르거나 .app을 더블클릭하면 키보드 입력이 멈추거나 먹통이 될 수 있다. 반드시 아래 스크립트를 통해서만 설치할 것.

./tools/install_debug.sh

이 스크립트가 한 번에 처리하는 일:

xcodebuild로 앱 빌드
/Library/Input Methods/ 디렉토리에 빌드 결과물 복사 (sudo 권한 필요)
기존에 실행 중인 구름입력기 프로세스를 안전하게 교체 (Hot reload)

설치가 끝나면 터미널에 Done. 또는 완료 메시지가 출력된다.

4단계: 시스템 설정에서 입력 소스 등록

설치 직후 기존 입력 소스 목록에서 구름입력기가 사라진 것처럼 보일 수 있다. 다음 순서로 다시 추가하면 된다.

시스템 설정 → 키보드 → 입력 소스 로 이동
+ 버튼 클릭
한국어 탭에서 원하는 구름 자판 선택 (예: 두벌식 구름, 세벌식 390 구름)
Caps Lock 전환을 쓰고 싶다면 ‘Caps Lock 키로 입력 소스 전환’ 옵션 활성화

빌드 오류 해결

`xcode-select: error: tool 'xcodebuild' requires Xcode`

Xcode 앱이 아닌 Command Line Tools 경로를 바라보고 있을 때 발생한다.

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

이후 make init 또는 ./tools/install_debug.sh 를 다시 실행한다.

`unable to resolve module dependency: 'SwiftIOKit'`

Preferences 타깃에 SwiftUp 패키지 의존성이 빠져 있을 때 발생한다. SwiftIOKit은 별도 패키지가 아니라 SwiftUp 안에 포함된 모듈이기 때문에, SwiftUp을 직접 링크해야 한다.

Xcode에서 Gureum.xcodeproj 열기
좌측 Project Navigator에서 Gureum 프로젝트 선택
TARGETS → Preferences 선택
General 탭 → Frameworks, Libraries, and Embedded Content
+ 클릭 → SwiftUp 선택 → Add

이후 ./tools/install_debug.sh를 다시 실행한다.

`xcpretty: command not found`

make init 중 루비 젬 설치가 실패했을 때 나타난다.

sudo gem install xcpretty

Apple Silicon Mac에서 시스템 루비(/usr/bin/gem)와 Homebrew로 설치한 루비가 혼재할 경우, rbenv 또는 rvm으로 관리하는 루비 버전이 활성화된 상태인지 확인한다.

마치며

공식 릴리즈 주기가 느린 건 아쉽지만, 메인 브랜치는 꽤 활발하다. 한 번 빌드 환경을 세팅해 두면 이후에는 git pull && ./tools/install_debug.sh 두 줄로 최신 상태를 유지할 수 있다.

Caps Lock 한영 전환을 오래 기다려 왔다면, 지금이 직접 빌드를 시도해 볼 좋은 타이밍이다.

버그나 이슈는 GitHub Issues나 공식 디스코드에서 개발자와 직접 소통할 수 있다.