[GR-2243] Update documentation about Java/host interoperability with native images

* Fixes #1853.

Author: eregon

README.md

@@ -60,7 +60,7 @@ 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, 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
+VisualVM, it is less convenient for Java interoperability, and *peak performance may be
 lower than on the JVM*. The native configuration is used by default, but you
 can also request it using `--native`. To use polyglot programming with the
 *native* configuration, you need to use the `--polyglot` flag. To check you
@@ -69,7 +69,7 @@ are using the *native* configuration, `ruby --version` should mention
 
 TruffleRuby can also be used in the *JVM* configuration, where it runs as a
 normal Java application on the JVM, as any other Java application would. The
-advantage of the JVM configuration is that you can use Java interoperability,
+advantage of the JVM configuration is that you can use Java interoperability easily,
 and *peak performance may be higher than the native configuration*. The
 disadvantage of the JVM configuration is that it takes much longer to start and
 to get fast, and may use more memory. The JVM configuration is requested using

doc/contributor/native-image.md

@@ -100,8 +100,11 @@ 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.
+* Java interoperability works in the native configuration but requires more setup.
+  First, only for classes loaded in the image can be accessed.
+  You can add more classes by compiling a native image including TruffleRuby.
+  See https://www.graalvm.org/docs/reference-manual/embed/#build-native-images-from-polyglot-applications for details.
 
 So the native version may not be appropriate for all uses.
 

doc/user/compatibility.md

@@ -291,15 +291,15 @@ extensions to Ruby.
 
 ## Features not yet supported in native configuration
 
-* 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 GraalVM Native Image Generator's limited support for
-runtime reflection.
+par with one another.
+
+Java interoperability works in the native configuration but requires more setup.
+First, only for classes loaded in the image can be accessed.
+You can add more classes by compiling a native image including TruffleRuby.
+See https://www.graalvm.org/docs/reference-manual/embed/#build-native-images-from-polyglot-applications for details.
 
 ## Spec Completeness
 

doc/user/deploying.md

@@ -18,14 +18,14 @@ JVM installed on your system to use it. The advantage of the native
 configuration is that it starts about as fast as MRI, it may use less memory,
 and it becomes fast in less time than the *JVM* configuration. 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
+VisualVM, it is less convenient for Java interoperability, and *peak performance may be
 lower than on the JVM*. The native configuration is used by default, but you
 can also request it using `--native`. To use polyglot programming with the
 *native* configuration, you need to use the `--polyglot` flag.
 
 TruffleRuby can also be used in the *JVM* configuration, where it runs as a
 normal Java application on the JVM, as any other Java application would. The
-advantage of the JVM configuration is that you can use Java interoperability, and
+advantage of the JVM configuration is that you can use Java interoperability easily, and
 *peak performance may be higher than the native configuration*. The disadvantage
 of the JVM configuration is that it takes much longer to start and to get fast,
 and may use more memory. The JVM configuration is requested using `--jvm`.

doc/user/polyglot.md

@@ -147,8 +147,11 @@ converted to boolean if possible or considered to be true.
 ## Accessing Java objects
 
 TruffleRuby's Java interop interface is similar to the interface from the
-Nashorn JavaScript implementation, as also implemented by Graal.js. It's only
-available in JVM mode (`--jvm`).
+Nashorn JavaScript implementation, as also implemented by Graal.js.
+
+It is easier to use Java interop in JVM mode (`--jvm`).
+Java interop is also supported in native mode but requires more setup.
+See https://www.graalvm.org/docs/reference-manual/embed/#build-native-images-from-polyglot-applications for details.
 
 `Java.type('name')` returns a Java class object, given a name such as
 `java.lang.Integer` or `int[]`. With the class object, `.new` will create an