`

rubygems.org guides 翻译三(第一个gem)

    博客分类:
  • gem
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       = 'nick@quaran.to'
  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教程,你已经入门了。

 

 

分享到:
评论

相关推荐

    gemstash, 一个 RubyGems.org 缓存和 private gem 服务器.zip

    gemstash, 一个 RubyGems.org 缓存和 private gem 服务器 什么是 Gemstash?Gemstash是远程服务器( 如 https://rubygems.org ) 和 private gem 源的缓存。在你的控制范围内,如果你使用的是多个可以访问服务器的...

    rubygems-update-3.1.3.gem

    A package (also known as a library) contains a set of functionality that can be invoked by a Ruby program, such as reading and parsing an XML ... See our guide on publishing a Gem at guides.rubygems.org

    rubygems.org:Ruby社区的gem托管服务

    RubyGems.org(néeGemcutter) Ruby社区的gem主机。 目的 提供更好的API处理宝石 创建更透明,更易于访问的项目页面 使社区能够改善和增强网站 支持 由管理, 是一个社区资助的组织,通过门票和赞助为和的会议...

    adoption.rubygems.org

    创建一个新的Web UI,以使用带有框架导轨的gem 使用包含供选择的gem和搜索器的列表制作主页视图 开发功能并提出提出采用的观点 开发功能,并为采用gem做好准备 开发身份验证视图 与rubygems.org A

    Ruby Toolbox data on Rubygems.org-crx插件

    例如,如果您正在https://rubygems.org/gems/simplecov上查看诸如simplecov之类的gem,它将从Ruby Toolbox中获取信息,它是“一个仍在接受更新的长期项目”。 其他gem将基于Ruby Toolbox收集的指标显示其他信息。

    meg:帮助管理和支持 RubyGems.org 的快速命令

    帮助管理和支持 RubyGems.org 的快速命令。 目前帮助通过 SSH 连接到 RubyGems.org 基础设施和运行命令。 安装 $ cd $ git clone git://github.com/rubygems/meg.git .meg 对于 bash 用户: $ echo 'eval "$($...

    rubygems.org-backup:这是历史重写之前 ruby​​gems.org 的 BACKUP 存储库。 不使用。 请不要拉请求

    RubyGems.org(姓氏 Gemcutter) Ruby 社区的 Gem 托管。目的提供更好的 API 来处理 gems 创建更透明和可访问的项目页面使社区能够改进和增强站点链接 :#rubygems 在 Freenode 上: : :贡献请遵循我们的。 要进行...

    rubygems-master-(1).zip_GEM

    Download from: rubygems.org/pages/download Unpack into a directory and cd there Install with: ruby setup.rb # you may need admin/root privilege For more details and other options, see: ruby setup....

    rubygems-update-1.3.1.gem

    rubygems-update-1.3.1.gem

    rubygems-update-1.3.7.gem

    rubygems-update-1.3.7.gem

    2.4-3.0.rubygems.rar

    gem包管理

    ruby-2.2.4.tar.gz、rubygems-2.6.2.zip、redis-3.2.2.gem

    所有资源 下载路径,包含6个redis-config配置文件和 ruby-2.2.4.tar.gz、rubygems-2.6.2.zip、redis-3.2.2.gem 几个资源

    rubygems-incident-verifiers

    Rubygems.org S3 存储桶中的 .gem 文件验证本地 .gem 文件来帮助我们。 此过程是可选的,但它有助于我们重建对 Rubygems.org 的信任,因此我们感谢您做出的任何贡献。 在开始之前,请注意有两种方法可以完成此操作

    redis-3.0.5.gem

    https://rubygems.org/downloads/redis-3.0.5.gem

    gemstash:RubyGems.org缓存和私有gem服务器

    如果您经常在多个项目中捆绑同一组宝石,则可能要使用Gemstash。 您是否仅使用宝石,并且不经常捆绑相同的宝石? 好吧,也许您不需要Gemstash了。 Gemstash由维护,是一项基层计划,致力于支持您所依赖的关键Ruby...

    rubygems-2.4.2 redis-3.2.1.gem

    安装redis 集群所需要的rubygems-2.4.2 redis-3.2.1.gem

    曲柄的Rubygems「Crank for Rubygems」-crx插件

    ★导航至ruby gem的GitHub或Rubygems.org页面。 在GitHub上打开'Gemfile'或'.gemspec'文件,然后单击任何gem名称。 您将被重定向到gem项目页面。 ★从上下文菜单中打开RubyGems.org中的ruby gem页面。 用鼠标突出...

    ruby+watir安装包,安装步骤

    3.本地安装rubygems-update-1.3.4.gem,执行 gem install rubygems-update-1.3.4.gem 4.更新rubygems,执行update_rubygems (这一步先忽略,有影响再说) 5.本地安装 mime-types-1.15.gem,执行 gem install mime-...

Global site tag (gtag.js) - Google Analytics