Configuration

Configuration

Installation | Table Of Contents | Application

Shell Setup

In order to utilize Library, Ruby has to be made aware of it. To do this add some setup code to your shell's runtime configuration script, e.g. the .bashrc file. We recommended doing this via a secondary file. So to the .bashrc or equivalent file add to the end something like:

    if [ -f ~/.bash/ruby.sh ]; then
      . ~/.bash/ruby.sh
    fi

Then create the ~/.bash/ruby.sh script containing the following lines:

    export RUBYOPT="-rubylibs"
    export RUBYPATH="$(ruby -e 'puts Library::sync')"
    export PATH="$PATH:$RUBYPATH"

The first line ensures that Library is loaded every time Ruby is executed. If you have other entries in the RUBYOPT variable already it is usually best that the -rubylibs occur before the others.

The second line ensures that that current cached ledger is in sync with the current contents of library locations. It also returns a list of bin/ directories for all those libraries. By appending this to the system's PATH variable, the executables of the libraries handled by Library are made available on the command line.

Note that this PATH approach to executables requires that the bin files have their executable bits turned on and have the proper header (i.e. #!usr/bin/env ruby). Also keep in mind that while this approach works for most operating systems (i.e. Unix-based systems), other systems may need to use binstubs instead. At this time binstubs is not an implemented feature because current users have not yet needed it. Eventually this will be addressed for future release and volunteers are welcome to step-up and implement it at any time.

Library Locations

By default Realms will serve up the $GEM_PATH locations. For many users that is all that is needed and this section of instruction can be skipped.

Yet Library is very flexible and can be configured in any number of manners to serve up Ruby programs. This can be done by adjusting the locations in which libraries can be found via the $RUBY_LIBRARY environment variable.

For example, lets say a developer wants to ensure that a current project's vendor location is always prepended to the library look-up to ensure the use of any modified dependencies.

    export RUBY_LIBRARY="./vendor:$GEM_PATH"

Now any submodules in a project's vendor/ directory will be accessible via require and load. While not the most robust solution, since it requires the project be run from its root directory, and only makes sense when running in live mode, it is nonetheless an easy example of how one can manipulate the $RUBY_LIBRARY environment variable.

When using a Ruby version manager, and modifying the $RUBY_LIBRARY environment variable for more general purposes, say for instance you want to serve up a special set of Ruby projects that you simply "installed" via a git checkout, you may want to differentiate sets of libraries based on your current Ruby. For example, with chruby, you might do something like:

    export RUBY_LIBRARY="~/ruby-gits/$RUBY_VERSION/:$GEM_PATH"

That way, when you change your current Ruby, you also change which libraries are available. In most cases this is not important, but if the library has any C extensions which must be compiled, then it may be vital to make this differentiation.

Another interesting feature of $RUBY_LIBRARY is that is can take a file, rather then a directory. If a path is a file it will read the file and parse it for additional paths, one for each line in the file. So for instance, one could do:

    export RUBY_LIBRARY="~/.ruby/mylibs"

And then in a file called ~/.ruby/mylibs put:

    ~/ruby-gits/$RUBY_VERSION/
    $GEM_PATH

Which would have the same effect as the prior configuration.

These are just some examples of advanced configuration. How and why a developer might adjust the $RUBY_LIBRARY setting is their call.

Live Mode

The library system can operate in different run modes. The locked-down "production" mode is the default. This mode will always utilize a cached list of available libraries. This means that whenever the configuration changes, e.g. $RUBY_LIBRARY is modified, or when $GEM_PATH is in $RUBY_LIBRARY and a new library has been installed via gem install, then the locked list must be re-synced. If your system as setup as instructed in System Setup, this can be done by re-running the .bash/ruby.sh script.

    . ~/.bash/ruby.sh

Continually having to re-sync can be inconvenient is some situations, to get around this you can set the $RUBY_LIBRARY_LIVE variable to "true".

    export RUBY_LIBRARY_LIVE="true"

In live mode the library ledger will be reconstructed every time ruby runs. This mode is much slower than the locked mode. It also does not suffice if the $PATH environment variable needs to be updated. In that case, you must still re-sync the ledger.

There is a another modality called "development" mode. We will discuss this mode in Application under Dependency Isolation.

Project Conformity

For a library to be accessible as a "Library", it should conform to the common organizational conventions generally used by all Ruby projects.

In addition it is best for a project to provide an .index file (of type: ruby). The .index file is recommended because it makes project metadata look-up faster and more convenient. A .gemspec file will work as a fallback if an .index file isn't found, but this can slow things down a little. See the Indexer project for more information about .index files.

Roll supports library versioning simply by working with the typical repository layout, whether using Subversion, Darcs, Git or some other versioning system, Realms doesn't much care, as long as you follow some basic conventions and provide the necessary metadata. The metadata file means there is no need for special installation repositories, procedures or supporting programs. Your directory layout should generally follow the conventions set by Minero Aoki's setup.rb. Roll simply adds a couple additional details.

Here's an example of a typical Subversion project layout.

    fruitapp/
      tags/
        1.0.0/
          VERSION
          bin/
            ...
          lib/
            fruitapp/
              index.rb
              ...
      trunk/
        VERSION
        bin/
          ...
        lib/
          fruitapp/
            index.rb
            ...

Notice there is 1.0.0 tagged version and a new verison currently being worked on. The above layout is your typcial subversoin repository. Another viable layout is:

    fruitapp/
      1.0.0/
        VERSION
        bin/
          ...
        lib/
          fruitapp/
            index.rb
            ...
      current/
        VERSION
        bin/
          ...
        lib/
          fruitapp/
            index.rb
            ...

This demonstrates the two varieties of Subversion layout that Realms can comprehend. Other SCM's that use directories for tagging with have the same layout. Git, and any SCM that tracks tags internally, on the other hand, will of course not have these additonal layer of subdirectories.

At this point you may be wondering how renaming the lib directory with a changing version is even possible --how will the internal require statements find their files? It's actually quite simple. Realms keeps a map of available libraries and their versions. When a library is first referenced it is instatiated with a particluar version. From then on requests against that libary are routed to that library object where the correct path is used.

!{float:left}important.png! It important to keep the VERSION file up to date. The version number in the VERSION file must correspond to the tag name for realm install to work correctly. This is becuase the install command uses the tag name to locate versions, but Roll's require method uses the VERSION file.

Load Path

One of the most important settings in the .realm file is the the load path, By default the load scope of a library is it's lib/ directory. But you can vary the load path if need be.

Let us consider an example. Assume the following lib/ layout:

    fruitapp/
      fruit/
        apple.rb
      basket/
        wicker.rb

By providing the library with a scope detailing which sub-directories are to be accessible via the directory name, the internal directories are automatically exposed to one another.

  loadpath:
    - lib
    - lib/fruit
    - lib/basket

So given the above, when requiring against the library, the system will search all three internal paths instead of just the main lib/ path. The file apple.rb can contain require 'fruitapp/wicker.rb' and it will find the file in the basket/ directory.