ruby-core

On Dec 16, 2003, at 8:30 AM, Gavin Sinclair wrote:

> On Tuesday, December 16, 2003, 3:29:54 PM, Yukihiro wrote:
>
>> Hi,
>
>> In message "Re: Where to install documentation"
>>     on 03/12/16, Dave Thomas <dave@pragprog.com> writes:
>
> |>> I think data for standard tools should be somewhere under
> |>>
> |>>   $prefix/lib/ruby/<ver>
> |>>
> |>> e.g. /usr/lib/ruby/1.8/doc/rdoc
>> |
>> |Matz:
>> |
>> |That's where I went initially, but then I got thinking. Say RubyGems
>> |supports automatic installation of documentation. Should it go into
>> |site_ruby?
>
>> It should be done by RubyGems, i.e. gems installer should switch
>> installing directory depending on how it's going to install.  When a
>> gem is installed as a part of system's packages, the gem (including
>> documents) should be installed to the standard place.  Otherwise, it
>> should go to site_ruby directory.
>
> That is an interesting comment that I don't fully understand.  Can you
> elaborate, Matz?  Chad, what do you think?
>
> Cheers,
> Gavin
>

Well, not being Chad or Matz let me chime in since I implemented the 
Gems
doc stuff ;-)

Let me introduce the gems path stuff that we have arrived at so far:

where '...'== the root install point of ruby libraries (e.g. 
/usr/local/lib).

.../ruby
.../ruby/<ver>/**/*.rb,*.so
.../ruby/site_ruby/<ver>/**/*.rb,*.so

We settled on:

.../ruby/gems/<ver>/

For the root gems directory.  The reason for this was a bit involved, 
but
my thinking is that Gems should not interfere with the current library
structure of Ruby, and that Gems, at its core, is actually a manager of
the $LOAD_PATH.  When you install Ruby libraries today, they all go in
the same place, and whereas this is nice (from a 'require' standpoint)
management of those installed libraries is a pain.  So with Gems, we
decided that one of our goals was to enable the simplified installation
and management of installed libraries (including maintaining multiple
versions of a particular library).  We accomplish this by having each
Gem'ed up library install itself in a version unique path:

.../ruby/gems/<ver>/library-version/..

Then we add this command:

   require_gem 'gem', [version]

Which searches the installed Gems for one that meets the Gem/version
requirement and modifies the $:/$LOAD_PATH to enable subsequent
'require' statements to find the *.rb/*.so files.  Also, in the Gem
specification, you can 'autorequire' a particular Ruby file, thus
the 'require_gem' command may very well be all you need to do.

Then came the question of documentation.  The current implmentation
lets you add a declaration that your library is RDoc'ed.  If so, a
user can install the RDoc for a Gem (actually, it generates the RDoc
from the Gem source.  We had the same issue of where to put it.

We settled on this:

.../ruby/gems/<ver>/rdoc/library-version/**/*.html, etc

This has each of the Gems docs are under a common directory, and
this can easily be served up (via Webrick) in a browser.  You end
up with an index page which documents each installed Gem + version
and a link to its RDoc documentation (if generated).

Another thing we did, is let a person modify the $GEM_PATH to not
be _just_ the .../ruby/gems/<ver> but also include any number of
other directories (perhaps in ~/gems, etc).  Each of these paths are
searched (in order) for Gems.  There is, in addition to the global
$GEM_PATH the ability to have an ENV variable (RUBY_GEMS) which
defines this path.

Anyway, that is what Gems is today.  It obviously can be changed,
but there are lots of things to keep in mind in doing so (more
than I have articulated above).

More info on Gems is here:  http://rubygems.rubyforge.org

Best,

Rich

Thread

Prev Next

In This Thread

Prev Next