rubygems.org guides 翻译三（第一个gem）

目录：

1.简介

2.你的第一个gem

3.载入跟多的文件

4.加入可执行文件（二进制文件）

5.测试，测试，测试

6.文档化你的code

7.总结

 

一、简介

由于有了rubygem这个工具，创建和发布自己的gem非常简单。下面介绍怎样制作一个hello world的gem，该gem的地址是https://github.com/qrush/hola

二、你的第一个gem

hola这个gem只有一个ruby文件盒一个hola.gemspec文件。如果你要发布，你必须起一个特别一点的名字，例如hola_flowerwrong。gem的命名规范请查看http://guides.rubygems.org/patterns/#consistent-naming ├── hola.gemspec └── lib └── hola.rb

你的gem的核心代码必须放在lib目录下。约定（convention）是只有一个和该gem名字相同的ruby文件。因为当require 'hola'运行时，他就会被加载。该文件负责设置你的代码和api。

该实例的hola.rb代码非常简单。

 

class Hola
  def self.hi
    puts "Hello world!"
  end
end

 

 

gemspec文件定义了该gem的功能，谁创造了该gem，版本信息等等。他也是http://rubygems.org/的接口。

Gem::Specification.new do |s|
  s.name        = 'hola'
  s.version     = '0.0.0'
  s.date        = '2010-04-28'
  s.summary     = "Hola!"
  s.description = "A simple hello world gem"
  s.authors     = ["Nick Quaranto"]
  s.email       = '[e-mail]'
  s.files       = ["lib/hola.rb"]
  s.homepage    =
    'http://rubygems.org/gems/hola'
  s.license       = 'MIT'
end

 

该gem的描述或许会很长，如果它匹配 /^== [A-Z]/ ，它就会在http://rubygems.org/上以rdoc解析来显示。注意：其他的不会被rdoc解析。

看起来很熟悉，对吗？它也是ruby文件，所以你可以用脚本（wrap scripts）来自动生成name和version等成员。它可以包含许多成员信息。想了解更多，从http://guides.rubygems.org/specification-reference查看。

创建gemspec后，你就可以用他来构建你的gem了。然后你就可以本地安装以便测试。

% gem build hola.gemspec
Successfully built RubyGem
Name: hola
Version: 0.0.0
File: hola-0.0.0.gem

% gem install ./hola-0.0.0.gem
Successfully installed hola-0.0.0
1 gem installed

 

当然，冒烟测试（smoke test）还没完，最后一步是require这个gem并使用它。

% irb
>> require 'hola'
=> true
>> Hola.hi
Hello world!

如果你使用1.9.2之前版本的ruby，那么你需要使用irb -rubygems命令先加载rubygem。

现在你可以分享你的gem到ruby社区了。发布gem到RubyGems.org只需要一个命令，当然你得先有一个RubyGems.org的账户。设置你得RubyGems.org账户在你得计算机上：

$ curl -u qrush https://rubygems.org/api/v1/api_key.yaml >
~/.gem/credentials; chmod 0600 ~/.gem/credentials

Enter host password for user 'qrush':

如果curl, OpenSSL, or certificates有问题，你也可以复制地址到浏览器，然后浏览器也会要求你登陆。登陆后会下载api_key.yaml文件，保存到 ~/.gem 并取名叫做 ‘credentials’ 。

设置完毕之后，你就可以发布你的gem了。

% gem push hola-0.0.0.gem
Pushing gem to RubyGems.org...
Successfully registered gem: hola (0.0.0)

半杯咖啡后（通常用不到一分钟），任何人（地球）都可以安装使用你的gem了。你可以在https://rubygems.org/gems/hola看到他，也可以抓取。

% gem list -r hola

*** REMOTE GEMS ***

hola (0.0.0)

% gem install hola
Successfully installed hola-0.0.0
1 gem installed

分享你得代码到rubygems.org就是这么简单。

 

三、载入跟多的文件

通常来说，一个文件的规模通常是不够的。那我们就来加入跟多的文件吧。

% cat lib/hola.rb
class Hola
  def self.hi(language = "english")
    translator = Translator.new(language)
    translator.hi
  end
end

class Hola::Translator
  def initialize(language)
    @language = language
  end

  def hi
    case @language
    when "spanish"
      "hola mundo"
    else
      "hello world"
    end
  end
end

 

这个文件看上去有些乱（真的？为了配合下文）。那我们把Translator单独拿出来放到文件里面。

如前所述（As mentioned before），gem的root文件负责管理加载其他文件的代码。其他的gem文件通常放在/lib/gemname/下面。就像这样：

% tree
.
├── hola.gemspec
└── lib
    ├── hola
    │   └── translator.rb
    └── hola.rb

Translator类现在在lib/hola下，我们可以使用require来加载它，translator.rb如下：

% cat lib/hola/translator.rb
class Translator
  def initialize(language)
    @language = language
  end

  def hi
    case @language
    when "spanish"
      "hola mundo"
    else
      "hello world"
    end
  end
end

 

下面在hola.rb里面加载它：

% cat lib/hola.rb
class Hola
  def self.hi(language = "english")
    translator = Translator.new(language)
    translator.hi
  end
end

require 'hola/translator'

 

明白了吗（Gotcha）：创建文件或者文件夹后，别忘了在hola.gemspec里面注册。如果不注册，将无法使用。

% cat hola.gemspec
Gem::Specification.new do |s|
...
s.files       = ["lib/hola.rb", "lib/hola/translator.rb"]
...
end

让我们在来试试，打开irb

% irb -Ilib -rhola
irb(main):001:0> Hola.hi("english")
=> "hello world"
irb(main):002:0> Hola.hi("spanish")
=> "hola mundo"

这里我们使用了陌生的命令-Ilib，rubygem通常会include lib，所以gem使用者无需担心gem的加载问题。然而，如果你在rubygem外使用这个库，那么你不得不自行配置。

操作$LOAD_PATH来配置是可行的，但他同时也是一种反面模式（anti-pattern），想了解更多好的做法和反面模式，可以查看http://guides.rubygems.org/patterns

如果你新添加了文件，记得在gemspec注册。许多开发者会使用Hoe, Jeweler, Rake, Bundler, 或者 just a dynamic gemspec 自动完成。

添加跟多的目录和代码的过程和上面是一样的。分割你的ruby文件使他有意义。合理组织你的代码会为你以后的维护工作带来很大的便利，不会用头疼药了。

 

四、加入可执行文件

为了扩展你的ruby代码，gem也允许加入可执行文件到你的shell's PATH. 最著名的莫过于rake了。另一个常用的就是prettify_json.rb，包含在http://rubygems.org/gems/json这个gem里面。它格式化json为可读模式（ruby1.9自带）。

例子：

% curl -s http://jsonip.com/ | \
  prettify_json.rb
{
  "ip": "24.60.248.134"
}

添加一个可执行文件到gem非常简单。你只需要把他们放在gem的bin目录下，然后添加到gemspec的可执行数组中即可。我们来添加一个可执行文件到 hola gem里面。先创建文件夹bin，使他可执行。

% mkdir bin
% touch bin/hola
% chmod a+x bin/hola

===================================20140728下午16:30============================

可执行文件需要http://www.catb.org/jargon/html/S/shebang.html来确定用什么程序来执行他。形如：

% cat bin/hola
#!/usr/bin/env ruby

require 'hola'
puts Hola.hi(ARGV[0])

它所做的就是加载这个gem，用第一行的程序去执行。例如：

% ruby -Ilib ./bin/hola
hello world

% ruby -Ilib ./bin/hola spanish
hola mundo

最后，为了在你使用gem是包含这个可执行文件，你需要在gemspec注册他。

 

% head -4 hola.gemspec
Gem::Specification.new do |s|
  s.name        = 'hola'
  s.version     = '0.0.1'
  s.executables << 'hola'

 

上传这个gem，你的命令行工具就发布了。如果你需要，可以同时加多个可执行文件到bin目录，在gemspec中有一个executables 数组。

注意：当你更新后，你需要修改gem的version，有关gem version更多的信息请看http://guides.rubygems.org/patterns/#semantic-versioning

 

五、测试

编写你gem的测试非常重要。他不仅确定了你的代码正常工作，而且告诉了其他人你的代码做了什么工作。评估一个gem，ruby开发者就是通过查看测试代码的可靠度。

gem支持添加测试文件，所以gem下载后可以执行测试代码。一个完整的社区http://test.rubygems.org/正在兴起，帮助完成gem的测试在不同框架和编译器的运行文档。

In short: TEST YOUR GEM! Please!

 

Test::Unit是ruby内建的测试框架。https://github.com/seattlerb/minitest/blob/master/README.txt有许多在线教程。也有其他的测试框架可供使用，RSpec是最后的选择。不管你用什么，just TEST.

我们来为hola添加测试。需要添加一个Rakefile和一个test目录。

% tree
.
├── Rakefile
├── bin
│   └── hola
├── hola.gemspec
├── lib
│   ├── hola
│   │   └── translator.rb
│   └── hola.rb
└── test
    └── test_hola.rb

Rakefile只是给一些自动化测试。

 

% cat Rakefile
require 'rake/testtask'

Rake::TestTask.new do |t|
  t.libs << 'test'
end

desc "Run tests"
task :default => :test

 

现在你可以运行rake test或者rake来执行测试。

来看看hola基本的测试代码：

 

% cat test/test_hola.rb
require 'test/unit'
require 'hola'

class HolaTest < Test::Unit::TestCase
  def test_english_hello
    assert_equal "hello world",
      Hola.hi("english")
  end

  def test_any_hello
    assert_equal "hello world",
      Hola.hi("ruby")
  end

  def test_spanish_hello
    assert_equal "hola mundo",
      Hola.hi("spanish")
  end
end

 

最后，跑测试：

% rake test
(in /Users/qrush/Dev/ruby/hola)
Loaded suite
Started
...
Finished in 0.000736 seconds.

3 tests, 3 assertions, 0 failures, 0 errors, 0 skips

Test run options: --seed 15331

green，太好了，记住，他依赖于你的shell的color配置。

更多信息请查看https://github.com/languages/Ruby

 

六、编写文档

大多是gem默认使用RDoc来生成文档。http://docs.seattlerb.org/rdoc/RDoc/Markup.html有许多教程。例子如下：

 

# The main Hola driver
class Hola
  # Say hi to the world!
  #
  # Example:
  #   >> Hola.hi("spanish")
  #   => hola mundo
  #
  # Arguments:
  #   language: (String)

  def self.hi(language = "english")
    translator = Translator.new(language)
    puts translator.hi
  end
end

 

两一个选择就是YARD(http://yardoc.org/),当你上传一个gem后，http://rubydoc.info/自动为你生成YARDocs文档，YARD与RDoc兼容，http://rubydoc.info/docs/yard/file/docs/GettingStarted.md介绍了怎样使用他们。

 

七、总结

通过这个简单的第一个gem教程，你已经入门了。