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 a JRE or JDK installed, i.e. the native launcher is a native executable replacement for the startup scripts (groovy.bat, groovy).
The native launcher is included in the Groovy Windows installer. For other platforms, if your package management system does not have it, you will have to compile it yourself. This is not hard, you just need to have SCons (and Python) installed.
Essentially the launcher does the same thing that the normal Java launcher (java executable) - 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).
The native launcher aims to compile and run on any os and any JDK/JRE >= 1.4. If you are using a combination of os+jdk/jre that is not supported, please post a JIRA enhancement request and support will be added.
At the moment, the following platforms have been tested:
At the moment, the following JDKs/JREs have been tested
The current version of the native launcher works with any version of Groovy.
Here are precompiled binaries for Windows:
They are not guaranteed to be completely up to date with the sources of HEAD in the Subversion repository, but they should work.
Hopefully we will have precompiled binaries for all supported platforms in the future.
The same binaries work for all the Groovy executables (groovy, groovyc, groovysh...). Just copy / (soft)link to the executable with the name of the executable you want, e.g. on Windows
and on Linux, Mac OS X, Solaris, etc.:
In addition the build produces launchers for gant and grails.
A note about gant: the gant launcher is meant for standalone gant installation. To use gant installed into your groovy installation (e.g. by groovy windows installer) use the renamed groovy executable as described above.
To get the sources please see the native launcher git repository.
The executables are compiled using SCons. For Windows there is a SCons installer that can be used after having installed Python - The SCons build framework is written in Python. SCons is part of Cygwin and can be installed using the usual installer. The same goes for MacPorts on Mac OS X, though there is a disk image installer as well. For Ubuntu, Debian, Fedora, SuSE, etc. SCons is packages and so the usual package management can be used to install. The build has only been tested with SCons 0.98 and greater, it may not work with earlier versions of SCons.
Once you have SCons installed then simply typing:
will compile things for the platform you are compiling on. Type:
for a short help message about the native launcher build and
for a message about using scons.
The native launcher, if compiled with default options, will look up groovy and java installation locations as described below. However, on some platforms (linux and other *nix variants) it may be desirable for performance and security reasons to "hardwire" these locations, i.e. set them to fixed values at compile time.
Currently, native launcher supports setting three things at compile time (together or separately): GROOVY_HOME, GROOVY_STARTUP_JAR and JAVA_HOME by passing in the values to scons build via "extramacros" option.
To test that the binary you compiled uses preset locations, run groovy w/ environment variable __JLAUNCHER_DEBUG set, e.g.
The launcher will print debug info to stderr, among other things how it obtained the locations of groovy and java installations.
If you are not already using Cygwin, then you may want to investigate using MSYS and the MinGW toolchain.
Compiling with the Cygwin or MinGW GCC produces executables that depend only dlls that are found on Windows by default. If you compile with Visual Studio, you will need an extra dll that may or may not be found on a particular windows system. The dll you need depends on the Visual Studio version, see here for details.
Try running the generated executable - if there's no complaint about a missing dll, you're fine.
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.
The native launcher uses the following order to look up java installation to use:
To put it another way - JAVA_HOME does not need to be set.
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 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
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
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.
By default, the Windows version of the native launcher only understands Windows style paths if compiled using the Microsoft compiler or the MinGW GCC. If you compile using Cygwin GCC then by default, Cygwin and Windows style paths are understood. The variable cygwinsupport controls the behaviour. If you need to exolicitly set whether the Cygwin path code is included in the build then you can set an option on the command line:
allowed values are True and False. Alternatively if you want to set the value explicitly for every build you can add a line like:
to the file local.build.options in the same directory as the SConstruct file.
Cygwin path support is a little experimental, but there are no known problem at the moment. If you use it, could you please report back success or any problems via the Groovy user mailing list.
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).
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:
Why have a native launcher, why aren't the startup scripts (groovy.bat, groovy.sh) sufficient? Here are some reasons:
Also, the launcher has been written so that the source can be used to easily create a native launcher for any Java program.
LD_LIBRARY_PATH=$JAVA_HOME/jre/lib/sparc/server:$JAVA_HOME/jre/lib/sparc:$LD_LIBRARY_PATH groovy -server myscript.groovy
If you have expertise with any of the following and want to help, please email me at antti dot karanta (at) hornankuusi dot fi: