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. Note that you still need to have groovy and jre or jdk installed, i.e. the native launcher is a native executable replacement for the startup scripts (groovy.bat, groovy.sh).
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, Vista)
- 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)
- jrockit (on windows)
The current version of the native launcher works with any groovy version.
- Paths are not converted on cygwin, so you have to use windows style paths when invoking scripts
- On OS-X automatic detection of the executable location does not work. This means you have to set GROOVY_HOME
The source code repository for the Native Launcher module resides at http://svn.codehaus.org/groovy/trunk/groovy/modules/native_launcher.
The binaries are compiled w/ the provided rant script. Just type
On Windows you can either compile w/ ms cl compiler + ms link from normal windows command prompt or gcc from cygwin or msys. On cygwin, you currently have to use the rant version from svn head, and run rant w/ the script rant/trunk/run_rant as the present rant release does not work w/ cygwin.
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, 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 that this means that GROOVY_HOME environment variable does not need to be set to be able to run groovy.
The native launcher accepts accepts all the same parameters as the .bat / shell script launchers, and a few others on top of that. For details, type
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. You can achieve the same effect by using environment variable JAVA_TOOL_OPTIONS, see http://java.sun.com/j2se/1.5.0/docs/guide/jvmti/jvmti.html#tooloptions and http://java.sun.com/j2se/1.5/pdf/jdk50_ts_guide.pdf
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).
There are precompiled binaries for windows attached to this page (go to the top of the page, click "View in wiki" symbol on the right and then click on the "Attachments" tab). They are not guaranteed to be completely up to date with the sources in svn head, but they should work.
Hopefully we will have precompiled binaries for all supported platforms in the future.
Windows file association
If you want to run your groovy scripts on windows so that they seem like any other commands (i.e. if you have myscript.groovy on your PATH, you can just type myscript), do as follows:
- add .groovy to PATHEXT environment variable
- make changes in windows registry as follows
- run regedit.exe
- create a new key HKEY_CLASSES_ROOT\.groovy and give it the value groovyFile
- create HKEY_CLASSES_ROOT\groovyFile
- under that, create HKEY_CLASSES_ROOT\groovyFile\Shell and give it value open
- under that, create HKEY_CLASSES_ROOT\groovyFile\Shell\open\command and give it value (adjust according to your groovy location) "c:\programs\groovy-1.0\bin\groovy.exe" "%1" %*
Yes, it would be nicer to have an installer do this. = ) See http://jira.codehaus.org/browse/GROOVY-1892#action_98035 for a groovy scriptom script that does the registry manipulation and http://jira.codehaus.org/browse/GROOVY-1950 to see what's up with a real installer.
Why have a native launcher, why aren't the startup scripts (groovy.bat, groovy.sh) sufficient? Here are some reasons:
- 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.
How it works
Essentially the launcher does the same thing that the normal java launcher (java executable) does - it dynamically loads the dynamic library containing the jvm and hands the execution over to it. It does not start a separate process (i.e. it does not call the java executable).
If you have expertise with any of the following and want to help, please email me at antti dot karanta (at) iki dot fi:
- Cygwin c api
- more specifically: how to successfully load and use the win <-> posix path conversion functions when loading the cygwin1.dll from a non-cygwin app
- os-x c programming
- more specifically: how to get the path to the current executable