Directory layout for pure Ruby project

Question

Hi!

I'm starting to learn ruby. I'm also a day-to-day C++ dev. For C++ projects I usually go with following dir structure

/
 -/bin <- built binaries
 -/build <- build time temporary object (eg. .obj, cmake intermediates)
 -/doc <- manuals and/or Doxygen docs
 -/src
 --/module-1
 --/module-2
 -- non module specific sources, like main.cpp
 - IDE project files (.sln), etc.

What dir layout for Ruby (non-Rails, non-Merb) would you suggest to keep it clean, simple and maintainable?

Answer 1

Why not use just the same layout? Normally you won't need build because there's no compilation step, but the rest seems OK to me.

I'm not sure what you mean by a module but if it's just a single class a separate folder wouldn't be necessary and if there's more than one file you normally write a module-1.rb file (at the name level as the module-1 folder) that does nothing more than require everything in module-1/.

Oh, and I would suggest using Rake for the management tasks (instead of make).

Answer 2

Let's say that module-1 might be a web spider. It might consist of multiple classes and, following the rule "1 class = 1 header file + 1 source file", of multiple files.

So I would treat spider.rb as "header" file that includes all necessary files from /spider?

Also, since everything in Ruby is a source, so naming the dir /src might be inconvenient. I've been looking for RoR's naming of /app, /lib, etc..

Answer 3

@Dentharg: your "include one to include all sub-parts" is a common pattern. Like anything, it has its advantages (easy to get the things you want) and its disadvantages (the many includes can pollute namespaces and you have no control over them). Your pattern looks like this:

- src/
    some_ruby_file.rb:
      require 'spider'
      Spider.do_something

+ doc/

- lib/
  - spider/
      spider.rb:
        $: << File.expand_path(File.dirname(__FILE__))
        module Spider
          # anything that needs to be done before including submodules
        end

        require 'spider/some_helper'
        require 'spider/some/other_helper'
        ...

I might recommend this to allow a little more control:

- src/
    some_ruby_file.rb:
      require 'spider'
      Spider.include_all
      Spider.do_something

+ doc/

- lib
  - spider/
      spider.rb:
        $: << File.expand_path(File.dirname(__FILE__))
        module Spider
          def self.include_all
            require 'spider/some_helper'
            require 'spider/some/other_helper'
            ...
          end
        end

Answer 4

You could install the newgem RubyGem and let it generate the layout for you.

$ gem install newgem
$ newgem spider
      create  
      create  config
      create  doc
      create  lib
      create  script
      create  tasks
      create  lib/spider
      create  History.txt
      create  License.txt
      create  Rakefile
      create  README.txt
      create  PostInstall.txt
      create  setup.rb
      create  lib/spider.rb
      create  lib/spider/version.rb
      create  config/hoe.rb
      create  config/requirements.rb
      create  tasks/deployment.rake
      create  tasks/environment.rake
      create  tasks/website.rake
  dependency  install_test_unit
      create    test
      create    test/test_helper.rb
      create    test/test_spider.rb
  dependency  install_website
      create    website/javascripts
      create    website/stylesheets
      exists    script
      exists    tasks
      create    website/index.txt
      create    website/index.html
      create    script/txt2html
       force    tasks/website.rake
  dependency    plain_theme
      exists      website/javascripts
      exists      website/stylesheets
      create      website/template.html.erb
      create      website/stylesheets/screen.css
      create      website/javascripts/rounded_corners_lite.inc.js
  dependency  install_rubigen_scripts
      exists    script
      create    script/generate
      create    script/destroy
      create  script/console
      create  Manifest.txt
      readme  readme
Important
=========

* Open config/hoe.rb
* Update missing details (gem description, dependent gems, etc.)

Then, in lib/, you create modules as needed:

lib/
  spider/
    base.rb
  crawler/
    base.rb
  spider.rb
    require "spider/base"
    require "crawler/base"

Answer 5

I would stick to something similar to what you are familiar with: there's no point being a stranger in your own project directory. :-)

Typical things I always have are lib|src, bin, test.

(I dislike these monster generators: the first thing I want to do with a new project is get some code down, not write a README, docs, etc.!)

Answer 6

So I went with newgem. I removed all unnecessary RubyForge/gem stuff (hoe, setup, etc.), created git repo, imported project into NetBeans. All took 20 minutes and everything's on green. That even gave me a basic rake task for spec files.

Thank you all.

Answer 7

The latest newgem produces much less cruft which is nice.