目录
1.命名一致性
2.版本语义化
3.声明依赖
4.加载代码
5.preRelease gem
一、命名一致性
There are only two hard things in Computer Science: cache invalidation and naming things. -Phil Karlton
1.文件名
保持lib和bin目录下文件命名的一致性。
hola gem的命名如下:
% tree
.
├── Rakefile
├── bin
│ └── hola
├── hola.gemspec
├── lib
│ ├── hola
│ │ └── translator.rb
│ └── hola.rb
└── test
└── test_hola.rb
可执行文件和lib下的主文件命令相同。开发者可以轻易的使用require 'hola'来加载。
2.命名你的gem
命名自己的gem非常重要。在你命名你的gem之前,到on RubyGems.org and GitHub 搜索下,看看别人是否已经使用了这个名字。每一个发布的gem都必须使用一个唯一的名字。当你想好自己gem的名字时,请阅读 naming recommendations 。
二、版本语义化
版本控制策略只是一个版本如何被分配的简单规则。它非常简单(例如从1自增),或者非常特别(Knuth’s TeX 项目的 version numbers: 3, 3.1, 3.14, 3.141, 3.1415; each successive version added another digit to PI)
RubyGems团队使用语义化版本号来给gem规定版本。RubyGems并未严格强调命名策略,但是使用不合理的命名策略是在给其他使用你gem的人帮倒忙。
假设你有一个stack的gem,Stack class里面包含push和pop两个方法。如果你使用语义化版本控制,那么你的CHANGELOG需要像这样:
Version 0.0.1: The initial Stack class is released.
Version 0.0.2: Switched to a linked list implementation because it is cooler.
Version 0.1.0: Added a depth method.
Version 1.0.0: Added top and made pop return nil (pop used to return the old top item).
Version 1.1.0: push now returns the value pushed (it used it return nil).
Version 1.1.1: Fixed a bug in the linked list implementation.
Version 1.1.2: Fixed a bug introduced in the last fix.
语义化版本控制归结如下:
PATCH 0.0.x level changes for implementation level detail changes, such as small bug fixes
MINOR 0.x.0 level changes for any backwards compatible API changes, such as new functionality/features
MAJOR x.0.0 level changes for backwards incompatible API changes, such as changes that will break existing users code if they update
三、声明依赖
gem可以喝其他gem一起协同工作。下面是一些tips以确保他们之前正常工作。
1.运行时 vs 开发
rubygems提供两种类型的依赖:运行时和开发。运行时依赖是你的gem工作时所需要的(例如such as rails needing activesupport)
开发时依赖对于别人想修改你的gem时非常有用。当你指定开发时依赖,其他开发者可以使用install --dev your_gem命令,rubygems会同时抓取两种依赖。典型的开发时依赖就是测试框架和构建系统。
在gemspec中设置依赖非常简单。只需要使用add_runtime_dependency
and add_development_dependency
Gem::Specification.new do |s|
s.name = "hola"
s.version = "2.0.0"
s.add_runtime_dependency "daemons",
["= 1.1.0"]
s.add_development_dependency "bourne",
[">= 0"]
2.不要在你得gem中使用gem
你也许有像下面一样的这些代码,确保你指定了gem的版本。
gem "extlib", ">= 1.0.8"
require "extlib"
对于应用来说,这样做有理由说是在consume gems(虽然他们也可能使用其他工具,例如 Bundler).gems本身不会这样做。他们会在gemspec中使用依赖,这样rubygems可以加载它,而不是用户自己去加载。
It’s reasonable for applications that consume gems to use this (though they could also use a tool like Bundler). Gems themselves should not do this. They should instead use dependencies in the gemspec so RubyGems can handle loading the dependency instead of the user.
3.封闭式的版本约束
如果你的gem版本计划遵循语义化版本2.0.0(http://semver.org/lang/zh-CN/),那么其他ruby开发者将会大受裨益,当他们在自己的应用中使用版本约束锁定gem的时候。
看看下面这样的gem版本releases
-
Version 2.1.0 — Baseline
-
Version 2.2.0 — Introduced some new (backward compatible) features.
-
Version 2.2.1 — Removed some bugs
-
Version 2.2.2 — Streamlined your code
-
Version 2.3.0 — More new features (but still backwards compatible).
-
Version 3.0.0 — Reworked the interface. Code written to version 2.x might not work.
某个其他使用你gem的人发现2.2.0在他的应用中工作良好,但是2.1.0不工作。那么他的gem配置,或者Gemfile(使用bundler)配置如下
# gemspec
spec.add_runtime_dependency 'library',
'>= 2.2.0'
# bundler
gem 'library', '>= 2.2.0'
这是一个好的版本约束。他表示所有2.X版本的在我的应用中工作良好,但是3.X的不确定。
The alternative here is to be “pessimistic”. This explicitly(明白地)excludes(排除) the version that might break your code.
# gemspec
spec.add_runtime_dependency 'library',
['>= 2.2.0', '< 3.0']
# bundler
gem 'library', '>= 2.2.0', '< 3.0'
RubyGems 提供了一种简单的方式,叫做
twiddle-wakka:
# gemspec
spec.add_runtime_dependency 'library',
'~> 2.2'
# bundler
gem 'library', '~> 2.2'
注意:他会抛弃补丁级别的版本号。
这里的~>2.2.0是指在[">=2.2.0", "<2.3.0"]这个区间。
If you want to allow use of newer backwards-compatible(向下兼容) 版本 but need a specific bug fix you can use a compound requirement:
# gemspec
spec.add_runtime_dependency 'library', '~> 2.2', '>= 2.2.1'
# bundler
gem 'library', '~> 2.2', '>= 2.2.1'
The important note to take home here is to be aware others will be using your gems, so guard yourself from potential bugs/failures in future releases by using ~>
instead of >=
if at all possible.
小提示:如果你不得不在你的应用中处理大量的gem依赖,那么我建议你看看bundler和isolate这样的工具,他会帮助你管理复杂的gem依赖问题。
If you want to allow prereleases and regular releases use a compound requirement:
# gemspec
spec.add_runtime_dependency 'library', '>= 2.0.0.a', '< 3'
在prerelease版本中使用~>限制你只能使用的prerelease版本。
4.require rubygems
摘要:不要。
这一行。。。。。。
require 'rubygems'
没必要出现在你的gem代码中,当一个gem required的时候,RubyGems 已经被加载了。
require 'rubygems'意味着这个gem使用简单,没必要运行RubyGems 客户端。
关于这个主题,如果你想了解更多,请查看 Ryan Tomayko
四、加载代码
从其核心,RubyGems的存在时帮助你管理ruby的$LOAD_PATH,他关系到require语句怎样加载你的代码。有几个方法可以使你确定你正确的加载了代码。
1.respect the global load path
当打包你的gem的时候,你需要特别注意你的lib目录里面是些什么。你安装的每一个gem都会把lib目录添加到你的$LOAD_PATH中去。这意味着lib目录中的顶层文件将会被加载。
例如,我们的foo这个gem有如下的目录结构:
.
└── lib
├── foo
│ └── cgi.rb
├── erb.rb
├── foo.rb
└── set.rb
这看上去你把自定义的erb和set文件放在这里是无害的。但这确实是有害的,每一个加载这个gem的用户就不能从ruby的标准库中加载erb和set了。避免这个的最好办法是在lib目录下使用其他目录。通常的做法是把他们放在和你的gem name同名的目录下。例如lib/foo/cgi.rb.
2.requiring files relative each other
Gems不应该使用__FILE__来加载其他文件到你的gem中。如下代码出人意料的普遍:
require File.join(
File.dirname(__FILE__),
"foo", "bar")
# or
require File.expand_path(File.join(
File.dirname(__FILE__),
"foo", "bar"))
The fix is simple,, just require the file relative to the load path:
require 'foo/bar'
#or 使用require_relative
require_relative 'foo/bar'
The make your own gem guide has a great example of this behavior in practice, including a working test suite. The code for that gem is on GitHub as well.
3.mangling the load path
gems不应该改变$_LOAD_PATH常量。RubyGems 帮你管理这些。如下代码是必须的:
lp = File.expand_path(File.dirname(__FILE__))
unless $LOAD_PATH.include?(lp)
$LOAD_PATH.unshift(lp)
end
# or
__DIR__ = File.dirname(__FILE__)
$LOAD_PATH.unshift __DIR__ unless
$LOAD_PATH.include?(__DIR__) ||
$LOAD_PATH.include?(File.expand_path(__DIR__))
当RubyGems激活一个gem,退添加lib目录到你的 $LOAD_PATH
以准备好被其他lib或者应用加载。 It is safe to assume you can then require
any file in your lib
folder.
五、preRelease gem
当一个大的gem更新前,许多gem开发者会放出testing或者edge版本。RubyGems 支持prerelease的观点,prerelease可以使betas, alphas或者其他。
他的优点很明显。在你的gem版本中只需要多一个或者几个字母。例如,下面是一个prerelease gemspec的字段:
Gem::Specification.new do |s|
s.name = "hola"
s.version = "1.0.0.pre"
其他prerelease版本可能包含 2.0.0.rc1
, 或者 1.5.0.beta.3
. 只需要包含几个字母,你就做大了。这样的gem可以使用--pre,就想这样:
% gem list factory_girl -r --pre
*** REMOTE GEMS ***
factory_girl (2.0.0.beta2, 2.0.0.beta1)
factory_girl_rails (1.1.beta1)
% gem install factory_girl --pre
Successfully installed factory_girl-2.0.0.beta2
1 gem installed
六.扩展阅读
Several sources were used for content for this guide:
分享到:
相关推荐
gemstash, 一个 RubyGems.org 缓存和 private gem 服务器 什么是 Gemstash?Gemstash是远程服务器( 如 https://rubygems.org ) 和 private 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 Toolbox数据 此Chrome扩展程序从Ruby工具箱(https://www.ruby-toolbox.com/)中提取信息,以显示在rubygems.org上。 例如,如果您正在https://rubygems.org/gems/simplecov上查看诸如...
帮助管理和支持 RubyGems.org 的快速命令。 目前帮助通过 SSH 连接到 RubyGems.org 基础设施和运行命令。 安装 $ cd $ git clone git://github.com/rubygems/meg.git .meg 对于 bash 用户: $ echo 'eval "$($...
option.rubygems.org 项目导师的姓名: Nick Quaranto,Benjamin Fleischer 项目团队的名称:丽娜·托雷斯(Lina Torres)的安吉拉(Angela Guette) 项目名称: RubyGems.org采用中心 网址: : 关于该项目: ...
RubyGems.org(姓氏 Gemcutter) Ruby 社区的 Gem 托管。目的提供更好的 API 来处理 gems 创建更透明和可访问的项目页面使社区能够改进和增强站点链接 :#rubygems 在 Freenode 上: : :贡献请遵循我们的。 要进行...
RubyGems.org(néeGemcutter) Ruby社区的gem主机。 目的 提供更好的API处理宝石 创建更透明,更易于访问的项目页面 使社区能够改善和增强网站 支持 由管理, 是一个社区资助的组织,通过门票和赞助为和的会议...
标题“2.4-3.0.rubygems.rar”暗示了这个压缩包可能包含了Ruby Gems从版本2.4到3.0之间的升级或集合,这对于Ruby开发者来说是一个重要的资源,因为版本升级通常会带来性能优化、新功能以及对旧问题的修复。...
RubyGems是Ruby编程语言的一个核心组成部分,它提供了一个管理和分发Ruby库和程序的框架。这个名为"rubygems-3.2.27.zip"的压缩包包含了RubyGems的3.2.27版本,这是一个重要的更新,旨在提高稳定性和性能,同时也...
##概括此处提供的工具使您能够将 gem 的本地副本与 Rubygems.org 上的副本进行检查。 这些工具旨在让 gem 开发人员根据 Rubygems.org 服务器检查他们的本地开发副本(为什么?请参阅文档末尾的注释)。 目前正在...
★导航至ruby gem的GitHub或Rubygems.org页面。 在GitHub上打开'Gemfile'或'.gemspec'文件,然后单击任何gem名称。 您将被重定向到gem项目页面。 ★从上下文菜单中打开RubyGems.org中的ruby 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是Ruby编程语言的一个核心组成部分,它提供了一个管理和分发Ruby库和程序的框架。这个特定的压缩包“rubygems-1.8.7.gz”是RubyGems的一个旧版本,适用于Linux操作系统。在深入理解这个压缩包之前,我们先来...
RubyGems
今天或什至更好的做出贡献,并确保Bundler,RubyGems,Gemstash和其他共享工具在未来数年内都存在。 快速入门指南 设置 Gemstash旨在快速,轻松地进行设置。 到本《快速入门指南》结束时,您将能够将公共资源中的...
从rubygems.org/pages/docs移植内容 从help.rubygems.org知识库移植内容 在这里找到许多StackOverflow / ruby-talk问题并获得其常见答案 填写更多指南! 设置 确保已gem install jekyll ( gem install jekyll ...
1. **安装**:使用`gem install <gem_name>`命令,RubyGems会从官方的Gem仓库(rubygems.org)下载指定gem的最新版本,并将其安装到本地系统。同时,RubyGems还会处理gem的依赖关系,确保所有必需的依赖项都被正确...
RubyGems是Ruby编程语言的一个核心组件,它提供了一个便捷的包管理机制,使得开发者能够轻松地安装、管理和使用各种库和工具。在本案例中,“rubygems-2.7.4.tgz”是一个压缩包,包含了RubyGems的特定版本——2.7.4...