If you’re working with Ruby on Rails on a Mac, you might have encountered issues installing the mysql2 gem. One common problem is the failure in building a native extension, which can be frustrating especially when you think you’ve installed all the necessary dependencies correctly.
The mysql2 gem requires certain libraries and tools to be present on your system to compile its native extensions. However, even with the right dependencies seemingly in place, the installation might still fail. This is often due to missing or improperly configured system libraries, or issues related to the development headers of MySQL itself. Or something else, I honestly give up on finding the underlaying issue sometimes.
Anyhow, here’s the step you can take to solve this issue:
1. Checking the gem_make.out for Missing Dependencies
When the mysql2 gem installation fails, the first step towards troubleshooting is to check the gem_make.out file. This file is created during the gem installation process and contains detailed logs of what went wrong. It’s not the easiest to read, becuase you’ll see a log of the build process. What you’re looking for are error messages, often towards the end of the file. These messages will often indicate what is missing or misconfigured.
Two of the most common culprits are zlib and mysql-client. If these are missing or not properly configured, the gem installation will fail. zlib errors are pretty straightforward, mysql-client can be more criptic, like missing function rb_enc_interned_str.
2. Get Info on Installed Dependencies
Now it’s time to use brew info, as it will provide us with important information lib and headers we need to compile mysql2.
Run either:
brew info zlib
brew info mysql-client
Of course you have to have them installed. If you have them on your system they’ll provide you with details like this:
==> Caveats
mysql-client is keg-only, which means it was not symlinked into /opt/homebrew,
because it conflicts with mysql (which contains client libraries).
If you need to have mysql-client first in your PATH, run:
echo 'export PATH="/opt/homebrew/opt/mysql-client/bin:$PATH"' >> ~/.zshrc
For compilers to find mysql-client you may need to set:
export LDFLAGS="-L/opt/homebrew/opt/mysql-client/lib"
export CPPFLAGS="-I/opt/homebrew/opt/mysql-client/include"
For pkg-config to find mysql-client you may need to set:
export PKG_CONFIG_PATH="/opt/homebrew/opt/mysql-client/lib/pkgconfig"
3. Modify .bundle/config to Configure MySQL2 Compilation Options
Bundle has interesting system to allow you a little bit more control. It’s through a file located at .bundle/config. Open it with a text editor and write a line like this:
BUNDLE_BUILD__MYSQL2: "--with-mysql-lib=/opt/homebrew/opt/mysql-client/lib --with-mysql-dir=/opt/homebrew/opt/mysql-client/ --with-mysql-config=/opt/homebrew/opt/mysql-client/bin/mysql_config --with-mysql-include=/opt/homebrew/opt/mysql-client/include --with-ldflags=-L/opt/homebrew/opt/zlib/lib"
Now, --with-mysql-lib, --with-mysql-dir, --with-mysql-config, --with-mysql-include are for configuring mysql-client. You can see how values correspond to the information from brew info.
Similarly --with-ldflags points to ldflags of zlib. Make sure you don’t forget -L at the beginning.
Done!
It worked for me as intended. Hopefully this will help you as well. In the struggling with Ruby on Mac series I wrote recently on switching from RVM to rbenv, as it seems to play nicer with openssl.