= Isolate

* http://github.com/jbarnette/isolate

== Description

Isolate is a very simple RubyGems sandbox. It provides a way to
express and install your code's Gem dependencies.

When Isolate runs, it uses GEM_HOME, GEM_PATH, and a few other tricks
to completely separate your code from the system's RubyGems
configuration, leaving it free to run in blissful solitude.

While Isolate doesn't make any assumptions about what sort of code
you're writing, it was extracted from a few Rails apps, so it's
naturally going to be most useful with stuff like Rails, Merb, or
Sinatra.

Isolate is very, very, very stupid simple. For a much more
full-featured Gem bundler, check out Yehuda Katz and Carl Lerche's
Bundler[http://github.com/wycats/bundler]: It does a lot of fancy AOT
dependency resolution, supports non-gem resources, and is probably a
better fit for you. For a widely used Gem manager and installer, check
out Chad Woolley's GemInstaller[http://geminstaller.rubyforge.org].

YMMV, but I haven't tried Isolate with anything older than RubyGems
1.3.5.

== Examples

=== Defining Your Isolated Environment

It's pretty easy: <tt>gem</tt> is similar to RubyGems' method of the
same name. Version specifiers are optional.

    require "rubygems"
    require "isolate"

    Isolate.gems "vendor/isolated" do
      gem "johnson", "~> 1.1" # or maybe...
      gem "jbarnette-johnson"
    end

At the end of the <tt>Isolate.gems</tt> block, you're completely
isolated. <tt>GEM_PATH</tt> and <tt>GEM_HOME</tt> are set, and all
your specified gems have been activated.

=== Conditionals

Sometimes different sets of gems are appropriate at different
times. Isolate allows you to restrict gems by 'environment' (which is
really just a string passed in when things are activated).

    Isolate.gems "vendor/isolated" do
      gem "intercession"

      environment :test, :cucumber do
        gem "mocha"
      end
    end

Unsurprisingly, the <tt>mocha</tt> gem will only be activated in the
<tt>test</tt> and <tt>cucumber</tt> environments. See the Rails
example below for an example of how to use <tt>RAILS_ENV</tt> to set
your environment.

=== Options

Any trailing hash args to <tt>gem</tt> are passed to
<tt>Gem::DependencyInstaller</tt> as options. There are two special
exceptions, <tt>:source</tt> and <tt>:args</tt>.

    # explicitly specify gem source
    gem "jbarnette-johnson", :source => "http://gems.github.com"

    # pass gem install args (the part after the '--')
    gem "pg", :args => "ARCHFLAGS='-arch x86_64'"

=== Installing Isolated Gems

By default, Isolate will install your gems automatically. You can pass
<tt>:install</tt> and <tt>:verbose</tt> options to control things:

    # install, but quietly
    Isolate.gems "vendor/isolated" :verbose => false do
      ...
    end

    # don't install
    Isolate.gems "vendor/isolated", :install => false do
      ...
    end

=== A Rails Example

Here's a quick example (extracted from a real project) of how to use
Isolate with Rails. This project doesn't use vendored Rails, and
doesn't want to depend on any system gems (except isolate, of course).

Gem dependencies are defined in <tt>config/preinitializer.rb</tt>. If
you want, you could just as easily put them in
<tt>config/{gems,deps,whatever}.rb</tt>, just make sure it's loaded in
the preinitializer:

    require "rubygems"
    require "isolate"

    Isolate.gems "vendor/isolated" do
      gem "rails", "= 2.2.2"

      # async emails!
      gem "ar_mailer", "~> 1.3", '>= 1.3.3'

      # Facebook integration
      gem "facebooker", ">= 1.0.31"

      # Google contacts integration
      gem "gmail_contacts", "~> 1.7"

      # View templates
      gem "haml", "~> 2.0"

      # Session as model
      gem "intercession", "~> 1.0"

      # XML/HTML parsing in Facebooker and tests
      gem "nokogiri", ">= 1.2.3"

      # Twitter authentication
      gem "oauth", "~> 0.3"

      environment :development, :test do
        gem "modelizer" # easy model factories
        gem "sqlite3-ruby" # database support
        gem "vlad"         # deployment
        gem "webrat"       # integration tests
      end

      environment :cucumber do
        gem "cucumber" # stories!
      end
    end

Since this is in the preinitializer, Isolate will install and activate
the fundamental gems before Rails loads.

This is early enough in Rails' lifecycle that <tt>RAILS_ENV</tt> isn't
set, so we need a way to activate gems for the current
environment. Let's add one line to <tt>config/environment.rb</tt>,
right below where <tt>boot.rb</tt> is required:

    require File.join(File.dirname(__FILE__), 'boot')
    Isolate.activate RAILS_ENV

Pow. Isolated!

=== A Library Example

If you're using Hoe[http://blog.zenspider.com/hoe] to manage your
library, you can use Isolate's Hoe plugin to automatically install
your lib's development, runtime, and test dependencies without
polluting your system RubyGems, and run your tests/specs in total
isolation.

Assuming you have a recent Hoe and isolate's installed, it's as simple
as putting:

    Hoe.plugin :isolate

before the <tt>Hoe.spec</tt> call in your <tt>Rakefile</tt>.

If you're not using Hoe, you can just do a regular
<tt>Isolate.gems</tt> block at the top of your Rakefile.

== Installation

    $ gem install isolate

== License

Copyright 2009 John Barnette, et al. (jbarnette@rubyforge.org)

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.