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 is included in the groovy windows installer. For other platforms, you have to compile it yourself.

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).

Status

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

OS-X

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.

Compiling on windows

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.

Thus the best way compiling with an open source tool chain is to use msys. To install the tool chain for msys follow these simple steps:

Run it (it install the bash and sets up the path, adding the MinGW executables to the path inherited from Windows)

You get an icon that starts a bash

Start the bash and navigate to where you downloaded the source code for the native launcher

Enter the command 'rant' and watch it compile the sources.

Compiling with cygwin/mingw gcc the produced executable will not depend on any dlls that aren't found on windows by default. If you compile with ms visual studio, you will need an extra dll that may or may not be found on your windows. The dll youo need depends on the visual studio version, see here for details.

Just try to run first - if there's no complaint about a missing dll, you're fine.

Usage

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.

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.

Finding java installation

The native launcher uses the following order to look up java installation to use:

user provided java home (using the -jh / --javahome parameter)

java installation pointed to by JAVA_HOME environment variable

java installation found by seeing where java executable can be found on PATH (symlinks are followed to find the actual executable)

java installation marked as the current version in windows registry (value of "CurrentVersion" in keys

HKEY_LOCAL_MACHINESOFTWARE
JavaSoft
Java Development Kit

HKEY_LOCAL_MACHINESOFTWARE
JRockit
Java Development Kit

HKEY_LOCAL_MACHINESOFTWARE
JavaSoft
Java Runtime Environment

HKEY_LOCAL_MACHINESOFTWARE
JRockit
Java Runtime Environment

hard coded "/System/Library/Frameworks/JavaVM.framework" (os-x only)

To put it another way - JAVA_HOME does not need to be set.

Parameters

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

groovy -h

JVM parameters

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

JAVA_OPTS

The environment variable JAVA_OPTS can be used to set jvm options you want to be in effect every time you run groovy, e.g. (win example)
set JAVA_OPTS=-Xms100m -Xmx200m

Note that if you set the same option from the command line that is already set in JAVA_OPTS, the one given on the command line overrides the one given in JAVA_OPTS.

Paths on cygwin

By default, the windows version of the native launcher only understands windows style paths.

You can compile a version that supports both (cygwin paths on cygwin, normal windows paths elsewhere) by using the compile target cygwinc like this:

rant cygwinc

As noted above, if you are running the build on cygwin, you have to use the rant version from svn head. Or use scons.

Cygwin support is a little experimental and if you use it I would very much appreciate if you told me how it works for you. There are no known issues ATM.

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).

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), you have to associate groovy script files with the groovy executable. If you use the groovy windows installer it will do this for you. Otherwise, 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

Why?

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

on Linux, you can't use an interpreted script as a #! interpreter, because of a kernel bug

Also, the launcher has been written so that the source can be used to easily create a native launcher for any Java program.

Known issues

Using -server option on solaris crashes the jvm.

Help wanted

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 (specifically: how to successfully load and use the win <-> posix path conversion functions when loading the cygwin1.dll from a non-cygwin c app)

If you are running on an os that is not yet supported, please contact me and we'll make it work. You do not need c expertise, I'll just ask you some questions about the environment, then you compile after I've made the changes and make sure it works. Examples of environments I'd like someone who has them to help me out with: linux on non-x86 hardware, solaris on x86, hpux, freebsd...