指南

在命令列中使用多重驗證

Specification 類別包含寶石的資訊。通常定義在 .gemspec 檔案或 Rakefile 中，如下所示

Gem::Specification.new do |s|
  s.name        = 'example'
  s.version     = '0.1.0'
  s.licenses    = ['MIT']
  s.summary     = "This is an example!"
  s.description = "Much longer explanation of the example!"
  s.authors     = ["Ruby Coder"]
  s.email       = 'rubycoder@example.com'
  s.files       = ["lib/example.rb"]
  s.homepage    = 'https://rubygems.org/gems/example'
  s.metadata    = { "source_code_uri" => "https://github.com/example/example" }
end

從 RubyGems 2.0 開始，Specification 可以保存任意元資料。請參閱 metadata，了解您可能新增至規格中的元資料項目格式和大小的限制。

必要的 gemspec 屬性

authors=
files
name
summary
version

建議的 gemspec 屬性

description
email
homepage
license=
licenses=
metadata
required_ruby_version

唯讀屬性

extensions_dir
rubygems_version

可選的 gemspec 屬性

add_development_dependency
add_runtime_dependency
author=
bindir
cert_chain
executables
extensions
extra_rdoc_files
platform=
post_install_message
rdoc_options
require_paths=
required_ruby_version=
required_rubygems_version
required_rubygems_version=
requirements
signing_key

必要的 gemspec 屬性

authors=(`值`)

此寶石的作者清單。

或者，可透過將字串指定給 spec.author 來指定單一作者。

用法

spec.authors = ['John Jones', 'Mary Smith']

files

此寶石中包含的檔案。您無法附加到此存取器，您必須指定給它。

僅將您可以需要的檔案新增到此清單，而非目錄等。

在建立寶石時，目錄會自動從此清單中移除，其他非檔案會造成錯誤。

用法

require 'rake'
spec.files = FileList['lib/**/*.rb',
                      'bin/*',
                      '[A-Z]*'].to_a

# or without Rake...
spec.files = Dir['lib/**/*.rb'] + Dir['bin/*']
spec.files += Dir['[A-Z]*']
spec.files.reject! { |fn| fn.include? "CVS" }

name

此寶石的名稱。

用法

spec.name = 'rake'

summary

此寶石說明的簡短摘要。顯示於 gem list -d 中。

說明 應比摘要更詳細。

用法

spec.summary = "This is a small summary of my gem"

version

此寶石的版本。

版本字串可以包含數字和句點，例如 1.0.0。如果版本中包含字母，例如 1.0.0.pre，則寶石為「預發行」寶石。

用法

spec.version = '0.4.1'

建議的 gemspec 屬性

description

此寶石的詳細說明

說明應比摘要更詳細，但不要過長。建議長度為幾段文字，且不含範例或格式化。

用法

spec.description = <<~EOF
  Rake is a Make-like program implemented in Ruby. Tasks and
  dependencies are specified in standard Ruby syntax.
EOF

email

此寶石的聯絡電子郵件地址（或地址）

用法

spec.email = 'john.jones@example.com'
spec.email = ['jack@example.com', 'jill@example.com']

homepage

此寶石首頁的網址

用法

spec.homepage = 'https://github.com/ruby/rake'

license=(`o`)

此寶石的授權。

授權不得超過 64 個字元。

這應僅為您的授權名稱。在建立寶石時，授權的完整文字應位於寶石中（頂層）。

最簡單的方法是指定授權的標準 SPDX ID spdx.org/licenses/。理想情況下，您應選擇一個 OSI（開放原始碼倡議組織）opensource.org/licenses/ 核准的授權。

最常用的 OSI 核准授權為 MIT 和 Apache-2.0。GitHub 也在 choosealicense.com/ 提供授權選擇器。

您也可以將自訂授權檔案與您的 gemspec 搭配使用，並指定 LicenseRef-<idstring>，其中 idstring 是包含授權文字的檔案名稱。

您可以使用 licenses= 設定多個授權

用法

spec.license = 'MIT'

licenses=(`授權`)

該函式庫的授權。

每個授權都必須是簡短的名稱，不超過 64 個字元。

這應僅為您的授權名稱。授權的全文應在您建置它時包含在寶石中。

請參閱 license= 以進行更多討論

用法

spec.licenses = ['MIT', 'GPL-2.0']

metadata

元資料保存此寶石的其他資料，這些資料可能對其他使用者有用，並且可由寶石作者設定。

元資料項目有以下限制

元資料必須是雜湊物件
所有金鑰和值都必須是字串
金鑰最多可為 128 位元組，而值最多可為 1024 位元組
所有字串都必須為 UTF-8，不允許二進位資料

您可以使用元資料來指定連結到您的寶石首頁、程式碼庫、文件、wiki、郵件清單、問題追蹤器和變更日誌。

s.metadata = {
  "bug_tracker_uri"   => "https://example.com/user/bestgemever/issues",
  "changelog_uri"     => "https://example.com/user/bestgemever/CHANGELOG.md",
  "documentation_uri" => "https://www.example.info/gems/bestgemever/0.0.1",
  "homepage_uri"      => "https://bestgemever.example.io",
  "mailing_list_uri"  => "https://groups.example.com/bestgemever",
  "source_code_uri"   => "https://example.com/user/bestgemever",
  "wiki_uri"          => "https://example.com/user/bestgemever/wiki"
  "funding_uri"       => "https://example.com/donate"
}

這些連結將用於您在 rubygems.org 上的寶石頁面，並且必須通過下列正規表示式的驗證。

%r{\Ahttps?:\/\/([^\s:@]+:[^\s:@]*@)?[A-Za-z\d\-]+(\.[A-Za-z\d\-]+)+\.?(:\d{1,5})?([\/?]\S*)?\z}

required_ruby_version

此寶石所需的 Ruby 版本

用法

spec.required_ruby_version = '>= 2.7.0'

唯讀屬性

extensions_dir

此寶石安裝其擴充功能的路徑。

rubygems_version

用於建立此寶石的 RubyGems 版本。

可選的 gemspec 屬性

add_development_dependency(`寶石`, `*需求`)

將名為 寶石 的開發依賴項新增到此寶石，並附有 需求。

用法

spec.add_development_dependency 'example', '~> 1.1', '>= 1.1.4'

開發依賴項並未預設安裝，且在需要寶石時不會啟用。

add_runtime_dependency(`寶石`, `*需求`)

將名為 寶石 的執行時間依賴項新增到此寶石，並附有 需求。

用法

spec.add_runtime_dependency 'example', '~> 1.1', '>= 1.1.4'

author=(`o`)

authors 的單數（替代）寫入器

用法

spec.author = 'John Jones'

bindir

寶石中可執行腳本的路徑。通常為「exe」

用法

spec.bindir = 'exe'

cert_chain

用於簽署此寶石的憑證鏈。有關詳細資訊，請參閱 Gem::Security。

executables

包含在寶石中的可執行檔。

例如，rake 寶石具有 rake 作為可執行檔。您不必指定完整路徑（如 bin/rake）；預期所有應用程式樣式檔案都可以在 bindir 中找到。這些檔案必須是可以執行的 Ruby 檔案。使用 bash 或其他解釋器的檔案將無法使用。

包含的可執行檔只能是 ruby 腳本，不能是其他語言或編譯二進位檔的腳本。

用法

spec.executables << 'rake'

extensions

安裝寶石時要建置的擴充功能，特別是 extconf.rb 樣式檔案的路徑，用於編譯擴充功能。

這些檔案會在 gem 安裝時執行，讓 C (或其他) 程式碼編譯在使用者的機器上。

用法

spec.extensions << 'ext/rmagic/extconf.rb'

請參閱 Gem::Ext::Builder，以取得關於撰寫 gem 擴充套件的資訊。

extra_rdoc_files

要新增到 RDoc 的額外檔案，例如 README 或 doc/examples.txt

當使用者選擇產生 gem 的 RDoc 文件時（通常在安裝時），所有程式庫檔案會傳送至 RDoc 以進行處理。此選項允許您包含一些非程式碼檔案，以提供更完整的文件集。

用法

spec.extra_rdoc_files = ['README', 'doc/user-guide.txt']

platform=(`platform`)

此 gem 執行的平台。

這通常是 Gem::Platform::RUBY 或 Gem::Platform::CURRENT。

大多數 gem 都包含純 Ruby 程式碼；它們應該只保留預設值。有些 gem 包含要編譯成 Ruby「擴充套件」的 C (或其他) 程式碼。除非程式碼只能在特定類型的系統上編譯，否則 gem 應保留預設值。有些 gem 包含預先編譯的程式碼（「二進位 gem」）。由其適當地設定平台屬性特別重要。一個捷徑是將平台設定為 Gem::Platform::CURRENT，這將導致 gem 建構器將平台設定為執行建構的系統的適當值。

如果此屬性設定為非預設值，它會包含在建置 gem 時的檔案名稱中，例如：nokogiri-1.6.0-x86-mingw32.gem

用法

spec.platform = Gem::Platform.local

post_install_message

gem 安裝後顯示的訊息。

用法

spec.post_install_message = "Thanks for installing!"

rdoc_options

指定產生 API 文件時要使用的 rdoc 選項。

用法

spec.rdoc_options << '--title' << 'Rake -- Ruby Make' <<
  '--main' << 'README' <<
  '--line-numbers'

require_paths=(`val`)

當此 gem 被啟用時，要新增到 $LOAD_PATH 的 gem 中路徑。如果您有擴充套件，則不需要在 require 路徑中新增 "ext"，擴充套件建置程序會將擴充套件檔案複製到「lib」中給您。

預設值是 "lib"

用法

# If all library files are in the root directory...
spec.require_paths = ['.']

required_ruby_version=(`req`)

此 gem 所需的 Ruby 版本。ruby 版本可以指定到 patch 等級

$ ruby -v -e 'p Gem.ruby_version'
ruby 2.0.0p247 (2013-06-27 revision 41674) [x86_64-darwin12.4.0]
#<Gem::Version "2.0.0.247">

也可以指定預發行版本。

用法

# This gem will work with 1.8.6 or greater...
spec.required_ruby_version = '>= 1.8.6'

# Only with final releases of major version 2 where minor version is at least 3
spec.required_ruby_version = '~> 2.3'

# Only prereleases or final releases after 2.6.0.preview2
spec.required_ruby_version = '> 2.6.0.preview2'

# This gem will work with 2.3.0 or greater, including major version 3, but lesser than 4.0.0
spec.required_ruby_version = '>= 2.3', '< 4'

required_rubygems_version

此 gem 所需的 RubyGems 版本

required_rubygems_version=(`req`)

此 gem 所需的 RubyGems 版本

requirements

列出此 gem 正常運作所必須符合的外部（對 RubyGems 而言）需求。這只是提供給使用者的資訊。

用法

spec.requirements << 'libmagick, v6.0'
spec.requirements << 'A good graphics card'

signing_key

用於簽署此 gem 的金鑰。詳情請參閱 Gem::Security。

上一個下一個

必要的 gemspec 屬性

建議的 gemspec 屬性

唯讀屬性

可選的 gemspec 屬性

必要的 gemspec 屬性

authors=(值)

files

name

summary

version

建議的 gemspec 屬性

description

email

homepage

license=(o)

licenses=(授權)

metadata

required_ruby_version

唯讀屬性

extensions_dir

rubygems_version

可選的 gemspec 屬性

add_development_dependency(寶石, *需求)

add_runtime_dependency(寶石, *需求)

author=(o)

bindir

cert_chain

executables

extensions

extra_rdoc_files

platform=(platform)

post_install_message

rdoc_options

require_paths=(val)

required_ruby_version=(req)

required_rubygems_version

required_rubygems_version=(req)

requirements

signing_key

authors=(`值`)

license=(`o`)

licenses=(`授權`)

add_development_dependency(`寶石`, `*需求`)

add_runtime_dependency(`寶石`, `*需求`)

author=(`o`)

platform=(`platform`)

require_paths=(`val`)

required_ruby_version=(`req`)

required_rubygems_version=(`req`)