Update README for multi-backend Star.

1 files changed, 65 insertions, 29 deletions

diff --git a/README b/README
index de5c135..df4c43c 100644
--- a/README
+++ b/README
@@ -8,24 +8,48 @@ License Information
 -------------------
 Rakudo Star is distributed under the terms of the Artistic License 2.0.
 This distribution contains software collected from other sources; see the
-individual source subdirectories (in parrot/, rakudo/, and modules/) for
-copyright and licensing information of those components.
+individual source subdirectories (in parrot/, rakudo/, MoarVM/ and modules/)
+for copyright and licensing information of those components.
 
-Build Prerequisites
--------------------
-To build Rakudo Star you need at least a C compiler, a 'make' utility,
-and Perl 5.9.0 or newer.  You probably also want a machine with a fair
-amount of memory available: 1GB is known to be too small for building 
-Rakudo, while 2GB is generally known to be sufficient.
+Overview
+--------
+The Rakudo Perl 6 compiler can target MoarVM, the JVM, and the Parrot
+Virtual Machine. Rakudo Star fully supports MoarVM and Parrot; not all
+modules work on the JVM at present. You can choose to build and install
+Rakudo for one or more of these virtual machines at configure time.
+
+
+Build Prerequisites for Rakudo on MoarVM
+----------------------------------------
+To build Rakudo Star on MoarVM, you need at least a 'make' utility, a C
+compiler, and Perl 5.10.0 or newer. Building Rakudo on MoarVM needs a
+machine with a gigabyte of memory; for a 32-bit build, you may get by
+with less.
 
-In order to fully support Unicode on the parrot backend, you'll also
-want to have the
-ICU library installed (http://site.icu-project.org/).
-Rakudo can run without ICU, but some Unicode-related features
-will not work properly.
 
-For the JVM Backend, you also need the Java Development kit, for example
-openjdk-7 or the Oracle JDK.
+Build Prerequisites for Rakudo on the JVM
+-----------------------------------------
+To build Rakudo Star on the JVM, you need at least a 'make' utility,
+both 'java' and 'javac' available in your path, and Perl 5.9.0 or
+newer. The 'java' and 'javac' are obtained by installing a Java
+Development kit, for example openjdk-7 or the Oracle JDK.
+
+The newer the JDK you have the better; due to bugs in the
+invokedynamic instruction in early JDK7 releases, JDK7 update 21 or
+above is suggested. JDK8, if available, is better still. The build
+can complete within a gigabyte of memory.
+
+
+Build Prerequisites for Rakudo on Parrot
+----------------------------------------
+To build Rakudo Star on Parrot you need at least a 'make' utility, a C
+compiler, and Perl 5.9.0 or newer. You probably also want a machine with
+a fair amount of memory available: 1GB is known to be too small for
+building Rakudo on Parrot, while 2GB is generally known to be sufficient.
+
+In order to fully support Unicode, you'll also want to have the ICU
+library installed (http://site.icu-project.org/). Rakudo can run
+without ICU, but some Unicode-related features will not work properly.
 
 On Debian GNU/Linux or Ubuntu Linux, the necessary components
 for building Rakudo can be installed via the command
@@ -40,11 +64,33 @@ On RedHat/Fedora/CentOS, the components can be installed with
     yum install libicu-devel readline-devel
 
 
+Configuring Rakudo Star
+-----------------------
+The easiest way to build Rakudo Star for a particular backend is:
+
+    $ perl Configure.pl --backend=moar --gen-moar       # MoarVM
+    $ perl Configure.pl --backend=parrot --gen-parrot   # Parrot
+    $ perl Configure.pl --backend=jvm --gen-nqp         # JVM
+
+You can also build for all backends:
+
+    $ perl Configure.pl --backend=parrot,jvm,moar --gen-parrot --gen-moar
+
+Note that --gen-parrot automatically builds a Parrot for you, and
+--gen-moar does likewise. Both imply --gen-nqp, which builds NQP, a
+subset of Perl 6 that is used to implemented Rakudo.
+
+Configure this way, one or more Perl 6 executable and selected Perl
+6 modules will be installed into the install/ subdirectory, which
+resides inside the source archive directory. Running make install
+will *not* install anything into /usr/local. If you want to change
+this behavior, specify the install prefix using the --prefix option.
+
+
 Building Rakudo Star
 --------------------
-The basic steps to build Rakudo Star are:
+After configuration, build Rakudo Star with:
 
-    $ perl Configure.pl --gen-parrot --gen-moar
     $ make
     $ make install
 
@@ -54,24 +100,13 @@ a symlink to help Parrot find the ICU library:
 
     # ln -s /usr/include/x86_64-linux-gnu/unicode /usr/include/unicode
 
-This will build a Perl 6 executable and install selected
-Perl 6 modules into the install/ subdirectory, which resides
-inside the source archive directory. Running make install
-will *not* install anything into /usr/local. Programs can
-then be run directly using a command like:
+Once Rakudo Star is installed, you can run Perl 6 programs by doing:
 
     $ ./perl6 hello.pl
 
 Programs can also be run by adding the "install/bin" directory
 to your PATH environment variable.
 
-The "--gen-parrot" option above tells Configure.pl to automatically
-build and install the version of Parrot that is distributed with 
-Rakudo Star. Likewise "--gen-moar" builds the MoarVM distributed with
-Rakudo Star. The "--prefix=" option can be provided to Configure.pl
-to change the location of the install directory. Note that Rakudo based
-on Parrot can only be installed to the same prefix as Parrot.
-
 If the Rakudo compiler is invoked without an explicit script to
 run, it enters a small interactive mode that allows Perl 6 statements
 to be executed from the command line.
@@ -91,6 +126,7 @@ Running "make modules-test" will run the test suites of any installed
 modules.  The modules currently have to be installed (via 'make install' 
 or 'make modules-install') before the tests can be run.
 
+
 Release information
 -------------------
 Information about the current release is placed in the docs/