Extended Bundler Errors is a
bundler plugin that makes gem installation errors more actionable, educative, and all around easier to understand.
Previously when gems fail,
bundler would simply tell you it failed and give you any output from the gem itself. This often includes C traces from native extensions.
These are hard to follow, particularly for people new to Ruby, because it requires you to understand the underlying system, programs in use (Imagemagick, SSL libraries, parsers, etc), and the output is simply verbose.
This gem instead will try to match the output of the gem to a series of handlers (see
lib/extended_bundler/handlers for a list). Each handler is specific to a gem, an matches one of many potential output. Once matched, we replace the error with something that explains the known problem, how to fix it, and (if possible) include a link to the original output.
Before when RMagick fails to install, you got a verbose log.
After when it fails to install you get a specific, actionable reason and step-by-step guide on how to handle it.
While this is a gem, you need to install it as a Bundler plugin:
bundler plugin install extended_bundler-errors
bundler plugin install extended_bundler-errors --git=https://github.com/jules2689/extended_bundler-errors.git
It is recommended to install from
git and work directly in a
bundle install run.
You can also...
After checking out the repo, run
bin/setup to install dependencies. Then, run
rake test to run the tests. You can also run
bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run
bundle exec rake install. To release a new version, update the version number in
version.rb, and then run
bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the
.gem file to rubygems.org.
Adding special handling for a bad error message
Errors will happen so we want to make sure we can respond to them properly. Instead of finding an answer on StackOverflow or somewhere ese, let's make sure everyone in the future can get a better error message directly in their terminal during the install.
To do this, you should:
- Create a file under lib/extended_bundler/handlers named "GEM_NAME.yml"
- Start with this template:
- versions: all matching: - "Matching Text" messages: en: | My Message
- Customize the template.
Customizing the template
There are a few keys to keep in mind:
versionscan be the word
allor a hash with
- This is the versions to which the handler applies
matchingis an array of strings (escapped regex is ok) that will be applied against the original bad error message
- You should find a unique string(s) that identifies a specific error
messagesis a hash of messages that we might be able to give to a user
enis required and is the default/English response
- Other language iso codes can be provided. Users will be given a response based on their
LANGenv var setting
Note, this is an array of "matchers". We will try each one iteratively against the
GEM_NAME until the first one matches. So if you have multiple handlers for a single gem, just continue expanding the yaml file.
Bug reports and pull requests are welcome on GitHub at https://github.com/jules2689/extended_bundler-errors. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.
Code of Conduct
Everyone interacting in the ExtendedBundler::Errors project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.