GemStone Maglev Ruby Repository
Ruby Other
Pull request Compare This branch is 7 commits ahead, 4009 commits behind MagLev:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
benchmark @ 1be60e3


MagLev Alpha

Minimum Requirements

  • 64-bit hardware. There are no plans for a 32-bit version.

  • 64-bit Linux, Mac OS X, or Solaris X86 operating system

  • a version of rake installed in /usr/bin/rake

  • root access so you can increase default shared memory settings (only during initial install)

Getting started

Create a MagLev directory. Its name doesn't matter. Put the installer or git clone there. It needs to be writable, as files are put there by installations and updates.

Installing the zipped version

We recommend this version unless you want to participate in MagLev development or want access to the absolute latest code. It changes more slowly than the github version, and it has undergone more testing.

You'll need to know a version number to install. The MagLev Alpha version on 10-Dec-09 is 22635. Check for later versions on Twitter or the MagLev Discussion Google Group.

First, download and unzip the installer from

The first time you install MagLev use It checks that your hardware will run MagLev, and sets appropriate shared memory settings. It's safe to run multiple times, it won't overwrite things it's already done. Subsequently, use It skips the checks run by You must supply the version number as a parameter, e.g.

./ 22635
./ 22635

The installer is somewhat verbose. That's so you can more easily debug installation problems.

Note: This installer/updater creates a separate (sub)directory for each new version of MagLev. Reverting to an older version is as simple as stopping MagLev, changing $MAGLEV_HOME to point to the prior version, and restarting.

Installing from the github repository

This version is best for MagLev contributors and for developers who want to live on the bleeding edge or use git functionality. It can be less stable than the zipped version.

First, clone the MagLev github repository, i.e.

git clone git://

and cd to the resulting directory.

To use MagLev, you need to run at least once. After that, everytime you do a 'git pull' you need to run to ensure you have the corresponding GemStone 3.x binaries. Otherwise, you might get version skew that prevents MagLev from running correctly. I'll tweet about any 'git only' updates, but if you're more than one update behind you still might need to run You don't need to know a version number to install. The installer/updater figures that out from the version.txt file.

You'll have all the functionality of git, but unless you create a new clone for each release, you may be unable to revert to an earlier version. Why? The install/upgrade script creates a new copy of the MagLev data repository including persistent kernel code. The scripts make one level of backup, but we won't be providing migration scripts during Alpha.

Running MagLev

Start the server by either running rake maglev:start from within your $MAGLEV_HOME directory tree, or running maglev start (which counts on $MAGLEV_HOME being set and $MAGLEV_HOME/bin being in your $PATH.

Useful commands include maglev-irb, maglev-ruby, and maglev-gem. MagLev code is in src, examples are in examples, some docs are in html. You'll find a few README files, too.

Stop the server by running rake maglev:stop or maglev stop.

Tips and troubleshooting

  • rake needs to be in your PATH. It's needed to install and to bootstrap MagLev. The MagLev installer expects rake to be in /usr/bin/rake. You shouldn't install rake into MagLev – it won't work.

  • You need to start MagLev before running “maglev-ruby”, “maglev-gem”, or “maglev-irb”. Either “rake maglev:start” or “maglev start” will do that. While not strictly required it's better to stop MagLev before turning off your machine. i.e. “rake maglev:stop” or “maglev stop”.

  • If you get this error when running maglev:start:

    rake aborted!
    Don't know how to build task 'maglev:start'

    it indicates /usr/bin/rake wasn't found during installation and so important steps were skipped. You can re-run the installer, or try this:

    rake stone:create[maglev]
  • if you get an error starting maglev-irb, try “maglev-irb -f”. It's likely something in your .irbrc is breaking maglev-irb.

  • RubyGems 1.3.5 is preinstalled. The command to use it is “maglev-gem”. For example: “maglev-gem install sinatra” will install both Sinatra and Rack into MagLev. Gems that use C extensions won't work. Many other gems may install, but not work correctly at this time. :-(

  • If you get an error like this when running “maglev-gem”:

    line 8: require: command not found

    it indicates your system thinks “maglev-gem” is a shell script. The first line of “maglev-gem” should be:

    #!/usr/bin/env maglev-ruby

    If it's not, either reinstall MagLev or correct the first line of bin/maglev-gem

  • If you get a “NoMethodError” such as the following:

        Coercion error: nil.to_str => String failed:
    (NoMethodError: undefined method `to_str' for )

    It will help us debug it if you send a stack trace. Setting “-d” in the environment variable MAGLEV_OPTS should leave you at a topaz prompt when you hit the error. Then execute the following sequence of commands. Be aware you may see a lot of output, which will also wind up in the file “stack.out”

    output push stack.out
    output pop

    Other useful MAGLEV_OPTS switches include “traceload”, i.e.:

    export MAGLEV_OPTS="-d -MtraceLoad"

    for more info on MAGLEV_OPTS type “maglev-ruby -h”

  • MagLev has ACID transactions. To share persistent objects between two running VM's you need to make use of Maglev.commit_transaction and Maglev.abort_transaction. Read the persistence-api docs for more info.