如何使用RubyGems将Ruby应用程序打包和分发为Gem
介绍
共享在每个参与的人之间架起了一座桥梁,它使事情发展。 这是开放源代码运动的基础,它让位并让许多伟大的事情发生——尤其是在最近几年。
此原则适用于 Ruby 和基于 Ruby 的应用程序。 这就是为什么 - 以及如何 - 开发人员可以开始着手将他们的想法如此迅速地变为现实,这要归功于他们可以利用的所有可用工具、库和框架。
在这篇 DigitalOcean 文章中,我们旨在帮助那些试图通过分享他们自己的基于 Ruby 或 Ruby 相关的创作来回馈社区的人。 我们将揭示打包代码的奥秘,以便其他人能够使用 RubyGems 包管理器轻松将其作为 Gem 下载,这使得整个过程变得轻而易举。
词汇表
1. 包装应用
2. RubyGems 包管理器和 Ruby Gem 包
- RubyGems 包管理器
- 红宝石包
- Gem 封装结构
3. 获取 Ruby 和必要的工具
- 安装 Ruby
- 安装捆绑器
3. 打包一个 Ruby 应用程序
- 准备分发目录
- 创建 .gemspec 文件
- 放置应用程序代码
- 修改主应用程序脚本
- 确保一切正常
- 列出 Gem 的依赖项
- 提交 Gem 包
4. 发布 Gem 包
- 创建包
- 发布宝石
包装应用
分发应用程序、库或其他与编程相关的代码包的方法之一是将它们放在称为 包 的档案中。 应用程序包以易于跟踪和易于使用的方式包含已编译和即用型软件。 它们通常带有附加文件,其中包含有关软件包的信息,有时还包含文档。
因此,打包应用程序包括遵循由包管理工具定义的一组格式(即 RubyGems)并使用这些工具以易于访问的方式与他人共享。
在本教程中,我们将从了解 RubyGems(Gem 包格式)开始,然后学习如何从头到尾打包 Ruby 应用程序,从创建包含代码(和其他相关材料)的包结构开始。
RubyGems 包管理器和 Ruby Gem 包
注:本文的主题是打包应用程序。 本节包含相关工具和材料的摘要。 要了解有关它们的更多信息,您可以阅读我们的 RubyGems 系列的 介绍性第一部分 。
RubyGems 包管理器
RubyGems 是 Ruby 的默认 包管理器。 它有助于从下载到分发 Ruby 应用程序和相关二进制文件或库的所有应用程序包生命周期。 RubyGems 是一个强大的包管理工具,它为开发人员提供了一个标准化的结构,用于将应用程序打包到档案中,称为 Ruby Gems。
红宝石包
Gem 是一个 Ruby 应用程序包,它可以包含从代码集合到库的任何内容,和/或打包代码实际需要运行的依赖项列表。
Gem 封装结构
Gem 包包含不同的组件集。 每个组件都放置在 gem 包中的专用位置内。
以下所有元素(以及更多)都可以进入 Gems:
- 申请代码;
- 测试;
- 依赖关系描述;
- 二进制文件;
- 相关文件;
- 有关包的信息 (gemspec)。
宝石由类似于以下的结构形成:
/[package_name] # 1 |__ /bin # 2 |__ /lib # 3 |__ /test # 4 |__ README # 5 |__ Rakefile # 6 |__ [name].gemspec # 7
- [package_name]:
Gem 包的主根目录。
- /bin:
可执行二进制文件的位置(如果包有)。
- /lib:
包含主要 Ruby 应用程序代码(inc. 模块)。
- /test:
测试文件的位置。
- Rakefile:
使用 Rake 进行构建的库的 Rake 文件。
- [packagename].gemspec:
- .gemspec 文件,具有主目录的名称,包含所有包元数据,例如 名称、版本、目录等
获取 Ruby 和必要的工具
安装 Ruby
如果您还没有安装 Ruby,您可以按照以下两个链接之一在您选择的平台上正确设置它。
- CentOS / 瑞尔:
如何使用 RVM 在 CentOS 6.5 上安装 Ruby 2.1.0
- Ubuntu / Debian:
如何使用 RVM 在 Ubuntu 13 上安装 Ruby 2.1.0
安装捆绑器
我们将用于创建 Gem 的工具之一是 Bundler。 一旦在你的系统上安装了 Ruby 和 RubyGems,你可以使用 ``gem` 命令来获取 bundler。
运行以下命令以使用 gem
安装 bundler
:
gem install bundler # Successfully installed bundler-1.5.3 # Parsing documentation for bundler-1.5.3 # Done installing documentation for bundler after 3 seconds # 1 gem installed
打包一个 Ruby 应用程序
有几种方法可以开始创建 Gem 包。 一种方法是使用流行的 Bundler,这是一种 Ruby 环境和依赖管理器,可帮助满足应用程序的需求和代码维护。 此工具还可用于搭建 Gem 分发目录以启动打包过程。
准备分发目录
Gem 包保存在包目录中,该目录应该以您的包命名,正如我们在前面的结构化部分中讨论的那样。 由于这些是在文件系统上找到的简单位置,您可以使用 Unix mkdir
命令一个一个地创建它们……或者让 Bundler 来完成这项工作。
运行以下命令在一个文件夹中搭建所有必要的目录,以您的 Gem 所需的名称命名:
# Usage: [sudo] bundle gem [your chosen gem name] # Example: bundle gem my_gem
注意: Gem 名称必须是唯一的。 因此,您应该搜索并确保您想为 Gem 使用的名称尚未被其他人的项目选择。 为了验证,您可以访问并搜索 RubyGems.org。
上面的命令将运行一系列命令来创建我们的包结构,例如:
# bundle gem my_gem # create my_gem/Gemfile # create my_gem/Rakefile # create my_gem/LICENSE.txt # create my_gem/README.md # create my_gem/.gitignore # create my_gem/my_gem.gemspec # create my_gem/lib/my_gem.rb # create my_gem/lib/my_gem/version.rb # Initializing git repo in .../my_gem
正如您将看到的,Bundler 还创建了一个全新的 Git 存储库,可以方便地进行各种版本控制操作。
注意: 如果您想了解更多关于如何使用 Git 的信息,请查看 DigitalOcean 社区文章 关于该主题的文章。
创建 .gemspec 文件
.gemspec
文件包含一些关于 Gem 包的绝对重要信息。 Ever Gem 必须附带一个,其中包含从 Gem 名称到版本和描述到 Gem 包含的文件夹的元数据。
提示: .gemspec
files are regular Ruby scripts – which means that they are programmable.
要查看由 Bundler 创建的通用 gemspec 的内容,请使用以下命令:
cat my_gem/my_gem.gemspec # # coding: utf-8 # lib = File.expand_path('../lib', __FILE__) # $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib) # require 'my_gem/version' # Gem::Specification.new do |spec| # spec.name = "my_gem" # spec.version = MyGem::VERSION # spec.authors = ["Maintainer Name"] # spec.email = ["maintainer@email.address"] # spec.summary = %q{TODO: Write a short summary. Required.}" # spec.description = %q{TODO: Write a longer description. Optional.} # spec.homepage = "" # spec.license = "MIT" # spec.files = `git ls-files -z`.split("\x0") # spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) } # spec.test_files = spec.files.grep(%r{^(test|spec|features)/}) # spec.require_paths = ["lib"] # spec.add_development_dependency "bundler", "~> 1.5" # spec.add_development_dependency "rake" # end # mba:Git
您可以现在编辑此文件,也可以在每次打包和发布之前编辑此文件。
为了修改此文件,您可以使用以下命令使用 nano 对其进行编辑:
nano my_gem/my_gem.gemspec
这将打开纳米文本编辑器。
您可能要在此处声明的推荐附加信息之一是运行代码所需的最低 Ruby 解释器版本。
您可以使用 required_ruby_version
声明来执行此操作,可以将其添加到文件的底部以保持一致性。
例如:
# .. # Declare that the Gem is compatible with # version 2.0 or greater spec.required_ruby_version = ">= 2.0" spec.add_development_dependency "bundler", "~> 1.5" spec.add_development_dependency "rake" end
完成文件编辑后,按 CTRL+X 并按 Y 确认保存并退出。
注意:不要忘记修改包含“to-do”占位符的声明(即 %q{TODO:
),例如 spec.description
。
放置应用程序代码
您的库(或应用程序、框架等)应始终位于 /lib
目录中。 在这个目录中,应该有一个 Ruby 脚本,其名称与您的 Gem 完全相同。 当另一个应用程序依赖于您的 Gem 时,此文件是导入的主要文件。
放置应用程序代码的推荐和最简洁的方法是将其分成几部分并将它们放置在 /lib
内的目录中,它们由 my_gem.rb
使用并提供给公众。
当您查看 /lib
目录的内容时,您会看到主 Ruby 脚本和包含您的代码的目录已准备就绪:
ls -l my_gem/lib # drwxr-xr-x 3 user staff 102 dd Mmm hh:mm my_gem # -rw-r--r-- 1 user staff 70 dd Mmm hh:mm my_gem.rb
而/lib
里面的my_gem
目录自带一个版本文件:
cat my_gem/lib/my_gem/version.rb module MyGem VERSION = "0.0.1" end
这个 VERSION
编号设置为由 Bundler 自动导入并在 *.gemspec
文件中使用。 您可以在此处修改并更改它以匹配您的 Gem 的当前版本。
您应该将所有代码移到此处以供您的应用程序使用。
例如,让我们创建一个 Hello [name]!
模块。
nano my_gem/lib/my_gem/hail.rb
把下面的例子放在里面:
class Hail def self.name(n = "Dalek") n end end
按 CTRL+X 并用 Y 确认保存并退出。
修改主应用程序脚本
在上一步中,我们了解到,为了保持一切井井有条,尤其是具有大量类的应用程序应该被分成几块,所有元素都放在 /lib/[gem-name]
目录中。
让我们看看我们如何修改当有人使用您的 Gem 时导入的主要 Ruby 脚本。
运行以下命令,使用 nano 编辑 /lib
中导入的 Ruby 文件:
# Usage: [sudo] nano my_gem/lib/[gem name].rb nano my_gem/lib/my_gem.rb
您将看到一个非常短的脚本,类似于以下脚本:
require "my_gem/version" module MyGem # Your code goes here... end
在这里,您应该从 /lib/[gem name]
目录导入所有类和代码并使用它们。
在我们的例子中,让我们看看如何使用我们在上一步中创建的 Hail
类。
修改您的代码类似于以下示例:
require "my_gem/version" require "my_gem/hail" module MyGem def self.hi(n = "Default Name") hail = Hail Hail.name(n) end end
按 CTRL+X 并用 Y 确认保存并退出。
注意:虽然没有必要将Hail
做成instantiable类,但为了演示,我们把MyGem作为一个模块来使用它的方法直接。
确保一切正常
将代码移入内部并修改主要导入的脚本后,您自然会希望确保一切正常。 最简单的方法是再次使用 Bundler,而不是安装 Gem。
首先,让我们进入 Gem 目录,然后使用 Bundler 的控制台功能:
cd my_gem bundler console
这将使用 *.gemspec
中的信息加载您的 Gem 并让您开始工作,例如:
bundler console # irb(main):001:0> MyGem.hi("Hello world!") # => "Hello world!"
列出 Gem 的依赖项
在现实世界的场景中,您的 Gem 本身很可能会依赖于其他人。
这些依赖项也列在 *.gemspec
文件中。
运行以下命令以使用 nano 编辑文件:
nano my_gem/my_gem.gemspec
在适当的块中添加以下说明以列出依赖项:
# Usage: spec.add_runtime_dependency "[gem name]", [[version]] spec.add_runtime_dependency "activesupport", [">= 4.0"]
按 CTRL+X 并用 Y 确认保存并退出。
注意:你可以通过对*.gemspec
文件依次重复指令来列出所有必要的依赖关系。
提交 Gem 包
一旦您的 Gem 准备好交付,您应该提交 Git 存储库以进行版本控制。
使用以下命令通过 Git 提交:
git commit -m "Version 0.1.0"
然后,Git 将提交您的所有代码并为您提供结果:
# [master (root-commit) d4640b8] Version 0.1.0 # 8 files changed, 104 insertions(+) # create mode 100644 .gitignore # create mode 100644 Gemfile # create mode 100644 LICENSE.txt # create mode 100644 README.md # create mode 100644 Rakefile # create mode 100644 lib/my_gem.rb # create mode 100644 lib/my_gem/version.rb # create mode 100644 my_gem.gemspec
发布 Gem 包
一旦您对您的 Gem 感到满意,您就可以在 RubyGems.org 上向全世界发布它。
注意: 为了发布您的代码,您需要在 https://rubygems.org/sign_up 拥有一个帐户。
创建包
全部设置好后,您可以使用 gem
工具创建包。
运行以下命令来创建你的包:
# Usage: [sudo] gem build [gem name].gemspec # Example: gem build mygem.gemspec # Successfully built RubyGem # Name: my_gem # Version: 0.1.0 # File: my_gem-0.1.0.gem
发布宝石
有几种方法可以发布新铸造的 Gem。 无论哪种方式,您都需要使用 RubyGems.org 帐户登录,所以让我们首先开始。
运行以下命令使用gem
登录:
gem push
输入您的电子邮件地址,然后输入您的密码以登录。
注意: 我们特别避免提供 Gem 名称来推送,以便我们只登录而不执行进一步操作。
为了简单地推送您的 Gem,请运行以下命令:
# Usage: [sudo] gem push [gem file] # Example: gem push my_gem-0.1.0.gem
或者,您可以从 Bundler 的 Rake 任务中受益。 您可以查看包含以下内容的完整列表:
rake -T
- rake build:
build my_gem-0.0.1.gem 到 pkg 目录
- rake install:
构建并安装 my_gem-0.0.1.gem 到系统 gems
- rake 发布:
创建标签 v0.0.1 并构建并将 my_gem-0.0.1.gem 推送到 Rubygems
如果你调用rake release
,你的包会被推送到你设置的Git账号,然后推送到RubyGems.org,例如:
rake build # my_gem 0.1.0 built to pkg/my_gem-0.1.0.gem. rake release # rake aborted! # Couldn't git push. `git push 2>&1' failed with the following output: # fatal: No configured push destination. # Either specify the URL from the command-line or configure a remote repository using # git remote add <name> <url>
要继续,请添加一个远程 Git 帐户:
# Usage: git remote add origin git@github.com:[user name]/[repository].git # Example: git remote add origin git@github.com:maintainer1/my_gem.git
然后使用 rake
同时发布您的代码:
rake release # .. # Pushed MyGem
就是这样! 您现在可以访问 RubyGems.org 并查看您的 Gem:
http://www.rubygems.org/gems/[your gem name]