$Revision$
$Date$

Author:  Antti Karanta (Antti dot Karanta (at) hornankuusi dot fi) 


What it is
----------

This is a native launcher for Groovy, i.e. here you can find C sources and
build files to build a native executable to launch Groovy scripts, much the 
same way Java binary is used to launch Java programs.


Design principles
-----------------

For maximum portability, the source is written in ANSI-C using POSIX functions. Anything
that can be done using these is done so without using external libraries / extensions. 

Also, C99 features (although cool and useful) have not been used as they are not supported
by ms cl compiler (visual c++).

The launcher has been built in such a way that only groovy.c has groovy dependent stuff.
It is simple to use the other source files to create a native laucher for any
Java program. In fact, native launchers for gant and grails have later been added.

Great care has been taken to avoid possibility of buffer overflows. The common c-convention
of using "big enough" buffer is avoided if at all possible - instead memory is allocated dynamically after
calculating how much is needed. The only exception to this rule is places where the posix or 
os specific API used must be called with a preallocated buffer, e.g. realpath function.

Licencing
---------

The sources are provided with Apache 2 licence as that was thought to be liberal 
enough so that these can be used for any purpose commercial or open source. If
you are for some reason restricted by that licence, please contact the author and
we'll work it out - the purpose is for these sources to be as widely usable as possible.


Porting to currently unsupported operating systems
--------------------------------------------------

Currently the implementation of the following things are platform dependent:

  * how a dynamic library is loaded. 
    * If your system has dlfcn.h (like linux, solaris and os-x), this works out of the box
  * directory handling (jst_fileutils.c). 
    * If your system has dirent.h this works out of the box.

  * location and name of jvm dynamic library (jvmstarter.c)
  * getting the location of the current process' executable (jst_fileutils.c)
  * supporting platform peculiarities like looking up java home from windows registry and
    using the standard Java installation location on os-x
  
Java launcher generator
-----------------------

This directory (and subdirectories) also contains a work in progress: a code 
generator to generate c sources and build files for a native launcher for any 
java app.

Ruby was chosen as the implementation language to avoid any bootstrap issues,
and due to its great yaml support.
  
There are other similar projects/products. Here are the ones that I'm aware of and why 
we need yet another one:

Product       Website                                     Why this is not sufficient            Notes

Launch4J      http://launch4j.sourceforge.net             Only generates windows executables    
Janel         http://www.redskaper.com/Janel.jsp          Only generates windows executables    
Caphyon       http://www.advancedinstaller.com/java.html  commercial + win & os-x support only  Generates an installer, the native launcher is just one feature
Java launcher included in the src.zip of a jdk            Licence does not permit the creation of custom launchers (TODO: check if openJDK has changed this situation). See e.g. http://www.ociweb.com/jnb/jnbJul2004.html
exe4j         http://www.ej-technologies.com/products/exe4j/overview.html commercial, windows only
JEXECreator   http://www.ucware.com/jexec                 commercial, windows only
JEXEPack      http://www.duckware.com/jexepack/index.html commercial, windows only


More information
----------------

See http://docs.codehaus.org/display/GROOVY/Native+Launcher


TODO
----

 * refactor parameter classification into separate functions, possibly a separate source file
   options:
   - value into system property
   - value to classpath (a sysprop, yes, but needs to be handled separaterly)
   - value used as java home
   - map to another launchee param (single or double)
   - if not set, 
     * use the value of an env var
     * use hard coded default (can refer to install dir by ${app_home}.
     * leave out
   * what about the other way around, i.e. specifying that a sys prop / launchee param is to
     be created using a param value / env var value / hard coded default value?
 * add the possibility to define "recursive jar dirs", i.e. directories where jars are searched for recursively.
 * the terminating suffixes is really only necessary in case where the name of the input file begins w/ "-". 
   Maybe it is such a special case that it can be ignored? In that case the terminating suffixes part could be
   removed.
 * add an option to restrict which vendor's java implementations are used
   * very low priority
 * add an option to restrict the used jre/jdk version to be exactly something, greater than something, between some values etc.
   Have a look at how eclipse plugins define the required version of their dependant plugins in their manifest.mf
   A problem that needs to be solved: how to reliably tell the version of a java impl without actually loading and starting the jvm?
 * Write some instructions on creating an .ico file for windows. Point to e.g. http://imageauthor.com and some win programs for icon creation.