root / trunk / README

 FREAKY FREAKY SANDBOX.
_______________________________________________________________________________

 This is a hack.  I know it's a hack and I'm aware that it's a hack.  It's not
 yet a tried and well-worn practice.  It's not old hand, right?  Not old hand.

 But it is pretty fantastic.  I'm really surprised how well it works.  Yeah
 let's talk about that.
_______________________________________________________________________________
-------------------------------------------------------------------------------

 INSTALLING THE FREAKY FREAKY SANDBOX.
_______________________________________________________________________________

 To run the freaky freaky sandbox, you need a patched Ruby 1.8.5 and the sandbox
 extension.

 There is one patch, which adds a Thread#kill! for stopping unending sandboxes.
 Also, the patch will manage swapping sandboxes in accord with the Ruby's
 scheduler.  Lastly, it opens up the syserr_tbl, which allows the sandbox to
 have its own set of OS exceptions.

 See the patch/ directory of this release.

  $ cd ruby-1.8.5
  $ patch -p1 < ruby-1.8.5-sandbox_needs.patch
  $ make
  # make install

 Once Ruby is patched, come back to this directory and install the extension.

  # ruby setup.rb

 There are no gems for Sandbox.  This is not without reason!  Sandbox _must_ be
 loaded before RubyGems.  So it is infeasible to distribute it as a gem for now.
_______________________________________________________________________________
-------------------------------------------------------------------------------

 RUNNING TRUSTED CODE.
_______________________________________________________________________________

 Believe it or not, FreakyFreaky is really handy for running your own apps.
 Some examples:

 * Start small interpreters which can periodically be dumped and restarted.
   (Long-running apps can self-upgrade!)

 * Load multiple different versions of a library.  Maybe you're converting
   an old version to a new version.

 * Run multiple Rails apps.  (Rails is a classic example of a crowded namespace
   where two apps' set of modules cannot coexist.)
 
 For trusted code, you want to use a plain Sandbox that let's you pass code
 back and forth.

   s = Sandbox.new

 Creates a new symbol table and copies all the boilerplate code from the main
 interpreter.  (So be sure you haven't removed any methods from the main
 interpreter!)

   s.eval "5 + 6"
   #=> 11

 Use eval to execute scripts inside the sandbox.  With the plain Sandbox,
 you'll get back the actual objects from the sandbox's world.  See, it's
 okay to share objects between trusted code.  So, why not?

   s.eval %{
     class Book
       attr_accessor :author, :title
       def initialize(a, t)
         @author, @title = a, t
       end
     end
   }

   book = s.eval("book = Book.new('Stanislaw Lem', 'The Star Diaries')")
     #=> #<Book ...>

 The Book object you get back is the same which was created in the sandbox.
 And you can certainly access and redefine the sandboxed Book class as well.

   Book = s.eval("Book")
   class Book
     def year
       1970
     end
   end

   s.eval("book.year")
     #=> 1970

 If you do a lot of back and forth with the sandboxes, it can be tough to keep
 track of what classes are in the sandbox and what's in main.  Especially since
 most sandboxes start to get a bit behind method-wise.