# HG changeset patch
# User Doug Simon <doug.simon@oracle.com>
# Date 1378841446 -7200
# Node ID a8132e3fd0d87bc45f16ef7a5ce572c156249b51
# Parent  9652640fae427e8ac84724d9605e9c55e0ca8e05
further improvements to README_GRAAL.txt

diff -r 9652640fae42 -r a8132e3fd0d8 README_GRAAL.txt
--- a/README_GRAAL.txt	Tue Sep 10 21:29:31 2013 +0200
+++ b/README_GRAAL.txt	Tue Sep 10 21:30:46 2013 +0200
@@ -11,11 +11,30 @@
 
 % mx build
 
-This builds the 'product' version of HotSpot with the Graal modifications.
-To build the debug or fastdebug versions:
+There are a number of VM configurations supported by mx which can
+be explicitly specified using the --vm option. However, you'll typically
+want one of these VM configurations:
 
-  mx --vmbuild debug build
-  mx --vmbuild fastdebug build
+1. The 'server' configuration is a standard HotSpot VM that includes the
+   runtime support for Graal but uses the existing compilers for normal
+   compilation (e.g., when the interpreter threshold is hit for a method).
+   Compilation with Graal is only done by explicit requests to the
+   Graal API. This is how Truffle uses Graal.
+   
+2. The 'graal' configuration is a VM where all compilation is performed
+   by Graal and no other compilers are built into the VM binary. This
+   VM will bootstrap Graal itself at startup unless the -XX:-BootstrapGraal
+   VM option is given.   
+
+Unless you use the --vm option with the build command, you will be presented
+with a dialogue to choose one of the above VM configurations for the build
+as well as have the option to make it your default for subsequent commands
+that need a VM specified.
+
+To build the debug or fastdebug builds:
+
+% mx --vmbuild debug build
+% mx --vmbuild fastdebug build
 
 Running Graal
 -------------
@@ -24,47 +43,16 @@
 
 % mx vm ...
 
-To select the fastdebug or debug versions of the VM:
+To select the fastdebug or debug builds of the VM:
 
 % mx --vmbuild fastdebug vm ...
 % mx --vmbuild debug vm ...
 
-Graal has an optional bootstrap step where it compiles itself before
-compiling any application code. This bootstrap step currently takes about 20 seconds
-on a fast x64 machine. It's useful to disable this bootstrap step when running small
-programs with the -XX:-BootstrapGraal options. For example:
-
-% mx vm -XX:-BootstrapGraal ...
-
-
-Other Build Configurations
---------------------------
-
-By default the build commands above create a HotSpot binary where Graal
-is the only compiler. This binary is the Graal VM binary and identifies as
-such with the -version option:
+Other VM Configurations
+-----------------------
 
-% mx vm -XX:-BootstrapGraal -version
-java version "1.7.0_25"
-Java(TM) SE Runtime Environment (build 1.7.0_25-b15)
-OpenJDK 64-Bit Graal VM (build 25.0-b43-internal, mixed mode)
-
-It's also possible to build and execute the standard HotSpot binaries
-using the --vm option:
-
-% mx --vm server build
-% mx --vm server vm -version
-java version "1.7.0_25"
-Java(TM) SE Runtime Environment (build 1.7.0_25-b15)
-OpenJDK 64-Bit Server VM (build 25.0-b43-internal, mixed mode)
-
-These standard binaries still include the code necessary to support use of the
-Graal compiler for explicit compilation requests. However, in this configuration
-the Graal compiler will not service VM issued compilation requests (e.g., upon
-counter overflow in the interpreter).
-
-To build and run a HotSpot binary that completely omits all VM support for Graal,
-use the following as a guide:
+In addition to the VM configurations described above, there are
+VM configurations that omit all VM support for Graal:
 
 % mx --vm server-nograal build
 % mx --vm server-nograal vm -version
@@ -78,3 +66,5 @@
 Java(TM) SE Runtime Environment (build 1.7.0_25-b15)
 OpenJDK 64-Bit Cleint VM (build 25.0-b43-internal, mixed mode)
 
+These configurations aim to match as closely as possible the
+VM(s) included in the OpenJDK binaries one can download.
\ No newline at end of file