Summary
-------

Create a tool that can assemble and optimize a set of modules and their
dependencies into a custom run-time image as defined in
[JEP 220](http://openjdk.java.net/jeps/220).


Non Goals
---------

This JEP does not commit the resulting tool to generate anything other
than a modular run-time image. 

It is not a goal of this JEP to define a standard or supported API for
plugins. Instead, the plugin API will be **strictly experimental**. A
future JEP may re-visit this topic once experience has been obtained
using the plugin API defined by this JEP.


Motivation
----------

[JEP 261](http://openjdk.java.net/jeps/261) defines _link time_ as an
optional phase between the phases of compile time (the `javac` command)
and run-time (the `java` run-time launcher). Link time requires a linking
tool that will assemble and optimize a set of modules and their
transitive dependencies to create a run-time image or executable.

Link time is an opportunity to do _whole-world_ optimizations that are
otherwise difficult at compile time or costly at run-time. An example
would be to optimize a computation when all its inputs become constant
(i.e., not unknown).  A follow-up optimization would be to remove code
that is no longer reachable.


Description
-----------

A basic invocation of the linker tool, `jlink`, is:

    $ jlink --module-path <modulepath> --add-modules <modules> --limit-modules <modules> --output <path>

where:

  - `--module-path` is the path where observable modules will be
    discovered by the linker; these can be modular JAR files, JMOD files,
    or exploded modules

  - `--add-modules` names the modules to add to the run-time image; these
    modules can, via transitive dependencies, cause additional modules to
    be added

  - `--limit-modules` limits the universe of observable modules

  - `--output` is the directory that will contain the resulting run-time
    image

The `--module-path`, `--add-modules`, and `--limit-modules` options are
described in further detail in [JEP 261](http://openjdk.java.net/jeps/261).

Other options that `jlink` will support include:

  - `--help` to print a usage/help message
  - `--version` to print version information


Alternatives
------------

The alternative to a linking tool is to use platform-specific JDK and JRE
image-build scripts. This approach would make it difficult to create
custom run-time images.


Testing
-------

Beyond the expected set of unit tests to exercise the tool I, the JDK build
will regularly exercise `jlink` by creating the JDK and JRE run-time images.


Risks and Assumptions
---------------------

The set of requirements for the tool is not complete at this time. The
tool's extensibility is expected to evolve.

Dependences
-----------

  - This JEP  depends on the module system that will be specified by
    [JSR 376 (Java Platform Module System)](http://openjdk.java.net/projects/jigsaw/spec)
    and implemented by [JEP 261: Module System](http://openjdk.java.net/jeps/261).

  - The initial implementation of [JEP 220](http://openjdk.java.net/jeps/220)
    in JDK 9 uses a custom build-time tool to construct JRE and JDK
    images. That tool will be replaced by `jlink`.