Typical Ruby (non-rails) project structure


#1

What is/are the best-practice(s) for a Ruby project structure?

As I am just learning Ruby I put everything in one file but, now I am
learning about Modules etc…

In Java, classes where in packages which helped with code organization.
Is there a typical way to layout a Ruby project structure?


#2

Carl J. wrote:

What is/are the best-practice(s) for a Ruby project structure?

As I am just learning Ruby I put everything in one file but, now I am
learning about Modules etc…

In Java, classes where in packages which helped with code organization.
Is there a typical way to layout a Ruby project structure?

I think the RubyGems guidelines describe how a ruby project is typically
structured. Additionally, I tend to create a directory for each module
and a file for each class:

/
bin/ #Put your executables here
data/ #Everything else needed for the project
doc/ #RDoc for the lib/ directory
ext/ #C-Extensions go here
lib/ #Everything internal is handled here
- my_namespace.rb #Contains module methods for MyNamespace
my_namespace/ #Directory for classes in MyNamespace
- my_class.rb #Contains MyClass
my_inner_namespace/
- my_2nd_class.rb

Marvin


#3

/
bin/ #Put your executables here
data/ #Everything else needed for the project
doc/ #RDoc for the lib/ directory
ext/ #C-Extensions go here
lib/ #Everything internal is handled here
- my_namespace.rb #Contains module methods for MyNamespace
my_namespace/ #Directory for classes in MyNamespace
- my_class.rb #Contains MyClass
my_inner_namespace/
- my_2nd_class.rb

Marvin

So all my code looks like it would go under lib/ correct?
What does -my_namespace.rb refer to? Is this the Ruby class driver for
the applicaiton? Also my_inner_namespace… not sure I understand this?


#4

Carl J. wrote:

/
bin/ #Put your executables here
data/ #Everything else needed for the project
doc/ #RDoc for the lib/ directory
ext/ #C-Extensions go here
lib/ #Everything internal is handled here
- my_namespace.rb #Contains module methods for MyNamespace
my_namespace/ #Directory for classes in MyNamespace
- my_class.rb #Contains MyClass
my_inner_namespace/
- my_2nd_class.rb

Marvin

So all my code looks like it would go under lib/ correct?
What does -my_namespace.rb refer to? Is this the Ruby class driver for
the applicaiton? Also my_inner_namespace… not sure I understand this?

Most of the code goes under lib/, that’s correct. The -my_namespace.rb
isn’t anything special, my_namespace.rb is a regular Ruby file. I just
used a - sign to distinguish a file from a directory, i.e. if I write

dir/

  • file1.rb
  • file2.rb
    subdir/
    • file3.rb

then those ending with / are directories and those beginning with - are
files. Regarding your other question I just repost my example with more
comments:

/
bin/ #Put your executables here
data/ #Everything else needed for the project, e.g. graphics
doc/ #RDoc for the lib/ directory, auto-generated by running the rdoc
command
ext/ #C-Extensions go here
lib/ #Everything internal is handled here
- my_namespace.rb #Contains module methods for MyNamespace
my_namespace/ #Directory for classes in MyNamespace
- my_class.rb #Contains MyNamespace::MyClass
my_inner_namespace/ #Directry for classes in
MyNamespace::MyInnerNamespace
- my_2nd_class.rb #Contains
MyNamespace::MyInnerNamespace::My2ndClass

Marvin


#5

Marvin Gülker wrote:

/
bin/ #Put your executables here
data/ #Everything else needed for the project, e.g. graphics
doc/ #RDoc for the lib/ directory, auto-generated by running the rdoc
command
ext/ #C-Extensions go here
lib/ #Everything internal is handled here
- my_namespace.rb #Contains module methods for MyNamespace
my_namespace/ #Directory for classes in MyNamespace
- my_class.rb #Contains MyNamespace::MyClass
my_inner_namespace/ #Directry for classes in
MyNamespace::MyInnerNamespace
- my_2nd_class.rb #Contains
MyNamespace::MyInnerNamespace::My2ndClass

Oops, that got malformatted. Here’s a better version:

/
bin/ #Put your executables here
data/ #Everything else needed for the project, e.g. graphics
doc/ #RDoc for the lib/ dir, auto-generated by running “rdoc”
ext/ #C-Extensions go here
lib/ #Everything internal is handled here
- my_namespace.rb #Contains module methods for MyNamespace
my_namespace/ #Directory for classes in MyNamespace
- my_class.rb #Contains MyNamespace::MyClass
my_inner_namespace/ #classes in MyNamespace::MyInnerNamespace
- my_2nd_class.rb #MyNamespace::MyInnerNamespace::My2ndClass

Marvin


#6
     - my_2nd_class.rb

So all my code looks like it would go under lib/ correct?
What does -my_namespace.rb refer to? Is this the Ruby class driver for
the applicaiton? Also my_inner_namespace… not sure I understand this?

I think he means something like:

/
lib/
library_name.rb
# This is the file that consumers of this
# library will require; it will create the
# module and load the actual library.

        require './library_name/library_class'

        module LibraryName
            VERSION  = "..."
        end
    library_name/
        library_class.rb
            # The class that implements the library.

            module LibraryName
                class LibraryClass
                end
            end
        another_class.rb
            # A support class for the library.

            module LibraryName
                class AnotherClass
                end
            end
        submodule/
            yet_another_class.rb
                # A support class in a submodule.

                module LibraryName
                    module Submodule
                        class YetAnotherClass
                        end
                    end
                end

#7

On Jul 22, 2010, at 11:41 AM, Carl J. wrote:

What is/are the best-practice(s) for a Ruby project structure?

As I am just learning Ruby I put everything in one file but, now I am
learning about Modules etc…

In Java, classes where in packages which helped with code organization.
Is there a typical way to layout a Ruby project structure?

Take a look at Mr Bones. It encapsulates many ruby best-practices and
lots of rake tasks to take care of the day-to-day development tasks

gem install bones

bones create new_project
cd new_project

rake -T # shows you all the available tasks
rake bones:help # shows you the various project configuration
settings

Other tools in the same vein as Mr Bones are “hoe” and “jeweler”

gem install hoe
gem install jeweler

I’m slightly partial to Mr Bones being the author and all.

Blessings,
TwP


#8

Tim P. wrote:

On Jul 22, 2010, at 11:41 AM, Carl J. wrote:

What is/are the best-practice(s) for a Ruby project structure?

As I am just learning Ruby I put everything in one file but, now I am
learning about Modules etc…

In Java, classes where in packages which helped with code organization.
Is there a typical way to layout a Ruby project structure?

Take a look at Mr Bones. It encapsulates many ruby best-practices and
lots of rake tasks to take care of the day-to-day development tasks

gem install bones

bones create new_project
cd new_project

rake -T # shows you all the available tasks
rake bones:help # shows you the various project configuration
settings

Other tools in the same vein as Mr Bones are “hoe” and “jeweler”

gem install hoe
gem install jeweler

I’m slightly partial to Mr Bones being the author and all.

Blessings,
TwP

I’m not sure that’s what the OP wants. He didn’t state he wanted to
build gems, he just wanted to know how a general Ruby projekt is
structured (an end-user desktop app maybe?). Well, if one consideres a
gem as the standard way to write a general Ruby project… :wink:

Marvin


#9

On Jul 22, 1:41 pm, Carl J. removed_email_address@domain.invalid wrote:

What is/are the best-practice(s) for a Ruby project structure?

As I am just learning Ruby I put everything in one file but, now I am
learning about Modules etc…

In Java, classes where in packages which helped with code organization.
Is there a typical way to layout a Ruby project structure?

http://wiki.github.com/proutils/setup/creating-packages


#10

My advice is to build a unique folder at root on a unix boxen (ex: RP1).
In your profile, modify RUBYLIB to point to a sub folder of this.
In your profile, modify GEM_HOME to point to an adjacent folder to this.

Modify Then install Ruby to said folder with .configure option.
Install gems.
In your profile: RUBYOPT=rubygems,

Then all updates to Ruby or gems will only require user perms.
Your code can be in a subfolder of (RP1).
Additionally, the entire folder structure can be easily backed up,
transferred or rsync’d.
Handy for remote instance installs.
Use VMware/Virtualbox as local test area.

Then get funky with code paths.

MarkT


#11

Mark T wrote:

My advice is to build a unique folder at root on a unix boxen (ex: RP1).
In your profile, modify RUBYLIB to point to a sub folder of this.
In your profile, modify GEM_HOME to point to an adjacent folder to this.

Modify Then install Ruby to said folder with .configure option.
Install gems.
In your profile: RUBYOPT=rubygems,

Then all updates to Ruby or gems will only require user perms.
Your code can be in a subfolder of (RP1).
Additionally, the entire folder structure can be easily backed up,
transferred or rsync’d.
Handy for remote instance installs.
Use VMware/Virtualbox as local test area.

Then get funky with code paths.

MarkT

I appreciate your advice but, didn’t understand most of what you were
trying to tell me. Still a bit of a greenhorn with Ruby really.


#12

Carl J. wrote:

What is/are the best-practice(s) for a Ruby project structure?

As I am just learning Ruby I put everything in one file but, now I am
learning about Modules etc…

In Java, classes where in packages which helped with code organization.
Is there a typical way to layout a Ruby project structure?

I would suggest using the same structure as the gem structure. You can
use jeweler or any of the others mentioned. THis is especially useful if
you might want to release as a gem later. In any case, if you do release
gems in addition to this, its best to be used to one structure.

If you are creating command-line programs or scripts, do look at thor,
commander and gli. And hibernate.

It’s up to you to put one or more classes in one file.

Typically, we have multiple folders within “lib”, so these folders can
be your packages. There was a thread recently on modules, it has some
good links for more info.


#13

Tim P. wrote:

On Jul 22, 2010, at 11:41 AM, Carl J. wrote:

What is/are the best-practice(s) for a Ruby project structure?

As I am just learning Ruby I put everything in one file but, now I am
learning about Modules etc…

In Java, classes where in packages which helped with code organization.
Is there a typical way to layout a Ruby project structure?

Take a look at Mr Bones. It encapsulates many ruby best-practices and
lots of rake tasks to take care of the day-to-day development tasks

gem install bones

bones create new_project
cd new_project

rake -T # shows you all the available tasks
rake bones:help # shows you the various project configuration
settings

Other tools in the same vein as Mr Bones are “hoe” and “jeweler”

gem install hoe
gem install jeweler

I’m slightly partial to Mr Bones being the author and all.

Blessings,
TwP

I just tried ‘bones’ and it works perfectly!

I did install ‘jeweler’ but, for some reason I am getting errors;
probably because I do not have git installed or an account yet…


#14

On Thu, Jul 22, 2010 at 6:41 PM, Carl J. removed_email_address@domain.invalid
wrote:

What is/are the best-practice(s) for a Ruby project structure?

Use the gem structure. Its pretty universal for packaging, structuring
and
even deploying Ruby projects. Rails projects use their own structure,
but
its well documented too.

As I am just learning Ruby I put everything in one file but, now I am
learning about Modules etc…

In Java, classes where in packages which helped with code organization.
Is there a typical way to layout a Ruby project structure?

Note that in Java packages also map 1:1 with the directory structure of
the
classes, that is quite strict. In Ruby, the hierarchy of namespaces has
no implications on how ruby files are loaded.

I haven’t seen much information, beyond the replies here, that implies
any consensus on how these files are structured or named.

It is worth researching exactly how ‘require’ and the load path works in
Ruby. It is a bit alien coming from a Java background, but the mechanics
of how it works will imply its own best practices.


#15

On Fri, Jul 23, 2010 at 2:28 PM, Carl J. removed_email_address@domain.invalid
wrote:

but
test/
-new_test.rb

In order to test the new_file.rb my new_test.rb must have the path to
the new_file.rb as the require correct? Something like require
‘…/lib/common/new_file’

Or is there a different way to do that?

Just looked at one of my bones-generated projects:

$ cat spec/spec_helper.rb

require File.expand_path(
File.join(File.dirname(FILE), %w[… lib fooz]))
[…]


#16

Richard C. wrote:

On Thu, Jul 22, 2010 at 6:41 PM, Carl J. removed_email_address@domain.invalid
wrote:

What is/are the best-practice(s) for a Ruby project structure?

Use the gem structure. Its pretty universal for packaging, structuring
and
even deploying Ruby projects. Rails projects use their own structure,
but
its well documented too.

As I am just learning Ruby I put everything in one file but, now I am
learning about Modules etc…

In Java, classes where in packages which helped with code organization.
Is there a typical way to layout a Ruby project structure?

Note that in Java packages also map 1:1 with the directory structure of
the
classes, that is quite strict. In Ruby, the hierarchy of namespaces has
no implications on how ruby files are loaded.

I haven’t seen much information, beyond the replies here, that implies
any consensus on how these files are structured or named.

It is worth researching exactly how ‘require’ and the load path works in
Ruby. It is a bit alien coming from a Java background, but the mechanics
of how it works will imply its own best practices.

When using them gem structure for example I have something like this.

new_proj/
bin/
lib/
common/
-new_file.rb
spec/
test/
-new_test.rb

In order to test the new_file.rb my new_test.rb must have the path to
the new_file.rb as the require correct? Something like require
‘…/lib/common/new_file’

Or is there a different way to do that?

Thanks for all the help - (everyone) this is most helpful!


#17

unknown wrote:

On Fri, Jul 23, 2010 at 2:28 PM, Carl J. removed_email_address@domain.invalid
wrote:

but
�test/
�-new_test.rb

In order to test the new_file.rb my new_test.rb must have the path to
the new_file.rb as the require correct? Something like require
‘…/lib/common/new_file’

Or is there a different way to do that?

Just looked at one of my bones-generated projects:

$ cat spec/spec_helper.rb

require File.expand_path(
File.join(File.dirname(FILE), %w[… lib fooz]))
[…]

haha - that’s genius…

(I should have known better and just looked myself.)


#18

On Jul 23, 9:28 pm, Carl J. removed_email_address@domain.invalid wrote:

In order to test the new_file.rb my new_test.rb must have the path to
the new_file.rb as the require correct? Something like require
‘…/lib/common/new_file’

Or is there a different way to do that?

Thanks for all the help - (everyone) this is most helpful!

I would play with the $LOAD_PATH in your spec_helper or whatnot:

spec_helper.rb

$LOAD_PATH.unshift(File.join(File.dirname(FILE), “…/lib”))

blah_spec.rb

require “spec_helper” # require in every spec file
require “my_class” # now it’s possible to require my_class from lib
dir because of changed $LOAD_PATH

describe MyClass do
it “test, test, test!” do
MyClass.new.should be
end
end

Or, if using really RSpec, then create a spec.opts file into the spec
directory and require it from there:
–require
spec_helper

Then you can remove those require statements from spec files
themselves. Although if you’re using some kind of an IDE, then they
might get confused, but i don’t mind :slight_smile: