Specifying Modules to Include
What you'll learn: How to use the --add-modules flag to explicitly include your application module and all its transitive dependencies when creating a custom runtime image with jlink.
The Core Idea
When you run jlink, it doesn't automatically guess which modules your application needs. You must explicitly tell it which root modules to include. Once you specify a root module with --add-modules, jlink intelligently resolves and includes all of that module's transitive dependencies—everything it requires, everything those modules require, and so on.
Think of it like packing for a trip: you tell the packing assistant "I need my hiking boots," and the assistant automatically includes the laces, insoles, and waterproofing spray because those are dependencies of having functional boots.
Using --add-modules
The basic syntax looks like this:
jlink --module-path $JAVA_HOME/jmods:mods \
--add-modules com.myapp.main \
--output myapp-runtime
Here, com.myapp.main is your application module. jlink will:
- Include
com.myapp.main - Scan its
requiresdirectives - Include all required modules (including
requires transitivedependencies) - Recursively resolve their dependencies
- Bundle everything into
myapp-runtime
You can add multiple root modules separated by commas:
--add-modules com.myapp.main,com.myapp.plugins
Why This Matters
Without --add-modules, jlink would create an empty or minimal runtime. By specifying your entry-point module, you ensure the entire dependency graph is captured, creating a complete, self-contained runtime image with only what your application needs—no more, no less.
Key Takeaway: The --add-modules flag tells jlink which root modules to include; jlink then automatically resolves and bundles all transitive dependencies into your custom runtime image.