The groovy native launcher is a native program for launching groovy scripts. It compiles to an executable binary file, e.g. groovy.exe on windows.
The native launcher should support any platform and any jdk / jre (>= 1.4). If you find something that is not supported, please post a JIRA enhancement request and support will be added.
At the moment, the following platforms have been tested:
- Windows XP
- linux (SuSE & Ubuntu) on x86
- solaris on sparc
At the moment, the following jdks / jres have been tested
- several versions of sun jre / jdk (from 1.4, 1.5 and 1.6 serieses)
The binaries are compiled w/ the provided rant script. Just type
On Windows you need MS cl compiler installed and MS link program to link. If you have the expertise and are willing to offer help to make compiling work w/ cygwin, mingw or something else, it is highly appreciated.
To use the native launcher, you need to either place the executable in the bin directory of groovy installation OR set the GROOVY_HOME environment variable to point to your groovy installation. If you do not use -jh / --javahome option (see below), JAVA_HOME needs to be set also.
The launcher primarily tries to find the groovy installation by seeing whether it is sitting in the bin directory of one. If not, it resorts to using GROOVY_HOME environment variable.
Note: the autodetection of groovy installation dir by using the location of the executable thus far only works on windows and linux. Support for other platforms is under way.
The native launcher accepts accepts the same parameters as the .bat / shell script launchers, and on top of that
-jh / --javahome <path to your jdk / jre> - makes groovy use the designated jre / jdk instead of the one pointed to by JAVA_HOME. Any jdk / jre >= 1.4 should work
--conf <conf file to use> use the given groovy conf file instead of the default one
-cp / -classpath / --classpath <user classpath> the classpath to use. Note that this does not need to be the first param as it must when using the windows groovy.bat
-client to use a client VM
-server to use a server VM
Any options not recognized as options to groovy are passed on to the jvm, so you can e.g. do
groovy -Xmx250m myscript.groovy
The -client (default) and -server options to designate the type of jvm to use are also supported, so you can do
groovy -Xmx250m -server myscript.groovy
Note that no aliases like -hotspot, -jrockit etc. are accepted - it's either -client or -server
You can freely mix jvm parameters and groovy parameters. E.g. in the following -d is param to groovy and -Dmy.prop=foo / -Xmx200m are params to the jvm:
groovy -Dmy.prop=foo -d -Xmx200m myscript.groovy
The environment variable JAVA_OPTS that the .bat/shell script launchers use is ignored.
groovy.exe and groovyw.exe on Windows
Similarly to java.exe and javaw.exe on a jdk, the build process produces groovy.exe and groovyw.exe on windows. The difference is the same as w/ java.exe and javaw.exe - groovy.exe requires a console and will launch one if it is not started in a console, whereas groovyw.exe has no console (and is usually used to start apps w/ their own gui or that run on the background).
Precompiled binaries are unfortunately not yet available. Hopefully they will be soon.
Why have a native launcher, why aren't the startup scripts (groovy.bat, groovy.sh) sufficient? Here are some reasons:
- on windows, groovy files may be associated w/ the groovy.exe. Apparently this is not possible for groovy.bat (or any .bat file for that matter)
- note that once you associate .groovy files w/ groovy.exe, you can run groovy scripts just by using their name w/out the suffix (provided they are
in the current dir or on PATH), e.g. you can run myscript.groovy just by typing myscript
- it solves an open bug : return value of groovy (on windows) is always 0 no matter what happens in the executed script ( even if you call System.exit(1) ). Granted, this could be solved by editing the launch scripts also.
- it is slightly faster than the corresponding .bat / shell script
- you can mix jvm params and groovy params, thus making it easier and more natural to e.g. reserve more memory for the started jvm.
- the process will be called "groovy", not "java". Cosmetic, yes, but still nice. = )
- fixes the problems there have been w/ the .bat launcher and paths w/ whitespace
Also, the launcher has been written so that the source can be used to easily create a native launcher for any Java program.