psych ライブラリのビルドエラー: yaml.h not found を解決する

問題の概要

Ruby Gem のインストール中に、psych（YAMLを処理するためのライブラリ）で以下のエラーが発生しました。

checking for yaml.h... no
yaml.h not found

以下詳細です。

C:\Users\<ユーザー名>>gem install rails
Using rubygems directory: C:/Users/<ユーザー名>/.local/share/gem/ruby/3.1.0
Temporarily enhancing PATH for MSYS/MINGW...
Installing required msys2 packages: mingw-w64-ucrt-x86_64-libyaml
エラー: 処理を始められませんでした（データベースをロックできませんでした: Permission denied）
pacman failed with the following output:
Building native extensions. This could take a while...
ERROR: Error installing rails:
ERROR: Failed to build gem native extension.

current directory: C:/Users/<ユーザー名>/.local/share/gem/ruby/3.1.0/gems/psych-5.2.3/ext/psych
C:/Ruby31-x64/bin/ruby.exe -I C:/Ruby31-x64/lib/ruby/3.1.0 extconf.rb
checking for yaml.h... no
yaml.h not found
*** extconf.rb failed ***
Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.

Provided configuration options:
    --with-opt-dir
    --without-opt-dir
    --with-opt-include
    --without-opt-include=${opt-dir}/include
    --with-opt-lib
    --without-opt-lib=${opt-dir}/lib
    --with-make-prog
    --without-make-prog
    --srcdir=.
    --curdir
    --ruby=C:/Ruby31-x64/bin/$(RUBY_BASE_NAME)
    --with-libyaml-source-dir
    --without-libyaml-source-dir
    --with-yaml-0.1-dir
    --without-yaml-0.1-dir
    --with-yaml-0.1-include
    --without-yaml-0.1-include=${yaml-0.1-dir}/include

このエラーは、libyaml のヘッダーファイルが見つからないことに起因しており、特に MSYS2 環境でのセットアップ中に発生することがよくあります。

警告
また、以下のようなエラーも関連して報告されることがあります。

• Permission denied
• Could not create Makefile due to some reason
• pacman failed with the following output

問題解決の背景

このエラーは、Ruby のバージョンを入れ直しても解決できませんでした。問題の原因は、MSYS2環境やlibyamlライブラリの不足、またはPATH設定が適切でないことに起因している可能性が高いと判明しました。

主な原因

このエラーの主な原因は

1. libyamlがインストールされていない.
   psych ライブラリのビルドには libyaml が必要です
2. MSYS2パッケージが適切にインストールされていない
   必要なツールチェーンやパッケージが不足している可能性があります
3. データベースロックやパーミッションの問題
   MSYS2でのパッケージ管理中にデータベースがロックされ、パッケージのインストールが失敗します

MSYS2とは

MSYS2（Minimal System 2）は、Windows上でUnix系のツールやソフトウェアを利用するための環境を提供するソフトウェアです。特に、RubyやRailsをセットアップする際のビルドツールやライブラリの依存関係を管理するためによく使用されます。

libyamlとは

libyamlとはdatabase.ymlやstorage.ymlなどのYAMLファイルをRailsが正しく読み込むために必要なライブラリです。Rubyのpsychライブラリが、このlibyamlに依存しているため、yaml.hというヘッダーファイルが必要になります。

Rails 7の環境構築におけるlibyamlの必要性

Rubyには標準ライブラリとしてpsychというYAML処理用ライブラリが含まれています。このpsychはlibyamlをバックエンドとして使用しています。そのため、libyamlがインストールされていない場合、先ほどのようなエラーが発生します。

libyaml と psych の関係

簡単に説明すると、libyamlは「エンジン部分」にあたります。YAMLデータを解析・生成する低レベルの処理を担当します。psychは「ユーザーインターフェース部分」にあたります。Rubyプログラムから簡単にYAMLを扱えるようにする高レベルのAPIを提供します。
もっと言うと、
libyaml を工場の機械、psych をお店の販売員 と考えます。
libyaml（機械）は、原料（YAMLファイル）を加工し、商品（データ構造）を作ります。
psych（販売員）は、その商品をユーザー（Rubyプログラム）に渡す役割を担います。

解決手順

以下の手順でエラーを解決します。

1. 必要なライブラリをインストール
   libyamlをMSYS2経由でインストールします。

   pacman -S mingw-w64-ucrt-x86_64-libyaml
   

   このコマンドにより、yaml.hファイルを提供するライブラリがインストールされます。

2. 必要なパッケージを確認
   エラーが特定のライブラリの不足に関連している場合、以下のコマンドを実行して必要なパッケージがインストールされているか確認しました。

   • libyaml の確認
     YAML処理に必要なライブラリが正しくインストールされているか確認

     pacman -Q mingw-w64-ucrt-x86_64-libyaml
     

   • gccやmakeの確認
     ツールチェーンが動作していることを確認

     gcc --version
     make --version
     

     これらのコマンドをなぜ使用するのかというと、Railsや関連Gemには、C言語のコードを含むネイティブ拡張が存在します（psych, nokogiriなど）。これらの拡張は、Windows環境ではgccやmakeを使ってビルドする必要があルため、これらのコマンドで事前に動作するか確認することができます。

3. PATH の設定
   MSYS2 環境で必要なパスが設定されていない場合、以下を実行します：

   export PATH=/mingw64/bin:$PATH
   

4. Rails のインストールを再試行
   psych が正常にビルドできるようになったら、Rails をインストールします。

   gem install rails
   

確認手順

yaml.h が利用可能か確認
以下のコマンドで yaml.h が見つかるかを確認します：

pacman -Q mingw-w64-ucrt-x86_64-libyaml

出力例👇

mingw-w64-ucrt-x86_64-libyaml 0.2.5-2

Rails のバージョン確認

rails -v

正しいバージョンが表示されれば成功です。

解決のポイント

• pacmanコマンドでlibyamlを確実にインストール
• PATH設定の確認：/mingw64/bin が正しく設定されていることを確認。
• MSYS2 環境の整備：必要なツールチェーンがインストールされていること。

まとめ

この記事では、psych ライブラリのビルドエラー（yaml.h not found）を解決するための手順を解説しました。MSYS2 環境での設定が適切であれば、問題なく Rails をインストールできます。同様のエラーが発生した場合は、この記事を参考に対応してください。