From: ptkwt@...1.aracnet.com (Phil Tomson)
Date: 2002-11-22T06:56:09+09:00
Subject: install.rb: avoiding file name collisions (raa-install too)

[Maybe this should be added to the packaging FAQ or perhaps to 
QuickGuideToPackaging on the RubyGarden wiki - I post it here for 
discussion first.]

<FAQ_ITEM>
This falls under the catagory of good manners...
Let's say that I've got a package I call 'Template'.  Now it seems that in 
order to avoid namespace collisions with 
other packages I should actually call it something like: 
'Text::Template' and I should wrap my 'Template' module in a 'Text' module 
like so:

module Text
  module Template
  end
end

Now I'm thinking that others might also use the Text module for other 
packages they create like: Text::Parse

module Text
  module Parse
  end
end

So, my Text::Template module is defined in a file called template.rb
What if someone else does an HTML::Template module that is also defined in 
a file called template.rb.  The last one installed will overwrite the 
other file in the Ruby library location.  The easy fix is to rename my 
template.rb file to something more specific like texttemplate.rb, but 
that requires me to know a lot about what others have called their library 
files.
When there is  potential for collisions in the namespace, we wrap 
modules in other modules in order to avoid this, but how do we avoid the 
problem of a library file (that contains a module definition) having 
potentially the same name as an already existing library file?

The answer lies in how I organize my package directories.  Remember that 
install.rb will install files in the lib subdirectory of my package in the 
directory 'RUBY_INSTALL_DIR/lib/ruby/site_ruby/1.x/'.  As it turns out 
install.rb will also recursively descent into our package's lib directory 
so that we could have subdirectories under the lib directory.  These 
subdirectories of lib will get created in 
'RUBY_INSTALL_DIR/lib/ruby/site_ruby/1.x/'.  So my hopothetical 
Text::Template package should be organized as follows (only showing the 
lib directory contents):

lib/
  text/
    template.rb


Now when a user wants to use Text::Template, they must:

require 'text/template'

So here's a suggestion for a convention:  Wherever you see a '::' in a 
package name, it should imply a subdirectory within your package and 
within Ruby's libraries:

Text::Template -> 'text/template'
</FAQ_ITEM>

<SOAPBOX>
And we should probalby be using a lot more '::'s in our package names.

I see several XML* packages that should probably be changed to 'XML::*' 
type names.

Does raa-install have any facility to search a namespace like:
raa-install --search XML::*  ?

</SOAPBOX>

BTW: I find that 'raa-install --search' doesn't work for me as advertised:

$ raa-install --search xml
/usr/bin/raa-install: unrecognized option `--search'
/usr/lib/ruby/1.6/getoptlong.rb:264:in `set_error': unrecognized option 
`--search' (GetoptLong::InvalidOption)
        from /usr/lib/ruby/1.6/getoptlong.rb:363:in `get'
        from /usr/lib/ruby/1.6/getoptlong.rb:457:in `each'
        from /usr/lib/ruby/1.6/getoptlong.rb:457:in `loop'
        from /usr/lib/ruby/1.6/getoptlong.rb:457:in `each'
        from /usr/bin/raa-install:32
 
Phil