layout | title | url | previous | next |
---|---|---|---|---|
default |
Plugins |
/plugins |
/faqs |
/credits |
Extensions that use the RubyGems plugin API.
RubyGems will load plugins in the latest version of each installed gem or
$LOAD_PATH
. Plugins must be named 'rubygems_plugin' (.rb, .so, etc) and
placed at the root of your gem's #require_path. Plugins are installed at a
special location and loaded on boot.
The first step is to follow the conventional file name, we will use ruby for this example and check that our plugin is loaded correctly:
% cat lib/rubygems_plugin.rb
puts 'hello from my plugin!'
% RUBYOPT=-Ilib gem
hello from my plugin!
RubyGems is a sophisticated package manager for Ruby. This is a
basic help message containing pointers to more information.
Usage:
[…]
Of course, our plugin would better be packaged as a gem, which is described in detail in the make your own gem guide.
RubyGems provides various hooks we can use to add custom features and
even modify how RubyGems behaves. For example, existing hooks allow
executing code before a single gem is installed, after it's built,
after it's installed, after all gem are installed and many others (see
code and documentation for Gem
as a reference).
Let's consider a simple example plugin that would ask confirmation
interactively before installing gems while supporting a whitelist. We
will leverage the pre_install
hook, passing a block to
Gem.pre_install
method. Reading this method documentation, we learn
that our hook will be called with a Gem::Installer
instance, and
that we can return false
to abort the installation:
% cat lib/rubygems_plugin.rb
WHITELIST_PATH = "#{ENV['HOME']}/.gem/install_audit/whitelist"
Gem.pre_install do |installer|
gem_name = installer.spec.name
whitelist = if File.exist? WHITELIST_PATH
File.read(WHITELIST_PATH).split
else
[]
end
unless whitelist.include? gem_name
print "`#{gem_name}' is not whitelisted, install? (y/n): "
case choice = $stdin.gets.chomp
when /\Ay/i
when /\An/i then next false
else fail "cannot understand `#{choice}'"
end
end
end
% echo rake > ~/.gem/install_audit/whitelist
% RUBYOPT=-Ilib gem install hoe
Fetching: rake-12.3.0.gem (100%)
Successfully installed rake-12.3.0
Fetching: hoe-3.16.2.gem (100%)
`hoe' is not whitelisted, install? (y/n): y
Successfully installed hoe-3.16.2
2 gems installed
% RUBYOPT=-Ilib gem install pry
Fetching: coderay-1.1.2.gem (100%)
`coderay' is not whitelisted, install? (y/n): n
ERROR: Error installing pry:
pre-install hook at /…/lib/rubygems_plugin.rb:3 failed for coderay-1.1.2
As expected, RubyGems calls our hook before each gem installation, and when our hook returns false, it aborts with an explanation.
If you find that the plugin system API lacks the extension point you
need for your needs, please read CONTRIBUTING.rdoc
in RubyGems
source code, or see the contributing guide.
Some plugins also add their own commands to the RubyGems CLI. As an
example, the graph
plugin listed below registers its own graph
command this way:
require 'rubygems/command_manager'
Gem::CommandManager.instance.register_command :graph
And implement the command similarly to this:
require 'rubygems/command'
class Gem::Commands::GraphCommand < Gem::Command
def initialize
super 'graph', 'Graph dependency relationships of installed gems'
end
def execute
# [real command implementation removed for this guide]
end
end
We can then use it by executing gem graph
, and it is also documented
like other RubyGems builtin commands (gem help commands
,
gem help graph
…).
The following list of RubyGems plugins is probably not exhaustive. If you know of plugins that we missed, feel free to update this page.
- executable-hooks
- gem-browse
- gem-ctags
- gem-empty
- gem_info
- gem-init
- gem-compare
- gem-man
- gem-nice-install
- gem-orphan
- gem-patch
- gem-toolbox
- gem-wrappers
- graph
- maven_gem
- manpages
- open_gem
- push_safety
- rbenv-gem-rehash
- rubygems-desc
- rubygems-openpgp
- rubygems-sandbox
- rubygems_snapshot
- specific_install
- rubygems-tasks
- rubygems_plugin_generator
https://github.com/mpapis/executable-hooks
Extends rubygems to support executables plugins.
In gem lib dir create rubygems_executable_plugin.rb:
Gem.execute do |original_file|
warn("Executing: #{original_file}")
end
https://github.com/tpope/gem-browse
Adds four commands:
gem edit
opens a gem in your editorgem open
opens a gem by name in your editorgem clone
clones a gem from GitHubgem browse
opens a gem's homepage in your browser
https://github.com/rvm/gem-empty
Adds command gem empty
to remove all gems from current GEM_HOME
.
https://github.com/tpope/gem-ctags
Adds a gem ctags
command to invoke the Exuberant Ctags indexer on already-installed gems, and then automatically invokes it on gems as they are installed.
https://github.com/oggy/gem_info
Adds a gem info
command with fuzzy matching on name and version. Designed for scripting use.
https://github.com/mwhuss/gem-init
Adds gem init
to create a barebones gem.
https://github.com/fedora-ruby/gem-compare
Adds gem compare
command that can help you to track upstream changes in the released
.gem files by comparing gemspec values, gemspec and Gemfile dependencies and files.
https://github.com/defunkt/gem-man
The gem man
command lets you view a gem's man page.
https://github.com/voxik/gem-nice-install
Tries to install system dependencies needed to install your gems with binary extensions
using standard gem install
command. This currently works only for Fedora, but
hopefully will be extended.
https://github.com/sakuro/gem-orphan
Adds a gem orphan
command that finds and lists gems on which no other gems are depending.
https://github.com/strzibny/gem-patch
Adds gem patch
command, which enables you to apply patches directly on .gem
files.
Supports both RubyGems 1.8 and RubyGems 2.0.
https://github.com/gudleik/gem-toolbox
Adds six commands:
gem open
- opens a gem in your default editorgem cd
- changes your working directory to the gem's source rootgem readme
- locates and displays a gem's readme filegem history
- locates and display's a gem's changeloggem doc
- Browse a gem's documentation in your default browsergem visit
- Open a gem's homepage in your default browser
https://github.com/rvm/gem-wrappers
Create gem wrappers for easy use of gems in cron and other system locations. By default wrappers are installed when a gem is installed.
Adds this commands:
gem wrappers regenerate
- force rebuilding wrappers for all gem executablesgem wrappers
- show current configuration
https://github.com/seattlerb/graph
Adds a gem graph
command to output a gem dependency graph in graphviz's dot format.
https://github.com/jruby/maven_gem
Adds gem maven
to install any Maven-published Java library as though it were a gem.
https://github.com/bitboxer/manpages
Exposes manpages inside of a gem to the man
command without the need to call gem man
or
another command to read the man page of a gem.
https://github.com/adamsanderson/open_gem
Adds two commands:
gem open
opens a gem in your default editorgem read
opens a gem's rdoc in your default browser
https://github.com/jdleesmiller/push_safety
Applies a whitelist to gem push
to prevent accidentally pushing private gems to the public RubyGems repository.
https://github.com/sstephenson/rbenv-gem-rehash
Automatically runs rbenv rehash
after installing or uninstalling gems.
This plugin is deprecated since its behavior is now included in rbenv core.
https://github.com/chad/rubygems-desc
Adds gem desc
to describe a gem by name.
https://github.com/grant-olson/rubygems-openpgp
Adds commands and flags to allow OpenPGP signing of gems.
gem sign foo.gem
to sign a gem.gem verify foo.gem --trust
to verify a gem.gem build foo.gemspec --sign
to sign at build time.gem install foo --verify --trust
to verify on install.
https://github.com/seattlerb/rubygems-sandbox
Manages command-line gem tools and dependencies with a gem sandbox
command. This lets you install things like flay and rdoc outside of the global rubygems repository.
https://github.com/rogerleite/rubygems_snapshot
Adds gem snapshot
to create exports of all your current gems into a single file that you can import later.
https://github.com/rdp/specific_install
Allows you to install an "edge" gem straight from its GitHub repository, or install one from an arbitrary web URI.
https://github.com/postmodern/rubygems-tasks
rubygems-tasks provides agnostic and unobtrusive Rake tasks for building, installing and releasing Ruby Gems.
https://github.com/brianstorti/rubygems_plugin_generator
rubygems_plugin_generator
is a plugin that generates plugins. Just run gem plugin <name>
and you are good to go.