맥북에서 Jekyll 설치하며 만난 오류들, 이렇게 해결했다!

- 목차 -

🤯 시작은 Gem::FilePermissionError
💥 호환성 지옥
💡 해결 방법
🎉 드디어 bundle install
마무리 🥺🎊

안녕하세요! 오늘은 맥북에서 Jekyll 블로그를 시작하려다 겪었던 난관들과 그 해결 과정을 상세히 공유해 보려 합니다. 사실 체념을 하고 맥북으로는 블로그 글을 쓰지 않고 있었습니다. 그래도 이제는 정말 해결해보고 싶었어요! 끝까지 파헤쳐보자는 마음으로 시작하게 됐습니다.

🤯 시작은 `Gem::FilePermissionError`

Jekyll은 Ruby 기반의 정적 사이트 생성 도구이죠! 지금 현재 제 블로그도 Jekyll로 작성이 되어있고 관련 글도 몇 개 작성했었는데요, Jekyll을 사용하려면 Ruby 환경 설정이 필수죠. 처음은 window에서 시작을 했고 맥북을 사게 돼서 맥북으로 옮겨왔습니다. 맥북에 rbenv로 설치를 하고 나서 💥 처음 gem install bundler 명령어를 입력하자마자 오류가 발생했습니다. 그 때 당시에도 해결해보려고 열심히 나름 노력은 했지만 외면하고 있다가 오늘 처음부터 시작을 해보았습니다.

오늘 제가 처음 받은 오류였습니다.

ERROR: While executing gem ... (Gem::FilePermissionError)
You don't have write permissions for the /Library/Ruby/Gems/2.6.0 directory.

📌 오류 원인 분석

permission 오류!! 이 오류는 정말 익숙합니다. 권한문제 ! 이 오류는 맥북에 기본으로 설치된 시스템 Ruby의 특징 때문에 발생합니다. macOS는 시스템의 안정성과 보안을 위해 /Library/Ruby/Gems 같은 시스템 디렉토리에 일반 사용자가 임의로 파일을 쓰거나 변경할 수 없도록 권한을 제한한다고 합니다. 제가 gem install을 했을 때, rbenv가 아닌 이 시스템 Ruby 환경에서 설치를 시도해서 발생한 문제였습니다.

💡 해결 방법

가장 깔끔한 해결책은 rbenv가 관리하는 Ruby 환경을 사용하는 것입니다.

rbenv가 관리하는 Ruby 버전으로 전환:
```
rbenv global [원하는 Ruby 버전] # 예: rbenv global 3.2.3
# 또는 특정 프로젝트 폴더에서만 사용하려면:
# rbenv local [원하는 Ruby 버전]
```
저는 이미 rbenv로 Ruby 3.1.4 (나중에는 3.2.3)를 설치해 두었기 때문에 해당 버전으로 전환했습니다.
bundle install 다시 시도: rbenv를 통해 올바른 Ruby 환경으로 전환한 뒤 다시 설치를 시도했습니다.

💥 호환성 지옥

bundler와 google-protobuf, 그리고 eventmachine

권한 문제는 해결했지만, 새로운 버전 충돌 문제들이 줄줄이 나타났습니다. 여기부터가 정말 지옥이었습니다. 자바스크립트를 주 언어로 사용하는 저는 package.json 으로 몇번 맛보았었죠… 이제 나름 적응이 됐다고 생각했었는데, 여기는 정말 지옥이었어요. 😭

오류 1: bundler와 Ruby 버전 불일치


bundler requires Ruby version \>= 3.1.0. The current ruby version is 2.7.8.225.

📌 오류 원인 분석

이는 설치하려는 bundler 버전이 Ruby 3.1.0 이상을 요구하는데, 당시 Ruby 버전이 2.7.8이었기 때문에 발생한 호환성 문제였습니다.

💡 해결 방법

bundler 구버전 설치 (임시방편) bundler는 하위 Ruby 버전을 지원하는 구 버전이 있습니다. 오류 메시지에서 안내해 준 대로 gem install bundler -v 2.4.22를 시도했습니다.
Ruby 버전 업그레이드 (권장) 결과적으로 Jekyll 설치를 위해 Ruby 버전을 3.1.4 (이후 3.2.3)로 업그레이드하기로 했습니다. rbenv를 사용하면 매우 간단합니다.
```
 rbenv install 3.2.3 # 원하는 최신 안정 Ruby 3.x 버전
 rbenv global 3.2.3
```

오류 2: google-protobuf와 Ruby 버전 불일치

Ruby 버전을 3.1.4로 올린 후 다시 bundle install을 시도하자 이번에는 google-protobuf라는 Gem에서 문제가 발생했습니다.

google-protobuf requires Ruby version \>= 3.1, \< 3.5.dev. The current ruby version is 2.7.8.225.

📌 오류 원인 분석

이번에도 Gem과 Ruby 버전 간의 호환성 문제였습니다. jekyll의 의존성인 google-protobuf가 Ruby 3.1 이상을 요구하는데, 제가 작업하고 있는 환경이 2.7.8로 인식되면서 발생한 것이었습니다.

💡 해결 방법

이 문제는 Ruby 버전을 3.1.4 (또는 3.2.3)로 확실히 전환한 후 다시 bundle install을 시도함으로써 해결되었습니다. rbenv로 Ruby 버전을 전환하고 터미널을 다시 시작하거나 source ~/.zshrc 등으로 환경을 재설정하는 것이 중요했습니다.

오류 3: 고질적인 eventmachine 빌드 실패

가장 오랜 시간 저를 괴롭혔던 오류입니다. 몇 번을 다시 설치하고 삭제하고 권한 찾고 업데이트 해보고 아주 모든 짓을 다했습니다. jekyll 4.x 버전까지 올렸는데도 계속해서 eventmachine-1.2.7이라는 Gem에서 빌드 실패 오류가 발생했습니다.

ERROR: Failed to build gem native extension.
......
make: \*\*\* [binder.o] Error 1

📌 오류 원인 분석

eventmachine-1.2.7은 Ruby 2.x 시절에 주로 사용되던 오래된 Gem입니다. 이 Gem은 C++ 코드를 포함하고 있어 설치 시 사용자의 시스템에서 컴파일(빌드)되어야 하는데, Ruby 3.x 버전의 내부 API 변경 사항과 호환되지 않아 컴파일에 실패하는 것이었습니다. binder.cpp 파일 컴파일 오류는 이 호환성 문제로 인해 발생한 것입니다.

xcode-select --install로 Command Line Tools를 재설치하고, Homebrew로 OpenSSL 경로를 명시해 줘도 해결되지 않았던 이유도 여기에 있었습니다. 기본적인 빌드 도구는 갖춰졌지만, Gem 자체의 소스 코드가 최신 Ruby 버전에 맞지 않았던 것입니다.

💡 해결 방법

eventmachine-1.2.7을 Ruby 3.x에서 빌드하는 것은 거의 불가능 이라고 생각했어요. 따라서 이 Gem에 대한 의존성을 우회하는 방법을 선택했습니다. 이런 버전 문제는 내 문제가 아니라는 것을 일찍 알고, 그에 대응하는 방법을 찾는 것이 답입니다.

eventmachine 의존성 우회 (Jekyll Serve의 Live Reload 포기): eventmachine은 주로 jekyll serve 명령의 실시간 브라우저 리로드(Live Reload) 기능을 위해 em-websocket을 통해 사용됩니다. 만약 이 라이브 리로드 기능이 필수가 아니라면, em-websocket의 설치 자체를 막아서 eventmachine의 문제를 우회할 수 있습니다.

Gemfile을 열어 jekyll-feed 그룹 내부에 다음 한 줄을 추가했습니다.
```
  # Gemfile
  source "[https://rubygems.org](https://rubygems.org)"

  # ... (생략) ...

  group :jekyll_plugins do
    gem "jekyll-feed", "~> 0.17"
    # em-websocket의 설치를 의도적으로 막는 라인
    gem 'em-websocket', '>= 99.0', require: false
  end

  # ... (생략) ...
```
- gem 'em-websocket', '>= 99.0': em-websocket 99.0 버전 이상을 찾으라고 지시하여, 실제로는 존재하지 않는 버전을 요구함으로써 Bundler가 이 Gem을 설치할 수 없게 만듭니다.
- require: false: 만약 다른 Gem이 em-websocket을 필요로 하더라도 Ruby가 자동으로 로드하지 않도록 합니다.
이후 Gemfile.lock과 Bundler 캐시를 정리한 뒤 다시 bundle install을 실행했습니다.
```
  rm Gemfile.lock
  bundle cache clean --all
  bundle install
```

🎉 드디어 `bundle install`

수많은 오류를 만난 끝에, em-websocket의 의존성을 우회하는 방법으로 마침내 bundle install을 성공했습니다!

이제 Jekyll 사이트를 로컬에서 실행할 수 있습니다. 프로젝트 디렉토리로 이동하여 다음 명령어를 입력해줍니다.

bundle exec jekyll serve

마무리 🥺🎊

Jekyll 설치는 간단해 보이지만, Ruby 버전 관리, Gem 의존성, 그리고 시스템 환경 설정이 얽히면서 생각보다 복잡한 오류에 직면할 수 있습니다. 저처럼 eventmachine과 같은 오래된 Gem이 최신 Ruby 환경에서 컴파일되지 않는 문제는 자주 발생하곤 합니다.

이 문제를 해결 하고 나서 다시 한번 마음으로 되뇌이는 문장들

오류 메시지는 항상 자세히 읽기
- 모든 해결 방법은 오류 메시지에 들어있다. 👀
rbenv와 같은 버전 관리 도구를 적극적으로 활용하기
- 저는 이제 nvm 없으면 node 사용 못해요!
Gemfile과 Gemfile.lock을 이해하고 적절히 수정하는 것.
- 처음부터 이쪽 파일을 봤다면 이렇게까지 오래 걸릴 일은 아니었는데…

이 글이 Jekyll 설치 과정에서 어려움을 겪는 다른 분들에게 작은 도움이 되기를 바랍니다.

```

🤯 시작은 Gem::FilePermissionError

💥 호환성 지옥

💡 해결 방법

🎉 드디어 bundle install

마무리 🥺🎊

🤯 시작은 `Gem::FilePermissionError`

🎉 드디어 `bundle install`