MagLev / maglev

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 ruby and rake to use during installation
• 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. If you install using RVM (rvm.beginrescueend.com), it will use ~/.rvm or the rvm_path specified in your .rvmrc.

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 02-Feb-10 is 22816. Check for later versions on Twitter or the MagLev Discussion Google Group.

First, download and unzip the installer from maglev.gemstone.com/files/MagLev-installer.zip

The first time you install MagLev use installMaglev.sh. 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 upgradeMaglev.sh. It skips the checks run by installMaglev.sh. You must supply the version number as a parameter, e.g.

  ./installMaglev.sh 22816
  ./upgradeMaglev.sh 22816

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://github.com/MagLev/maglev.git

and cd to the resulting directory.

To use MagLev, you need to run install.sh at least once. After that, everytime you do a ‘git pull’ you need to run update.sh 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 update.sh. 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.

Installing under RVM

RVM is useful if you want to compare behavior of various Ruby implementations or versions of MagLev. Install using rvm install maglev. See rvm.beginrescueend.com for details of using RVM.

RVM will automatically start a MagLev server when you rvm use maglev. That server is left running if you rvm use any_other_Ruby. To stop your MagLev server run rvm use maglev; maglev stop.

Note: maglev stop will only stop the version of MagLev currently in use. If you’re using more than one, you’ll have to maglev stop each of them — e.g. rvm use maglev-22816; maglev stop; rvm use maglev-head; maglev stop.

ProTip: To kill all the MagLev servers rather than shut them down gracefully, run ps -ef | grep /sys/stoned and kill the stoned processes that show up. It takes a short time before they shut down, as they do a bit of cleanup first.

Note: When running rake from MagLev, you cannot perform tasks which affect MagLev itself, like rake maglev:stop. You have to use the bin/maglev shell script instead.

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. If you have RVM installed, you can run rvm use maglev.

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. You shouldn’t install the rake gem 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 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
    where
    stack
    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.