How do I set up a basic Ruby project?

Question

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

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

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?

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.

Answer 1

To get a good start, you can use the bundle gem command and 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

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

1. Edit my_lib.gemspec, adding gem.add_development_dependency 'rspec' and gem.add_development_dependency 'rake' near the bottom.
2. Add Bundler.setup and 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 => :spec to your Rakefile, so that running rake will run your specs.

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

~/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

# 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.

~/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 Start by Steve Klabnik
• Exercise 46: A Project Skeleton from Zed Shaw's Learn Ruby The Hard Way
• New Gem with Bundler video on Railscasts
• docs

Answer 2

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

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 /spec if you're using RSpec. I recommend the latter.

Bundler is a great way to manage your load path. It will automatically set up your environment with only the dependencies specified on the Gemfile and optionally the gemspec. It also allows you to easily require your code without making it a 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.

I created a gem which you may find useful. Given a gemspec file, it defines many useful Rake tasks for working with your gem, which include tasks for building, installing and releasing your gem to rubygems and git repository with automatic version tagging. It also provides an easy way to load your code in a irb or pry session.

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