DevHeads.net

Typical Ruby (non-rails) project structure.

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?

Comments

Re: Typical Ruby (non-rails) project structure.

By Richard Conroy at 07/23/2010 - 13:13

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.

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.

Re: Typical Ruby (non-rails) project structure.

By Carl Jenkins at 07/23/2010 - 13:28

Richard Conroy wrote:
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!

Re: Typical Ruby (non-rails) project structure.

By Jarmo Pertman at 07/27/2010 - 11:47

On Jul 23, 9:28 pm, Carl Jenkins <carljenk...@gmail.com> wrote:
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 :)

Re: Typical Ruby (non-rails) project structure.

By brabuhr at 07/23/2010 - 16:04

On Fri, Jul 23, 2010 at 2:28 PM, Carl Jenkins < ... at gmail dot com> wrote:
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]))
[...]

Re: Typical Ruby (non-rails) project structure.

By Carl Jenkins at 07/23/2010 - 16:58

unknown wrote:
haha - that's genius..

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

Re: Typical Ruby (non-rails) project structure.

By R.. Kumar 1.9.1 OSX at 07/23/2010 - 01:26

Carl Jenkins wrote:
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.

Re: Typical Ruby (non-rails) project structure.

By Mark T at 07/22/2010 - 20:11

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

Re: Typical Ruby (non-rails) project structure.

By Carl Jenkins at 07/22/2010 - 20:27

Mark T wrote:
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.

Re: Typical Ruby (non-rails) project structure.

By Intransition at 07/22/2010 - 15:50

On Jul 22, 1:41 pm, Carl Jenkins <carljenk...@gmail.com> wrote:
<a href="http://wiki.github.com/proutils/setup/creating-packages" title="http://wiki.github.com/proutils/setup/creating-packages">http://wiki.github.com/proutils/setup/creating-packages</a>

Re: Typical Ruby (non-rails) project structure.

By Tim Pease at 07/22/2010 - 13:41

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

Re: Typical Ruby (non-rails) project structure.

By Carl Jenkins at 07/23/2010 - 12:54

Tim Pease wrote:

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....

Re: Typical Ruby (non-rails) project structure.

By =?utf-8?Q?Marvi... at 07/22/2010 - 14:37

Tim Pease wrote:
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... ;-)

Marvin

Re: Typical Ruby (non-rails) project structure.

By =?utf-8?Q?Marvi... at 07/22/2010 - 13:08

Carl Jenkins wrote:
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

Re: Typical Ruby (non-rails) project structure.

By Carl Jenkins at 07/22/2010 - 13:12

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?

Re: Typical Ruby (non-rails) project structure.

By brabuhr at 07/22/2010 - 13:38

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

Re: Typical Ruby (non-rails) project structure.

By =?utf-8?Q?Marvi... at 07/22/2010 - 13:33

Carl Jenkins wrote:
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

Re: Typical Ruby (non-rails) project structure.

By =?utf-8?Q?Marvi... at 07/22/2010 - 13:36

Marvin Gülker wrote:
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