groovy-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jwagenleit...@apache.org
Subject [1/2] groovy git commit: Clarify documentation around indy (closes #530)
Date Sun, 07 May 2017 05:34:31 GMT
Repository: groovy
Updated Branches:
  refs/heads/GROOVY_2_4_X c26a4ee30 -> c3220ee5e


Clarify documentation around indy (closes #530)


Project: http://git-wip-us.apache.org/repos/asf/groovy/repo
Commit: http://git-wip-us.apache.org/repos/asf/groovy/commit/188cc2d4
Tree: http://git-wip-us.apache.org/repos/asf/groovy/tree/188cc2d4
Diff: http://git-wip-us.apache.org/repos/asf/groovy/diff/188cc2d4

Branch: refs/heads/GROOVY_2_4_X
Commit: 188cc2d4de33e35be23b27bbf2ec66739d4219b4
Parents: c26a4ee
Author: John Wagenleitner <jwagenleitner@apache.org>
Authored: Sun Apr 30 11:07:34 2017 -0700
Committer: John Wagenleitner <jwagenleitner@apache.org>
Committed: Sat May 6 22:12:39 2017 -0700

----------------------------------------------------------------------
 src/spec/doc/invokedynamic-support.adoc | 35 +++++++++++++++++-----------
 1 file changed, 22 insertions(+), 13 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/groovy/blob/188cc2d4/src/spec/doc/invokedynamic-support.adoc
----------------------------------------------------------------------
diff --git a/src/spec/doc/invokedynamic-support.adoc b/src/spec/doc/invokedynamic-support.adoc
index 7c3314a..403cfd0 100644
--- a/src/spec/doc/invokedynamic-support.adoc
+++ b/src/spec/doc/invokedynamic-support.adoc
@@ -24,12 +24,11 @@
 
 == Foreword
 
-Since Groovy 2.0, we added support for the JVM http://docs.oracle.com/javase/7/docs/technotes/guides/vm/multiple-language-support.html#invokedynamic[invokedynamic]
instruction. This instruction is supported since Java 7 and is a new bytecode instruction
in the JVM that allows easier implementation of dynamic languages. This instruction will also
be used internally, by the JVM, for the lambda support in Java 8.
+Since Groovy 2.0, support was added for the JVM http://docs.oracle.com/javase/7/docs/technotes/guides/vm/multiple-language-support.html#invokedynamic[invokedynamic]
instruction. This instruction is supported since Java 7 and is a new bytecode instruction
in the JVM that allows easier implementation of dynamic languages. This instruction will also
be used internally, by the JVM, for the lambda support in Java 8.
 
 This means that unlike APIs, AST transformations or syntactic sugar, this feature is **not
visible** to the developer or the end user. It is a compilation and runtime feature only.
This means that given two programs written in Groovy, you have the choice to compile it with
or without invokedynamic support. Whatever you choose, it comes with pros and cons:
 
-- classes compiled with invokedynamic can only be used on JDK 1.7+ (without invokedynamic,
Groovy classes are still compatible with JDK 1.5+)
-- call site caching, as implemented in "normal" Groovy is replaced with invokedynamic since
Groovy 2.1
+- classes compiled with invokedynamic can only be used on JDK 1.7+ (without invokedynamic,
Groovy classes are still compatible with JDK 1.6+)
 - it is possible to mix classes compiled with and without invokedynamic in the same project,
as long as you run JDK 1.7+
 - depending on the JVM (even different minor versions of the JVM), you can target close to
Java performance for dynamic Groovy with invokedynamic support activated
 
@@ -39,15 +38,20 @@ This means that unlike APIs, AST transformations or syntactic sugar, this
featur
 
 The Groovy distribution comes with **two** jars:
 
-- groovy-x.y.z.jar : compatible with JDK 1.5+, makes use of call site caching
-- groovy-x-y-z-indy.jar : compatible with JDK 1.7+ only, has invokedynamic support bundled,
old call site caching still possible
+- groovy-x.y.z.jar : compatible with JDK 1.6+, contains Groovy sources compiled with call
site caching
+- groovy-x-y-z-indy.jar : compatible with JDK 1.7+ only, contains Groovy sources compiled
with invokedynamic instructions
 
-The first jar is Groovy compiled without invokedynamic support, while the second one has
invokedynamic support bundled. As Groovy core and the groovy modules are sometimes written
in Groovy, we currently have no choice but issuing two distinct versions of Groovy. This means
that if you pick the "normal" jar, the groovy classes of groovy itself are compiled with call
site caching (1.5+), while if you use the "indy" jar, the groovy classes of groovy itself
are compiled using invokedynamic. This means that the invokedynamic version of Groovy doesn't
make use of the old call site caching mechanism.
+As Groovy core and the Groovy modules are sometimes written in Groovy, we currently have
no choice but to distribute two
+distinct versions of Groovy. This means that if you pick the "normal" jar, the Groovy classes
of Groovy itself are
+compiled with call site caching (1.6+), while if you use the "indy" jar, the Groovy classes
of Groovy itself are
+compiled using invokedynamic.
 
-Both jars contain a fully working groovy implementation. They are mutually exclusive (don't
put both on classpath).
+Both jars contain a fully working Groovy implementation that is capable of compiling user
supplied Groovy sources using either
+invokedynamic or call site caching. The sets of jars are mutually exclusive (don't put both
on classpath) and the key difference between
+them has to do with how the Groovy source files that make up Groovy itself are compiled.
 
 === Command-line and indy
-If you download the distribution and that you use the command line, it's always the "normal"
version of Groovy which is picked up in classpath. This means that whatever command you use
(`groovy`, `groovyc`, `groovysh` or `groovyConsole`), invokedynamic support is not available
out of the box. To use the invokedynamic version, you have to switch the jars manually. The
distribution makes use of the jars in the ++lib++ directory, while the indy jars are available
in the ++indy++ directory. You have three things to do:
+If you download the distribution and use the command line, it's always the "normal" version
of Groovy which is picked up in classpath. This means that whatever command you use (`groovy`,
`groovyc`, `groovysh` or `groovyConsole`), invokedynamic support is not available out of the
box. To use a Groovy distribution that was compiled with invokedynamic for its Groovy sources
you have to switch the jars manually. The distribution makes use of the jars in the ++lib++
directory, while the indy jars are available in the ++indy++ directory. You have three things
to do:
 
 - remove or rename the groovy-*.jar files in the lib directory
 - replace them with the indy version from the indy directory
@@ -60,9 +64,14 @@ Here's a bash script that would do it all at once:
 $ for f in `ls lib/groovy*.jar | cut -d/ -f2`;do k=`basename $f .jar`; mv lib/$k.jar lib/$k.jar.old;
cp indy/$k-indy.jar lib/$k.jar ; done
 ----
 
+== Running groovy script from command line
+
+The usual way to run a script from the command line is by `groovy foo.groovy`, where `foo.groovy`
is the Groovy program
+in source form. To use indy for this you have to use the indy compilation flag, `groovy --indy
foo.groovy`.
+
 == The compilation flag
 
-Independently of the jar version that you use (and after having exchanged the jars as described),
invokedynamic support requires a specific compilation flag (__indy__). If you want to compile
your classes with invokedynamic support, this flag must be set at compile time. The following
tables show you what happens with user compiled classes and groovy core classes depending
on the jar you use and the compilation flag:
+Independently of the jar version that you use (and after having exchanged the jars as described),
invokedynamic support requires a specific compilation flag (__indy__). If you want to compile
your classes with invokedynamic support, this flag must be set at compile time. The following
tables show you what happens with user compiled classes and Groovy core classes depending
on the jar you use and the compilation flag:
 
 [cols="1,1,1" options="header"]
 .user compiled classes
@@ -73,7 +82,7 @@ Independently of the jar version that you use (and after having exchanged
the ja
 
 |normal jar
 |call site caching
-|N/A
+|invokedynamic
 
 |indy jar
 |call site caching
@@ -81,7 +90,7 @@ Independently of the jar version that you use (and after having exchanged
the ja
 |===
 
 [cols="1,1,1" options="header"]
-.core groovy classes
+.core Groovy classes
 |===
 |indy flag
 |**off**
@@ -89,11 +98,11 @@ Independently of the jar version that you use (and after having exchanged
the ja
 
 |normal jar
 |call site caching
-|N/A
+|call site caching
 
 |indy jar
 |invokedynamic
 |invokedynamic
 |===
 
-So even if you use the indy jar, if you don't use the invokedynamic flag at compile time,
then the compiled classes will use the "old" format, meaning they will use the JDK1.5+ classes
without invokedynamic.
\ No newline at end of file
+So even if you use the indy jar, if you don't use the invokedynamic flag at compile time,
then the compiled classes will use the "old" format, meaning they will use the JDK1.6+ classes
without invokedynamic.
\ No newline at end of file


Mime
View raw message