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 [e-mail]: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