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)
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.
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 22624 ./upgradeMaglev.sh 22624
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.
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:
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:
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.