Jigsaw Quick Start (Obsolete)

This page is obsolete, it has been replaced by a new Quick Start Guide.

1. Module Declaration

module-info.java

Each module has a module declaration, "module-info.java", specifying the module name, version, and its dependencies. For example, the following is the module-info.java for the "com.greetings" module. 
module com.greetings @ 0.1 {
    requires org.astro @ 1.2; // requires a specific version
    class com.greetings.Hello;
}

This com.greetings module is of version 0.1 and it requires the org.astro module. It also declares its main entry point com.greetings.Hello class. The modular compilation unit grammar is described at https://openjdk.org/projects/jigsaw/doc/lang-vm.html.

This module-info.java doesn't specify any platform module and thus by default it will require the full JRE module ("jdk"). You can specify to require the "jdk.base" module and any other platform module like this:

module com.greetings @ 0.1 {
    requires jdk.base; // default to the highest available version
    requires org.astro @ 1.2;
    class com.greetings.Hello;
}

Structuring the source tree

For module compilation, the java compiler needs to be able to find the complete module content (module-info.java and classes for each module in source form or in a compiled form). The ModulePath is introduced to make javac module-aware that can compile one or multiple modules. This section describes the ModulePath briefly and please refer to Modules and javac slides for details.

The module-info.java is placed in the root of the source tree of the module's classes. For example, the root of the source tree is under src/classes directory. To evolve from single-module structure of ClassPath, its module-info.java file should be placed under it.

src/classes/com/greetings/Hello.java
src/classes/module-info.java
For multiple modules, the source tree for each module are placed in its own subdirectory under the <modulepath> directory. For example, src is the ModulePath. The source tree for com.greetings module and org.astro module are in separate subdirectories under the src directory. 
src/com.greetings/module-info.java
src/com.greetings/com/greetings/Hello.java
src/org.astro/module-info.java
src/org.astro/org/astro/World.java
When compiling multiple modules, -modulepath option: 
$ javac -d modules -modulepath modules -sourcepath src \
     `find src -name '*.java'`
This will output to multi-module structure.

2. Compile a module

For example, the src directory contains two modules, com.greetings and org.astro modules with the following source files: 
$ cat src/com.greetings/com/greetings/Hello.java

package com.greetings;
import org.astro.World;
public class Hello {
    public static void main(String[] args) {
        System.out.println("Hello, " + World.name() + "!");
    }
}

$ cat src/org.astro/module-info.java

module org.astro @ 1.2 {
    exports org.astro;
}

$ cat src/org.astro/org/astro/World.java

package org.astro;
public class World {
    public static String name() {
        return "world";
    }
}

$ find src -print
src
src/com.greetings
src/com.greetings/module-info.java
src/com.greetings/com
src/com.greetings/com/greetings
src/com.greetings/com/greetings/Hello.java
src/org.astro
src/org.astro/module-info.java
src/org.astro/org
src/org.astro/org/astro
src/org.astro/org/astro/World.java

$ javac -d modules -modulepath modules -sourcepath src \
      `find src -name '*.java'`
This compiles all java files under the src directory and outputs to the "modules" directory in multi-module structure.

3. Install a module in a module library

A modular JDK has a system module library in which the platform modules are installed. You can create your own module library using the jmod command: 
$ jmod -L mlib create   # this creates a module library "mlib"
Each module library has a parent. By default, it uses the system module library as its parent. The "-P" option can be used to specify a parent module library. A module will be searched from the module library first; if not found, it will delegate to its parent.

You can install one or modules in a module library like this:

$ jmod -L mlib install modules org.astro com.greetings
You can also install a jmod file in a module library.

Currently, there is no jmod option to remove a module from a module library. The workaround is to remove the module content directly:

$ rm -rf mlib/com.greetings

4. Run a module

To run the com.greetings module installed in the "mlib" module library: 
$ java -L mlib -m com.greetings
Hello world!
The new "-m" option must be used to run an application in module mode; otherwise, the application will be run in legacy mode.

5. Create a jmod file

Package the com.greetings as a jmod file using the jpkg command: 
$ jpkg -m modules/com.greetings jmod com.greetings
$ jpkg -m modules/org.astro jmod org.astro
Files com.greetings@0.1.jmod and org.astro@1.2.jmod will be created. To install the jmod files in a module library: 
$ jmod -L mlib install com.greetings@0.1.jmod org.astro@1.2.jmod

Other Useful Commands

$ jmod -L mlib ls       # list all modules installed in mlib
com.greetings@0.1
org.astro@1.2

$ jmod -L mlib ls -v    # list with verbose

com.greetings@0.1
  requires org.astro@=1.2
  requires jdk@=8-ea

org.astro@1.2
  requires jdk@=8-ea
  exports
    org.astro

$ jmod -L mlib dump-config com.greetings

configuration roots = [com.greetings@0.1]
  context +com.greetings
    module com.greetings@0.1
    local (1)
      com.greetings.Hello:com.greetings@0.1
    remote (1101)
      org.astro=+org.astro

  [...]