From 470065927d4b4abfb23b8a98178a87885b4f7bee Mon Sep 17 00:00:00 2001 From: jnthn Date: Fri, 2 May 2014 21:51:30 +0200 Subject: Update README for multi-backend Star. --- README | 94 +++++++++++++++++++++++++++++++++++++++++++++--------------------- 1 file 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/ -- cgit v1.1