Ruby Project Directory Organization

NOTE: This post will be updated from time-to-time as I learn more.  Right now, it is collection of tidbits gathered together.  There is some conflicting information between a Rails project and a Ruby project.

TODO:  References

Ruby Project

A good Ruby project is organized into one or more modules.  A module's component files are placed into the project hierarchy by what they do.

project
  lib
    module1
      class_a.rb
      class_b.rb
      ...
    module1.rb

  test
    module1
      class_a_test.rb
      class_b_test.rb

We see that a module's files aren't kept together.  Copying a module from project-to-project will involve copy multiple directories and a file or two.

The motivation behind this organization appears to be search path and file name globbing.  One usually runs Ruby with the "-Ilib" command line option set.  A require statement for a module is:

    require 'module1'

Ruby will then locate and identify the code file as:

    lib/module1.rb

The file module1.rb will either be a complete implementation or simply a set of require statements:

    require 'module1/class_a'
    require 'module1/class_b'

Globbing is important as it allows other utilities to act on the appropriate subset of files.  For example, RDoc should be run on all Ruby source files under the lib/ directory but we don't want it to publicly document our test code.  Test runners are similar.

Files are organized into the directory structure for easy and consistent globbing by scripts and other utilities.