''This is an early stage version of a page we could introduce for every major group of ports which should follow certain common principles, and where the involved maintainers can collect the results of their discussions. I suggest introducing a similar page for Python, Perl, Erlang, and similar cases as well, if it turns out to be useful. Feel free to edit as you see fit. --[wiki:febeling]''

== Ruby Section ==

This page describes the general organization of the ruby section. It contains information about Ruby implementations
and the library packages, and how they are generally used in MacPorts. Information is divided into a that relevant for users of these ports, and information for maintainers. It should address things like naming conventions, dealing with different versions of the
language implementation and how it works together with the package manager {{{gem}}} and other installation methods.

== Usage Information ==

Ports providing a ruby library package have a prefix {{{rb}}} or {{{rb19}}}. So the Rails port is called rb-rails, e.g. If you installed a port which installs a rubygem, you should avoid manipulating that port with {{{gem}}} directly, since that makes the information inside MacPorts inconsistent. If you use gem a lot directly, you might be better off if you these exclusively.

== Guidelines for Ruby Ports ==
 * should have a name prefix of "rb" for 1.8, and "rb19" for 1.9. It would be nice to have ports compatible with both, but that is not possible, since the library paths for ruby get determined during configuration phase and are specific for the different versions. 
 * should generally be created using the ruby port group. This provides almost everything you need to do in a ruby portfile if you use the {{{ruby.setup}}} command. {{{ruby.setup}}} allows to create ports for ruby (1.8) and ruby19 already.


== Problems & Potential Improvements ==

 * many ruby library ports are installed by invoking the Rubygems installer program {{{gem}}}. Since that is just a regular command line tool, a package installed as port can be uninstalled or upgraded using {{{gem}}} directly. That results in an inconsistent state of the registry, because a certain version of some software is marked as installed, while in fact it isn't or not in that version. This should be solved in some way, maybe by installing in a special location of that is possible.
 * There are a number of ruby implementations available, but currently only Matz' Ruby 1.8.7 is invokable just as {{{ruby}}}, or Matz' Ruby 1.9.1 is installed with variant {{{+nosuffix}}}. The variant causes ruby 1.9 to install withuout the suffix, but that makes it conflict with port {{{ruby}}}, i.e. 1.8.7. On the list Brett Eisenberg has suggested fixing that using the same approach as python_select and gcc_select, i.e. by writing configuration symlinks in a PATH location. 
 * To be discussed: should library ports for ruby generally be avoided in favor of the now ubiquitous gem (part of the 1.9 release)? Gems easily break the repository's consistency if packages are not managed exclusively over {{{port}}} or {{{gem}}}. OTOH library ports are the only way to provide dependencies to apps building onto these libs which we want as ports.

== Section Maintainers ==

[wiki:febeling] ''add yourself here''