如何撰寫 Bundler 外掛程式

什麼是外掛程式？

Bundler 外掛程式是專門的寶石，用於整合和擴充 Bundler 的功能。本指南將協助您開始撰寫自己的 Bundler 外掛程式。

我為什麼要使用外掛程式？

外掛程式能夠整合和擴充 Bundler。
目前，外掛程式能夠

新增指令至 Bundler（例如：bundle my_command）
新增特殊處理程式來安裝寶石（例如：Mercurial 或 SVN）
新增功能至特定掛鉤點
- 所有可用掛鉤、其說明及其區塊引數的清單可在 plugin/events.rb 檔案中取得。
- 注意：請務必查看您所使用 Bundler 版本中的 events.rb 檔案。

使用外掛程式

從指令安裝外掛程式

外掛程式可以從 RubyGems（預設）或 Git 伺服器安裝。若要使用機器上的寶石，您可以執行 bundler plugin install gem_name。外掛程式安裝後，指令將可供使用，而掛鉤將自動註冊至 Bundler。

執行 bundler plugin help install 以取得更多詳細說明和從 Git 安裝的說明。

在 Bundler 2.2.0 中，您可以使用 bundler plugin uninstall gem_name 進行解除安裝。

從 Gemfile 安裝外掛程式

您也可以在 Gemfile 中指定外掛程式

plugin 'my_plugin' # Installs from Rubygems
plugin 'my_plugin', path: '/path/to/plugin' # Installs from a path
plugin 'my_plugin', git: 'https://github.com:repo/my_plugin.git' # Installs from Git

開始開發

1. 建立寶石

在製作 Bundler 外掛程式之前，您需要先建立一個專門的寶石。

使用本指南建立寶石。完成後，回到本指南並繼續進行第二步。

2. 建立 plugins.rb 檔案

plugins.rb 檔案位於寶石資料夾的最上層，是 Bundler 用來呼叫外掛程式的進入點。這是一個 Ruby 檔案，用於定義您的指令、掛鉤和其他程式碼。通常，您可能只需要需要寶石最上層的 lib 檔案。

例如，如果您的寶石稱為「my_plugin」，您可能在 lib/my_plugin.rb 中有一個檔案，其中包含寶石的最高層級命名空間。您的 plugins.rb 檔案可能是

require 'my_plugin'

lib/my_plugin.rb 檔案會包含其他 require 陳述式、掛鉤和指令，類似於一般的寶石。

3. 製作 Bundler 指令

Bundler 指令讓您可以使用額外功能來擴充 Bundler 介面。

若要新增 Bundler 指令，您需要建立一個類別，將其自身（或另一個類別）註冊為指令。例如，若要新增對 bundler my_command 指令的支援，您可以建立一個類別，如下所示

class MyCommand < Bundler::Plugin::API
  # Register this class as a handler for the `my_command` command
  command "my_command"

  # The exec method will be called with the `command` and the `args`.
  # This is where you should handle all logic and functionality
  def exec(command, args)
    if args.empty?
      # Using BundlerError in plugins is recommended. See below.
      raise BundlerError, 'My plugin requires arguments'
    end
    puts "You called " + command + " with args: " + args.inspect
  end
end

或

module MyCommand
  # Register this class as a handler for the `my_command` command
  Bundler::Plugin::API.command('my_command', self)

  # The exec method will be called with the `command_name` and the `args`.
  # This is where you should handle all logic and functionality
  def exec(command_name, args)
    puts "You called " + command_name + " with args: " + args.inspect
  end
end

這兩個元素對於在 Bundler 中註冊命令很重要

Bundler::Plugin::API.command(COMMAND_NAME, CLASS) 或 command 'COMMAND_NAME' 會被呼叫，這取決於所使用的函式（請參閱上面的範例）
此類別定義實例函式 exec(command_name, args)

引發錯誤

如果發生問題，您的外掛程式應引發 BundlerError。不建議在外掛程式中引發例如 Exception，因為這將導致 Bundler 列印它自己的錯誤報告範本，要求使用者向 Bundler 本身報告錯誤。

若要詳細了解 bundler 如何救援錯誤，請查看 bundler/friendly_errors.rb。

4. 使用 Bundler 勾子

若要與 Bundler 的各個部分介面，您可以使用勾子。勾子讓您可以在特定事件中注入一些功能，方法是註冊以偵聽特定事件的發生。若要偵聽事件，您需要為其新增勾子並提供區塊。

例如，對於 Bundler::Plugin::Events::GEM_BEFORE_INSTALL_ALL 勾子，您必須提供一個區塊，其中包含 Bundler::Dependency 物件陣列的引數

Bundler::Plugin.add_hook('before-install-all') do |dependencies|
  # Do something with the dependencies
end

5. 開發來源外掛程式

來源外掛程式讓您可以在 Bundler 中指定更多可能的安裝來源。例如，假設您想從 Amazon S3 安裝寶石。這可以透過建置外掛程式來完成。

建議熟悉 Bundler::Plugin::API::Source 的 API，它可以在 rubydoc.info 或原始程式碼中取得。

來源外掛程式的基本概觀是您必須繼承 Bundler::Plugin::API::Source 並覆寫多種函式。這些函式會在上面連結的說明文件/原始程式碼中指出。

Bundler 使用來源外掛程式 API 為 RubyGems、Git 和基於路徑的寶石提供介面。這些部分的原始程式碼可能有助於了解 API

6. 在本地執行您的外掛程式

若要安裝和在本地執行您的外掛程式，您可以執行 bundler plugin install --git '/PATH/TO/GEM' copycat

7. 部署您的外掛程式

將您的外掛程式部署到 RubyGems，以便其他人可以安裝它。有關部署到 RubyGems 的說明，請參閱本指南。

雖然外掛程式可以從 git 分支安裝，但建議直接從 RubyGems 安裝外掛程式。

範例外掛程式

以下是您可以用作範例和靈感的幾個外掛程式

對於新增命令的外掛程式，請查看 rubygems/bundler-graph
對於使用勾子的外掛程式，請查看 jules2689/extended_bundler-errors
對於來源外掛程式的範例，請查看 Bundler 的實作，包括 RubyGems 來源、git 來源和路徑來源

您也可以查看 bundler 外掛程式的完整清單。