外掛程式

使用 RubyGems 外掛程式 API 的擴充功能。

RubyGems 會載入每個已安裝寶石的最新版本或 $LOAD_PATH 中的外掛程式。外掛程式必須命名為「rubygems_plugin」（.rb、.so 等）並放置在寶石的 #require_path 根目錄。外掛程式會安裝在特殊位置並在開機時載入。

製作您自己的外掛程式

第一步是遵循慣例檔案名稱，我們將在此範例中使用 ruby，並檢查我們的外掛程式是否正確載入

% 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:
[…]

當然，我們的外掛程式最好打包成寶石，這在 製作您自己的寶石 指南中有詳細說明。

掛鉤

RubyGems 提供各種掛鉤，我們可以使用這些掛鉤來新增自訂功能，甚至修改 RubyGems 的行為。例如，現有的掛鉤允許在安裝單一寶石之前、在建置之後、在安裝之後、在所有寶石安裝之後執行程式碼，以及許多其他功能（請參閱 Gem 的程式碼和文件作為參考）。

讓我們考慮一個簡單的範例外掛程式，它會在安裝 gem 之前互動式地要求確認，同時支援白名單。我們將利用 pre_install 掛鉤，將區塊傳遞給 Gem.pre_install 方法。閱讀此方法文件，我們瞭解到我們的掛鉤將使用 Gem::Installer 執行個體呼叫，而且我們可以傳回 false 以中止安裝

% 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

正如預期，RubyGems 會在每次 gem 安裝之前呼叫我們的掛鉤，而且當我們的掛鉤傳回 false 時，它會中止並提供說明。

如果您發現外掛程式系統 API 缺少您需求的擴充點，請閱讀 RubyGems 原始碼中的 CONTRIBUTING.rdoc，或參閱 貢獻指南。

指令

有些外掛程式也會將自己的指令新增到 RubyGems CLI。例如，下面列出的 graph 外掛程式會以這種方式註冊自己的 graph 指令

require 'rubygems/command_manager'

Gem::CommandManager.instance.register_command :graph

並以類似於此的方式實作指令

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

然後，我們可以透過執行 gem graph 來使用它，而且它也會像其他 RubyGems 內建指令一樣有文件說明 (gem help commands、gem help graph… 等)。

現有外掛程式

以下 RubyGems 外掛程式清單可能尚未完整。如果您知道我們遺漏的外掛程式，請隨時更新此頁面。

• 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

executable-hooks

https://github.com/mpapis/executable-hooks

擴充 rubygems 以支援可執行檔外掛程式。

在 gem lib 目錄中建立 rubygems_executable_plugin.rb

Gem.execute do |original_file|
  warn("Executing: #{original_file}")
end

gem-browse

https://github.com/tpope/gem-browse

新增四個指令

• gem edit 在你的編輯器中開啟一個 gem
• gem open 在你的編輯器中開啟一個 gem
• gem clone 從 GitHub 複製一個 gem
• gem browse 在你的瀏覽器中開啟一個 gem 的首頁

gem-empty

https://github.com/rvm/gem-empty

新增指令 gem empty 以從目前的 GEM_HOME 中移除所有 gem。

gem-ctags

https://github.com/tpope/gem-ctags

新增 gem ctags 指令，用於對已安裝的 gem 呼叫 Exuberant Ctags 編制索引，然後在安裝 gem 時自動呼叫它。

gem_info

https://github.com/oggy/gem_info

新增 gem info 指令，並針對名稱和版本進行模糊比對。專為腳本使用而設計。

gem-init

https://github.com/mwhuss/gem-init

新增 gem init 以建立一個精簡的 gem。

gem-compare

https://github.com/fedora-ruby/gem-compare

新增 gem compare 指令，可協助你透過比較 gemspec 值、gemspec 和 Gemfile 相依關係以及檔案，來追蹤已發佈 .gem 檔案中的上游變更。

gem-man

https://github.com/defunkt/gem-man

gem man 指令可讓你檢視 gem 的手冊頁面。

gem-nice-install

https://github.com/voxik/gem-nice-install

嘗試安裝系統相依關係，以使用標準 gem install 指令安裝具有二進位擴充功能的 gem。目前僅適用於 Fedora，但希望未來能擴充。

gem-orphan

https://github.com/sakuro/gem-orphan

新增 gem orphan 指令，用於尋找並列出沒有其他 gem 相依的 gem。

gem-patch

https://github.com/strzibny/gem-patch

新增 gem patch 指令，可讓你直接在 .gem 檔案上套用修補程式。支援 RubyGems 1.8 和 RubyGems 2.0。

gem-toolbox

https://github.com/gudleik/gem-toolbox

新增六個指令

• gem open - 在預設編輯器中開啟 gem
• gem cd - 將工作目錄變更為 gem 的來源根目錄
• gem readme - 找出並顯示 gem 的 readme 檔案
• gem history - 找出並顯示 gem 的變更日誌
• gem doc - 在預設瀏覽器中瀏覽 gem 的文件
• gem visit - 在預設瀏覽器中開啟 gem 的首頁

gem-wrappers

https://github.com/rvm/gem-wrappers

建立 gem 封裝，以便在 cron 和其他系統位置中輕鬆使用 gem。預設情況下，封裝會在安裝 gem 時安裝。

新增下列指令

• gem wrappers regenerate - 強制為所有 gem 可執行檔重新建立封裝
• gem wrappers - 顯示目前的組態

graph

https://github.com/seattlerb/graph

新增 gem graph 指令，以 graphviz 的 dot 格式輸出 gem 相依圖。

maven_gem

https://github.com/jruby/maven_gem

新增 gem maven，用於安裝任何 Maven 發布的 Java 函式庫，就像安裝 gem 一樣。

manpages

https://github.com/bitboxer/manpages

將 gem 內部的 manpage 顯示在 man 指令中，無需呼叫 gem man 或其他指令來閱讀 gem 的 manpage。

open_gem

https://github.com/adamsanderson/open_gem

新增兩個指令

• gem open 在預設編輯器中開啟 gem
• gem read 在預設瀏覽器中開啟 gem 的 rdoc

push_safety

https://github.com/jdleesmiller/push_safety

將白名單套用於 gem push，以防止意外將私人 gem 推送到公開的 RubyGems 儲存庫。

rbenv-gem-rehash

https://github.com/sstephenson/rbenv-gem-rehash

在安裝或解除安裝 gem 後自動執行 rbenv rehash。

此外掛程式已不再使用，因為其行為現已包含在 rbenv 核心。

rubygems-desc

https://github.com/chad/rubygems-desc

新增 gem desc，用於根據名稱描述 gem。

rubygems-openpgp

https://github.com/grant-olson/rubygems-openpgp

新增指令和旗標，允許使用 OpenPGP 簽署 gem。

• gem sign foo.gem 用於簽署 gem。
• gem verify foo.gem --trust 用來驗證 gem。
• gem build foo.gemspec --sign 用於在建置時簽署。
• gem install foo --verify --trust 用於在安裝時驗證。

rubygems-sandbox

https://github.com/seattlerb/rubygems-sandbox

使用 gem sandbox 指令管理命令列 gem 工具和依賴項。這讓您可以在全球 rubygems 儲存庫之外安裝 flay 和 rdoc 等項目。

rubygems_snapshot

https://github.com/rogerleite/rubygems_snapshot

新增 gem snapshot 以建立所有目前 gem 的匯出，並儲存成單一檔案，以便您稍後匯入。

specific_install

https://github.com/rdp/specific_install

讓您直接從 GitHub 儲存庫安裝「邊緣」gem，或從任意網路 URI 安裝 gem。

rubygems-tasks

https://github.com/postmodern/rubygems-tasks

rubygems-tasks 提供中立且不顯眼的 Rake 任務，用於建置、安裝和釋出 Ruby Gems。

rubygems_plugin_generator

https://github.com/brianstorti/rubygems_plugin_generator

rubygems_plugin_generator 是用於產生外掛程式的外掛程式。只要執行 gem plugin <name>，即可開始使用。