Update terminology

Author: chrisseaton

README.md

@@ -1,7 +1,8 @@
 ![TruffleRuby logo](logo/png/truffleruby_logo_horizontal_medium.png)
 
-A high performance implementation of the Ruby programming language. Built on
-[GraalVM](http://graalvm.org/) by [Oracle Labs](https://labs.oracle.com).
+TruffleRuby is the [GraalVM](http://graalvm.org/) high-performance implementation
+of the [Ruby programming language](https://www.ruby-lang.org/en/) built by
+[Oracle Labs](https://labs.oracle.com).
 
 ## Getting started
 
@@ -61,7 +62,7 @@ TruffleRuby by default runs in the *native*
 configuration. In this configuration, TruffleRuby is ahead-of-time compiled to a
 standalone native executable. This means that you don't need a JVM installed on
 your system to use it. The advantage of the native configuration is that it
-[starts about as fast as MRI](doc/contributor/svm.md), it may use less memory,
+[starts about as fast as MRI](doc/contributor/native-image.md), it may use less memory,
 and it becomes fast in less time. The disadvantage of the native configuration
 is that you can't use Java tools like VisualVM, you can't use Java
 interoperability, and *peak performance may be lower than on the JVM*. The
@@ -89,7 +90,7 @@ At runtime you can tell if you are using the native configuration using
 
 You won't encounter it when using TruffleRuby from the GraalVM, but there is
 also another configuration which is TruffleRuby running on the JVM but with the
-Graal compiler not available. This configuration will have much lower
+GraalVM Compiler not available. This configuration will have much lower
 performance and should normally only be used for development. `ruby --version`
 will mention `Interpreter` for this configuration.
 

doc/contributor/benchmarking.md

@@ -1,6 +1,6 @@
 # Benchmarking TruffleRuby
 
-## Benchmarking with Graal
+## Benchmarking with the GraalVM Compiler
 
 ```
 $ jt benchmark bench/classic/mandelbrot.rb --simple
@@ -9,9 +9,9 @@ $ jt benchmark bench/classic/mandelbrot.rb --simple
 Output is iterations per second, printed roughly every second (more frequently
 for the first few iterations).
 
-# Benchmarking without Graal
+# Benchmarking without the GraalVM Compiler
 
-You can turn off Graal if you want using `--no-graal`.
+You can turn off the GraalVM Compiler if you want using `--no-graal`.
 
 ```
 $ jt benchmark --no-graal bench/classic/mandelbrot.rb --simple

doc/contributor/building-graal.md

@@ -1,9 +1,10 @@
-# Building Graal
+# Building the GraalVM Compiler
 
-If you want to build Graal from scratch to test running with Graal when
-developing TruffleRuby, or possibly to modify Graal or Truffle, or to use
-developer tools that come with Graal such as the Ideal Graph Visualizer, then
-you should install Graal locally.
+If you want to build the Truffle Language Implementation Framework and the
+GraalVM Compiler and other dependencies from scratch to test running with them
+when developing TruffleRuby, or possibly to modify them, or to use developer
+tools that come with Graal such as the Ideal Graph Visualizer, then you should
+install Graal locally.
 
 ## Installing Graal with jt
 
@@ -22,10 +23,10 @@ $ jt ruby --graal ...
 
 ## Building Graal manually
 
-If you want to build Graal by yourself, follow the instructions in the Graal
-repository.
+If you want to build the GraalVM Compiler by yourself, follow the instructions
+in the Graal repository.
 
-https://github.com/graalvm/graal
+https://github.com/oracle/graal
 
 You can then set the `GRAAL_HOME` environment variable to the location of the
 `compiler` directory inside the `graal` repository and use `jt` to run

doc/contributor/interop.md

@@ -1,9 +1,10 @@
 # Truffle Interop
 
-TruffleRuby supports standard Truffle API interop messages. This document
-explains what it does when it receives them, how to get it to explicitly send
-them, how to get it to send them using more idiomatic Ruby, and how what
-messages it sends for normal Ruby operations on foreign objects.
+TruffleRuby supports the standard interop message system of the Truffle
+Language Implementation Framework. This document explains what it does when it
+receives them, how to get it to explicitly send them, how to get it to send
+them using more idiomatic Ruby, and how what messages it sends for normal Ruby
+operations on foreign objects.
 
 This document only explains how TruffleRuby uses messages. The messages
 themselves are explained in the

doc/contributor/native-image.md

@@ -0,0 +1,107 @@
+# Using TruffleRuby with GraalVM Native Images
+
+The GraalVM Native Image Generator is a closed-world analysis ahead-of-time
+compiler for Java, and an implementation of parts of a JVM.
+
+We use Native Images to ahead-of-time compile TruffleRuby and the
+GraalVM Compiler to a single, statically-linked native binary
+executable, that has no dependency on a JVM, and does not link to any JVM
+libraries. The technique is more sophisticated than just appending a JAR as a
+resource in a copy of the JVM - only parts of the JVM which are needed are
+included and they are specialised for how TruffleRuby uses them. There is no
+Java bytecode - only compiled native machine code and compiler graphs for
+dynamic compilation.
+
+Note that the GraalVM Native Image Generator is not an ahead-of time compiler
+for your Ruby program. It only ahead-of-time compiles the Java code that
+implements the TruffleRuby interpreter and the GraalVM Compiler.
+
+The GraalVM Native Image Generator itself, like the GraalVM Compiler and
+TruffleRuby, is implemented in Java.
+
+https://youtu.be/FJY96_6Y3a4?t=10023
+
+More information can be found in Kevin Menard's
+[blog post](http://nirvdrum.com/2017/02/15/truffleruby-on-the-substrate-vm.html).
+
+The TruffleRuby that is distributed in the
+[GraalVM](../user/installing-graalvm.md) by default uses a version compiled
+using the Native Image Generator - this is to prioritise fast start-up and
+warm-up time for shorter running commands and benchmarks.
+
+```bash
+$ cd graalvm
+$ otool -L jre/bin/ruby
+jre/bin/ruby:
+	/System/Library/Frameworks/CoreFoundation.framework/Versions/A/CoreFoundation (compatibility version 150.0.0, current version 1348.28.0)
+	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1238.0.0)
+	/usr/lib/libz.1.dylib (compatibility version 1.0.0, current version 1.2.8)
+
+$ du -h jre/bin/ruby
+200M	jre/bin/ruby
+```
+
+The Native Image version of TruffleRuby has better startup performance and lower memory
+footprint than JRuby, Rubinius and TruffleRuby on the JVM, and similar or better
+startup performance than MRI.
+
+| Implementation     | Real Time (s) | Max RSS (MB) |
+| ------------------ | ------------: | -----------: |
+| TruffleRuby Native | 0.025         |  65          |
+| MRI 2.6.2          | 0.048         |  14          |
+| Rubinius 3.107     | 0.150         |  78          |
+| JRuby 9.2.7.0      | 1.357         | 160          |
+| TruffleRuby JVM    | 1.787         | 456          |
+
+Run on Linux with an Intel(R) Core(TM) i7-7700HQ CPU @ 2.80GHz with a SSD.
+
+```bash
+$ cd graalvm-ce-1.0.0-rc15
+$ bin/ruby -e 'puts "Hello"'       # TruffleRuby on the SVM
+$ bin/ruby --jvm -e 'puts "Hello"' # TruffleRuby on the JVM
+
+$ chruby ruby-2.6.2
+$ ruby -e 'puts "Hello"'
+
+$ chruby rbx-3.107
+$ rbx -e 'puts "Hello"'
+
+$ chruby jruby-9.2.7.0
+$ jruby -e 'puts "Hello"'
+```
+
+The real time and the maximum resident set size are measured with a custom
+[C program](https://gist.github.com/eregon/cbf6c89451ecf815463c00aef9745837)
+as `time` cannot measure real time in milliseconds and max RSS.
+Each command is run 10 times and the average is reported.
+`clock_gettime(CLOCK_MONOTONIC)` is used to measure time and `getrusage()` to
+measure max RSS.
+
+There is no need to do so, but you can actually also compile your own copy of
+the Native Image version of TruffleRuby using a tool distributed as part of GraalVM and
+the Java version of TruffleRuby from GraalVM.
+
+```
+$ native-image -H:Name=native-ruby --language:ruby
+```
+
+`native-ruby` is the output file name.
+
+You can build a native build of TruffleRuby using the Native Image Tool from a
+source distribution using:
+
+```
+$ jt build native
+```
+
+The disadvantages of the Native Image version of TruffleRuby are:
+
+* It has lower peak performance, as the GC is simpler and some optimisations
+  such as compressed ordinary object pointers (OOPS) are not yet available.
+* You can't use Java interoperability.
+* You can't use standard Java tools like VisualVM.
+
+So the native version may not be appropriate for all uses.
+
+For the highest performance for long-running processes you want to use the
+JVM version of TruffleRuby, using `--jvm`.

doc/contributor/pre-initialization.md

@@ -1,8 +1,9 @@
 # Context Pre-Initialization
 
-TruffleRuby supports context pre-initialization with SubstrateVM.
+TruffleRuby supports context pre-initialization with the GraalVM Native Image
+Generator.
 
-Context pre-initialization is enabled in Truffle by setting a Java property:
+Context pre-initialization is enabled by setting this Java property:
 
 ```
 -Dpolyglot.engine.PreinitializeContexts=ruby

doc/contributor/profiling.md

@@ -2,12 +2,11 @@
 
 There is no shortage of tools for profiling TruffleRuby. When running in JVM
 mode, we can use standard JVM tooling, such as VisualVM and Java Flight
-Recorder. When run as a native image we can use callgrind from the Valgrind
-tool suite and other system tools, such as strace. As an instrumented Truffle
-language, we can also use Truffle's profiling capabilities and other [user
-tools](../user/tools.md). For a broad enough definition of profiling, we can
-also use the Ideal Graph Visualizer (IGV) and C1 Visualizer to inspect Graal's
-output.
+Recorder. When run as a Native Image we can use callgrind from the Valgrind
+tool suite and other system tools, such as strace. As a GraalVM language we
+can also use other GraalVM [tools](../user/tools.md). For a broad enough
+definition of profiling, we can also use the Ideal Graph Visualizer (IGV) and
+C1 Visualizer to inspect Graal's output.
 
 This document is less about how to use each tool and more about suggestions for extracting
 the most useful information from the tools, assuming basic knowledge of their usage.
@@ -76,4 +75,4 @@ might have a different image manipulation application configured as the default
 for SVG files. While loading the file in such an application make render a graph, it likely
 will not handle the interactive components of the flame graph. Firefox may work as well,
 but Chromium-based browsers seem to have better support and performance for the flame graph
-files as of this writing (Dec. 2018).
+files as of this writing (Dec. 2018).

doc/contributor/svm.md

@@ -11,7 +11,7 @@
 require 'readline'
 
 unless TruffleRuby.graal?
-  puts 'You need Graal to run this'
+  puts 'You need the GraalVM Compiler to run this'
   exit
 end
 

doc/samples/can-we-fold-yet.rb

@@ -46,8 +46,10 @@ as their semantics fundamentally do not match the technology that we are using.
 #### Fork
 
 You cannot `fork` the TruffleRuby interpreter. The feature is unlikely to ever
-be supported when running on the JVM but could be supported in the future on
-the SVM. The correct and portable way to test if `fork` is available is:
+be supported when running on the JVM but could be supported in the future in
+the native configuration. The correct and portable way to test if `fork` is
+available is:
+
 ```ruby
 Process.respond_to?(:fork)
 ```
@@ -250,7 +252,7 @@ multiple languages, including Java, instead.
 #### Java to Ruby interop
 
 Calling Ruby code from Java is supported by the
-[Graal-SDK polyglot API](http://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/package-summary.html).
+[GraalVM polyglot API](http://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/package-summary.html).
 
 #### Java extensions
 
@@ -267,12 +269,13 @@ extensions to Ruby.
 
 * Java interop
 
-Running TruffleRuby in the native configuration is mostly the same as running on
-the JVM. There are differences in resource management, as both VMs use different
-garbage collectors. But, functionality-wise, they are essentially on par with
-one another. The big difference is support for Java interop, which currently
-relies on reflection. TruffleRuby's implementation of Java interop does not work
-with the SVM's limited support for runtime reflection.
+Running TruffleRuby in the native configuration is mostly the same as running
+on the JVM. There are differences in resource management, as both VMs use
+different garbage collectors. But, functionality-wise, they are essentially on
+par with one another. The big difference is support for Java interop, which
+currently relies on reflection. TruffleRuby's implementation of Java interop
+does not work with the GraalVM Native Image Generator's limited support for
+runtime reflection.
 
 ## Spec Completeness