How to install the locomotivecms_wagon gem on a Mac

Published by Moncef Belyamani on
Updated on

While this guide uses the locomotivecms_wagon gem as an example, the main goal is to teach you how Rubygems and gem versioning work so you can troubleshoot issues like this more confidently in the future.

If you’ve been trying to install the locomotivecms_wagon gem on a Mac using Ruby version 3.x, you probably got an error like the one below about failing to build the gem native extension while intalling thin 1.6.4:

Building native extensions. This could take a while...
ERROR: Error installing locomotivecms_wagon:
ERROR: Failed to build gem native extension.

current directory: /Users/some_user/.asdf/installs/ruby/3.3.2/lib/ruby/gems/3.3.0/gems/thin-1.6.4/ext/thin_parser

thin.c:242:3: error: call to undeclared function 'thin_http_parser_init'; ISO C99 and later do not support implicit function declarations [-Wimplicit-function-declaration]
  thin_http_parser_init(hp);

thin.c:338:8: error: call to undeclared function 'thin_http_parser_has_error'; ISO C99 and later do not support implicit function declarations [-Wimplicit-function-declaration]

Your next step might be to search for one of those error messages, which is perfectly reasonable. However, the “solutions” you might find will most likely not be helpful, and could create more issues.

For example, you might come across advice to install a gem by passing the following cflags option:

gem install thin -v '1.8.0' -- --with-cflags="-Wno-error=implicit-function-declaration"

I do not recommend using --with-cflags="-Wno-error=implicit-function-declaration" ever. In my 12+ years of working with Ruby, I’ve never had to use that flag. While it might allow a gem or Ruby to be installed in some cases, it is never the appropriate solution, and can cause issues down the line that you will have a very hard time troubleshooting, resulting in more wasted time.

To understand why we’re getting an error related to thin version 1.6.4, you have to understand how Rubygems and gem versioning work.

When you run gem install locomotivecms_wagon using a newer version of Rubygems (such as when using Ruby 3.3.x), it will try to install the latest version by default, and if it can’t, it will keep trying different versions until it finds the right combination of gems. Here are the steps it takes:

  1. Find the latest version of locomotivecms_wagon that is not a prerelease version (such as alpha, beta, or other “non-official” release). This is 3.1.1 as of today, as you can see on the Rubygems site: https://rubygems.org/gems/locomotivecms_wagon/

  2. Go through each runtime dependency of version 3.1.1 and see if it allows Ruby version 3.3.2. This fails because version 3.1.1 of locomotivecms_wagon depends on version 0.4.x of locomotivecms_common, which only supports Ruby versions 2.x: https://rubygems.org/gems/locomotivecms_common/versions/0.4.0

  3. Keep going down the versions of locomotivecms_common until it finds one that works with Ruby 3.x, if any, and that version is 1.5.8, which was released in 2015, and it also depends on thin ~> 1.6.1, which means the latest version of thin you could possibly try to install is 1.6.4. Therefore, any suggestion you might find elsewhere online to install a newer version of thin will not help.

The reason why thin 1.6.4 can’t be compiled on newer macOS versions is because it was released in 2015, and Apple often makes changes to macOS and/or Xcode/command line tools that can cause older gems to fail to install.

So how do we install locomotivecms_wagon on a Mac?

You have a couple of options:

  • Install Ruby 2.7.8, which will allow you to install version 3.1.1 of locomotivecms_wagon, which doesn’t depend on thin anymore.

  • Install the latest alpha version of locomotivecms_wagon, which supports the latest Ruby version (3.4.6 as of today):

    gem install locomotivecms_wagon -v 3.2.0.alpha1

Once version 3.2.x of locomotivecms_wagon is officially released, you should be able to install it without issues using Ruby 3.x.

I hope this has been helpful!