Search code examples
rubyproject-structure

How do I set up a basic Ruby project?

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.

Solution

  • 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 git@github.com: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