OVERVIEW

'jarbinger' creates a standalone binary when given a Java build
directory.  This would seem strange to most Java developers since
typically Linux developers would wrap the Java with a simple script
which bootstraps and executes the Java program and the user would not
realize the difference.  But for some environments avoiding the
install step by having a single distributable executable file is a
useful option.  So, the advantage and disadvantage is that now you've
got an architecture and OS specific executable.

  WARNING: there are a few setting hard coded at the moment in the
  makefile (e.g. arguments to 'objcopy', see CAVEATS below)

USAGE

jarbinger {toolName} {archiveDirPath} {jarFilename|.} {mainClassName}
        [jvmOptsDefault]

    toolName        standalone binary name (relative or absolute path)

    archiveDirPath  directory with Java jar or class files (relative or
                    absolute path)

    jarFilename     name of jar(s) colon separated (or '.' if no jars)

    mainClassName   class containing the 'main' method (full path)

    jvmOptsDefault  JVM default options passed while creating the JVM

EXAMPLES

Here are the two main use cases of jarbinger:

  + Given a standard NetBeans build you with a 'dist' directory which
    contains a single jar 'SomeProject.jar', a main class
    'some.project.Main', and you want the executable to be
    'some_project'

        jarbinger some_project dist SomeProject.jar some.project.Main

    If there are any dependent jars under the 'lib' directory they
    should be located implicitly because of how NetBeans packaged the
    main jar with a manifest entry pointing to the dependent jars.

  + Given a class file directory 'build/classes', a main class
    'some.project.Main', and you want the executable to be 
    'some_project'

        jarbinger some_project build/classes . some.project.Main

Also you can append any JVM default options such as defining system
properties or configuring JVM memory.  The user is allowed to override
the defaults via environment variable named '{toolName}_JVM_OPTS'

BACKGROUND

The tool creates an archive of your Java classes and/or jars.  The
archive gets converted into an object file.  The object file gets
linked to a simple executable.  At runtime, we unpack the archive,
start a JVM, invoke the main class you specified.

Incidentally, the tool uses the same technique of unpacking files it
needs to create your binary as your binary does at runtime to run your
Java program.

ENVIRONMENT CONFIGURATION

jarbinger uses a temporary directory to store all unpacked files.  The
goal of the directory name is to be unique to the user, easy to delete
from the top level and also unique per version of the tool.  Here is
the default format...

    "/tmp/jarbinger-%1%/%2%/%3%" where
        %1% = from environment variable LOGNAME (usually $USER)
        %2% = toolName
        %3% = a unique ID from build (uses `uuid`)
 
  - Using JARBINGER_CACHE_PATH_FORMAT will override the default for
    'jarbinger' or for the tool use.  The setting is not compiled into
    the executable (currently).

  - Using {toolName}_JVM_OPTS on the tool at runtime will override the
    compiled in JVM default options (see 'jvmOptsDefault' above)

CAVEATS

  ! currently hard coded arguments to 'objcopy' for x86-64

  - There is not much error checking.

  - The default use of /tmp as a cache for unpacked Java files might
    not be practical for all users.  See ENVIRONMENT CONFIGURATION for
    alternatives.

  - If an error is reported during processing it likely will be
    confusing as 'make' is invoked internally to create the binary.

BUGS

  - needs to catch and dump any exception from application and
    propagate exit status
    (currently exceptions are silent; there is no indication)

TODO

  - Determine objcopy arguments from user's system.

  - Add better error checking.

  - If {toolName}_JVM_OPTS_EXTRA is set add to JVM_OPTS while creating JVM.