我如何建立一个基本的 Ruby 项目？

How do I set up a basic Ruby project?

提问by ayckoster

I want to create a small Ruby project with 10 ~ 20 classes/files. I need some gems and I want to use RSpec as test framework.

我想创建一个包含 10 ~ 20 个类/文件的小型 Rub​​y 项目。我需要一些 gems，我想使用 RSpec 作为测试框架。

I might want to build a gem later on, but that is not certain.

稍后我可能想构建一个 gem，但这并不确定。

Is there some how-to or guide that shows me how to set up the basic structure of my project?

是否有一些操作方法或指南向我展示如何设置项目的基本结构？

Questions that I have are:

我的问题是：

• Where do I put all my custom Errors/Exceptions?
• Are there some conventions out there for naming directories like lib, bin, src etc?
• Where do I put test data or documents?
• Where do I require all my files so I have access to them in my project?

• 我在哪里放置我所有的自定义错误/异常？
• 是否有一些约定用于命名 lib、bin、src 等目录？
• 我在哪里放置测试数据或文件？
• 我在哪里需要我的所有文件，以便我可以在我的项目中访问它们？

I know I could do everything from scratch, but I would like some guidance. There are some good gems out there that I could copy, but I am not certain what I really need and what I can delete.

我知道我可以从头开始做任何事情，但我需要一些指导。有一些不错的宝石可以复制，但我不确定我真正需要什么以及可以删除什么。

I looked at http://gembundler.com/, but it stops after setting up Bundler.

我查看了http://gembundler.com/，但在设置 Bundler 后它停止了。

回答by John Douthat

To get a good start, you can use the bundle gemcommand and rspec --init.

为了有一个好的开始，您可以使用bundle gem命令和rspec --init。

~/code $ bundle gem my_lib
      create  my_lib/Gemfile
      create  my_lib/Rakefile
      create  my_lib/LICENSE.txt
      create  my_lib/README.md
      create  my_lib/.gitignore
      create  my_lib/my_lib.gemspec
      create  my_lib/lib/my_lib.rb
      create  my_lib/lib/my_lib/version.rb
Initializating git repo in /Users/john/code/my_lib
~/code $ cd my_lib/
~/code/my_lib $ git commit -m "Empty project"
~/code/my_lib $ rspec --init
The --configure option no longer needs any arguments, so true was ignored.
  create   spec/spec_helper.rb
  create   .rspec

• code goes in lib
• specs go in spec
• test data or documents go in spec/fixtures/
• Require all your ruby files in lib/my_lib.rb. You can define your exceptions in that file, too, or in their own files -- according to your own preference.
• C source files go in ext/my_lib
• shell scripts and executables go in bin

• 代码进去 lib
• 规格进去 spec
• 测试数据或文件进去 spec/fixtures/
• 需要所有 ruby​​ 文件在lib/my_lib.rb. 您也可以在该文件中或在它们自己的文件中定义您的例外——根据您自己的喜好。
• C源文件进去 ext/my_lib
• shell 脚本和可执行文件进去 bin

When in doubt, just look at how other gems are laid out.

如有疑问，只需看看其他宝石的布局方式。

---

---

Further information:

更多信息：

You should add rspec as a development dependency in your gemspec to make things easier for other developers

您应该在 gemspec 中添加 rspec 作为开发依赖项，以使其他开发人员的工作更轻松

1. Edit my_lib.gemspec, adding gem.add_development_dependency 'rspec'and gem.add_development_dependency 'rake'near the bottom.
2. Add Bundler.setupand require 'my_lib'to the top of spec/spec_helper.rb to ensure your gem dependencies are loaded when you run your specs.
3. Add require "rspec/core/rake_task"and task :default => :specto your Rakefile, so that running rakewill run your specs.

1. 编辑 my_lib.gemspec，添加gem.add_development_dependency 'rspec'并gem.add_development_dependency 'rake'靠近底部。
2. 将Bundler.setup和添加require 'my_lib'到 spec/spec_helper.rb 的顶部，以确保在运行规范时加载 gem 依赖项。
3. 将require "rspec/core/rake_task"和添加task :default => :spec到您的 Rakefile，以便运行rake将运行您的规范。

While you're working on your newest creation, guard-rspeccan save you time and hassle by automaticallyrunning your specs as files change, alerting you to spec failures.

当您在进行最新的创作时，guard-rspec可以通过在文件更改时自动运行您的规范，提醒您规范失败来节省您的时间和麻烦。

~/code/my_lib $ git add spec/spec_helper.rb
~/code/my_lib $ git commit -am "Add RSpec"
~/code/my_lib $ vim my_lib.gemspec # add guard development dependency
~/code/my_lib $ bundle
~/code/my_lib $ bundle exec guard init
~/code/my_lib $ vim Guardfile # Remove the sections below the top one
~/code/my_lib $ git add Guardfile
~/code/my_lib $ git commit -am "Add Guard"

After you're happy with your creation, push it up to github

对自己的创作感到满意后，将其推送到 github

# create a github repository for your gem, then push it up
~/code/my_lib $ curl -u myusername https://api.github.com/user/repos -d '{"name":"my_lib"}' 
~/code/my_lib $ git remote add origin [email protected]:myusername/my_lib.git
~/code/my_lib $ git push

Then, when you're ready to release your gem on Rubygems.org, run rake release, which will walk you through the steps.

然后，当您准备好在 Rubygems.org 上发布您的 gem 时，运行rake release，它将引导您完成这些步骤。

~/code/my_lib $ rake release

Further References

进一步参考

• The Rubygems patterns guide(and home page), from Matheus Moreira's answer. They're really great references
• How I Startby Steve Klabnik
• Exercise 46: A Project Skeletonfrom Zed Shaw's Learn Ruby The Hard Way
• New Gem with Bundlervideo on Railscasts
• docs

• 该RubyGems的模式引导（和主页），从马特乌斯莫雷拉的答案。他们真的是很好的参考
• 我是如何开始的 Steve Klabnik
• 练习 46：来自 Zed Shaw 的Learn Ruby The Hard Way 的项目骨架
• Railscasts 上的带有 Bundler 的新 Gem视频
• 文档

回答by Matheus Moreira

There are some nice guides at rubygems.orgthat will introduce you to the conventions and the reasoning behind some of them. In general, the Rubygems naming and directory conventionsare followed by most Ruby developers.

rubygems.org上有一些不错的指南，它们将向您介绍约定和其中一些背后的推理。通常，大多数 Ruby 开发人员都遵循Rubygems 命名和目录约定。

I would only create custom exception classes if I wasn't able to find any class in the standard library fits the error description. Nest your error class under the class or module that raises it:

如果我无法在标准库中找到任何符合错误描述的类，我只会创建自定义异常类。将您的错误类嵌套在引发它的类或模块下：

class Parser::Error < RuntimeError; end

begin
  Parser.new(:invalid).parse!
rescue Parser::Error => e
  puts e.message
end

Unit tests go either into /test, if you're using Test::Unit, or into /specif you're using RSpec. I recommend the latter.

单元测试要么进入/test，如果你正在使用Test::Unit，要么进入，/spec如果你正在使用RSpec. 我推荐后者。

Bundleris a great way to manage your load path. It will automatically set up your environment with only the dependencies specified on the Gemfileand optionally the gemspec. It also allows you to easily requireyour code without making it a gem.

Bundler是管理加载路径的好方法。它将自动设置您的环境，仅Gemfile使用gemspec. 它还允许您轻松地require编写代码，而不会使其成为 gem。

However, since you might bundle your code in a gem in the future, I recommend investigating how to create gem specifications. You should write your specification manually. Don't use some tool to automagically generate it - they are, in my opinion, brute force approaches that needlessly duplicate information and wreak havoc when used with source control.

但是，由于您将来可能会将代码捆绑在 gem 中，因此我建议您研究如何创建 gem 规范。您应该手动编写规范。不要使用某些工具来自动生成它 - 在我看来，它们是蛮力方法，在与源代码控制一起使用时会不必要地复制信息并造成严重破坏。

I created a gemwhich you may find useful. Given a gemspecfile, it defines many useful Raketasks for working with your gem, which include tasks for building, installing and releasing your gem to rubygemsand gitrepository with automatic version tagging. It also provides an easy way to load your code in a irbor prysession.

我创建了一个 gem，您可能会发现它很有用。给定一个gemspec文件，它定义了许多有用的Rake与您的宝石，其中包括建筑，安装和释放你的宝石任务的工作任务rubygems，并git与自动版本标记库。它还提供了一种在irb或pry会话中加载代码的简单方法。

# Rakefile
require 'rookie'

# Run `rake -T` for the complete task list
Rookie::Tasks.new('your_gem.gemspec').define_tasks!

回答by user2398029

Here are the conventions I have most often seen (assuming your project's name is "foo"):

以下是我最常看到的约定（假设您的项目名称是“foo”）：

• /lib/foo.rb - Defines the top-level namespace of the project and its version; requires needed files.
• /lib/foo/ - Contains all classes for your project, including error-related classes.
• /test/ - Contains tests for your project.
• /spec/ - Contains the specs for your project.
• /bin/ - If your project depends on binaries (JAR files, etc.), they usually go in there.

• /lib/foo.rb - 定义项目的顶级命名空间及其版本；需要需要的文件。
• /lib/foo/ - 包含项目的所有类，包括与错误相关的类。
• /test/ - 包含项目的测试。
• /spec/ - 包含项目的规范。
• /bin/ - 如果您的项目依赖于二进制文件（JAR 文件等），它们通常会放在那里。

Inside lib/, the convention is usually to create a folder for each sub-namespace inside your top-level namespace. For example, the class Foo::Bar::Baz is usually found under /lib/foo/bar/baz.rb.

在 lib/ 中，约定通常是为顶级命名空间内的每个子命名空间创建一个文件夹。例如，类 Foo::Bar::Baz 通常位于 /lib/foo/bar/baz.rb 下。

Some people like to create a /lib/foo/version.rb file just to set the Foo::VERSION constant, but very often I have seen this defined in the /lib/foo.rb file.

有些人喜欢创建一个 /lib/foo/version.rb 文件只是为了设置 Foo::VERSION 常量，但我经常看到这个定义在 /lib/foo.rb 文件中。

Also, if you are creating a gem, you will need the following files:

此外，如果您正在创建 gem，您将需要以下文件：

• /Rakefile - Defines rake tasks (such as tasks for testing, building and pushing the gem).
• /Gemfile - Defines the source of the gem (among other possible things).
• /foo.gemspec - Describes your gem and provides a list of dependencies.

• /Rakefile - 定义 rake 任务（例如用于测试、构建和推送 gem 的任务）。
• /Gemfile - 定义 gem 的来源（以及其他可能的东西）。
• /foo.gemspec - 描述您的 gem 并提供依赖项列表。

回答by Xiao Hanyu

There're some guides on the internet about how to structure a Ruby project. Besides, I think the best way to solve this is heading over github and looking for some famous Ruby project, and check "their" structures.

互联网上有一些关于如何构建 Ruby 项目的指南。此外，我认为解决这个问题的最好方法是前往 github 并寻找一些著名的 Ruby 项目，并检查“他们的”结构。

Besides general ruby gem requirements, I recommend the following tools for better workflow:

除了一般的 ruby​​ gem 要求之外，我还推荐以下工具以获得更好的工作流程：

• editorconfig, helps developers define and maintain consistent coding styles between different editors and IDEs.
• rubocop, static code analyzer for ruby, the defac to linter in ruby community.
• guard, together with a bunch of plugins, you can run any commands as you like when code changes, automatically.
• rake, the universal driver for various project tasks, such as:
  • package: build gem package
  • clean: clean generated files
  • test: run test
• yard, popular ruby documentation tool.

• editorconfig，帮助开发人员在不同的编辑器和 IDE 之间定义和维护一致的编码风格。
• rubocop，ruby 的静态代码分析器，ruby 社区中用于 linter 的 defac。
• guard，连同一堆插件，你可以在代码更改时自动运行任何命令。
• rake，各种项目任务的通用驱动程序，例如：
  • package: 构建 gem 包
  • clean: 清理生成的文件
  • test: 运行测试
• yard，流行的 ruby​​ 文档工具。

And besides all of the above tools, their're some online service for ruby project:

除了上述所有工具，他们还有一些 ruby​​ 项目的在线服务：

• CI(Continuous Integration)
  • travis-ci
  • circleci
  • codeship
• Code Review
  • codeclimate

• CI（持续集成）
  • 特拉维斯
  • 圈子
  • 代号
• 代码
  • 代码气候

And you can even genearate badges via http://shields.io/for your open source project.

您甚至可以通过http://shields.io/为您的开源项目生成徽章。

That's my experience, hope it helps for some one.

这是我的经验，希望对大家有所帮助。