Command Line Options
The native-image command has many options to use. There are four categories of options:
- Image generation options
- Macro options
- Non-standard options
- Server options
Basic Options
info
These options are collected from the output of native-image --help.
| Option | Description |
|---|---|
-cp, -classpath, --class-path | Set a list of directories, JAR archives, and ZIP archives to search for class files. |
-p, --module-path | Set a list of directories for modules. |
--add-modules | Root modules to resolve in addition to the initial module. Module name can also be ALL-DEFAULT, ALL-SYSTEM, ALL-MODULE-PATH. |
-D<name>=<value> | Set a system property |
-J<flag> | Pass <flag> to the JVM running the native image builder |
--diagnostics-mode | Enable diagnostics output: class initialization, substitutions, etc. |
--enable-preview | Allow classes to depend on preview features of this release |
--enable-native-access | Set modules that are permitted to perform restricted native operations. Module name can also be ALL-UNNAMED. |
-O<level> | b for fastest build time, 0 for no optimizations, 1 for basic optimizations, 2 for advanced optimizations, 3 for all optimizations for best performance |
--verbose | Enable verbose output |
--version | Display the product version |
--help | Display help message |
--help-extra | Display help of non-standard options |
--color | Set color build output (always, never, or auto) |
--allow-incomplete-classpath | Build with an incomplete class path. Type resolution errors will be reported at runtime when they are accessed the first time. |
--auto-fallback | Build a standalone image if possible |
--force-fallback | Force building of a fallback image |
--no-fallback | Build a standalone image or report a failure |
--enable-http | Enable HTTP support |
--enable-https | Enable HTTPS support |
--enable-monitoring | Enable monitoring features that allow the VM to be inspected at run time. Comma-separated list can contain heapdump, jfr, jvmstat, jmxserver (experimental), jmxclient (experimental), or all. |
--enable-sbom | Embed a Software Bill of Materials (SBOM) in the executable or shared library for passive inspection. A comma-separated list can contain cyclonedx, strict or export. |
--enable-url-protocols | List of comma separated URL protocols to enable. Currently, only file and resource are enabled by default. |
--gc=<value> | Select native-image garbage collector implementation |
--features | Set a comma-separated list of fully qualified Feature implementation classes |
--initialize-at-build-time | A comma-separated list of packages and classes (and implicitly all of their superclasses) that are initialized at image build time. An empty string means all packages. |
--initialize-at-run-time | A comma-separated list of packages and classes (and implicitly all of their subclasses) that must be initialized at runtime. |
--install-exit-handlers | Install signal handlers. This option is recommended for native images running in containerized environments, like Docker containers. |
--libc | Select the libc implementation to use when building static images. Possible values are glibc, musl, and bionic. |
--report-unsupported-elements-at-runtime | Report the usage of unsupported methods and fields at runtime when they are accessed the first time. |
--shared | Build a shared library |
--static | Build statically linked executable |
--target | Select the native image compilation target.The format is <OS>-<architecture>. The default value is host's OS-architecture pair. |
-g | Generate debugging information |
--trace-class-initialization | A comma-separated list of fully-qualified class names that class initialization is traced for. |
--trace-object-instantiation | A comma-separated list of fully-qualified class names that object instantiation is traced for. |
--enable-all-security-services | Add all security service classes |
--configure-reflection-metadata | Enable runtime instantiation of reflection objects for non-invoked methods. |
-o | Set name of the output file to be generated |
--strict-image-heap | Enable the strict image heap mode that allows all classes to be used at build-time but also requires types of all objects in the heap to be explicitly marked for build-time initialization. |
--parallelism | Set the maximum number of threads to use concurrently during native image generation |
--link-at-build-time | Require types to be fully defined at image build-time. If used without args, all classes in scope of the option are required to be fully defined. |
--link-at-build-time-paths | Require all types in given class or module-path entries to be fully defined at image build-time. |
--list-modules | List observable modules and exit. |
--list-cpu-features | Show CPU features specific to the target platform and exit. |
--native-image-info | Show native-toolchain information and image-build settings. |
Non-standard Options
Non-standard options can be checked by running native-image expert-options or native-image expert-options-all.
warning
Non-standard options may be deprecated or removed in different GraalVM releases.
There are two types of non-standard options:
- Hosted options
- Runtime options
Hosted options configure a native image build. These options are set using the prefix -H:.
Runtime options get their initial value in the image build time, using the prefix -R:. The initial value can be
overridden using the -XX: prefix when executing the native executable.
Boolean options are toggled using + or -. + means enabled, while - means disabled. For example, AOTInline is a hosted boolean option, it can be enabled using -H:+AOTInline, or disabled
using -H:-AOTInline.
Other options are specified using the name=value format. For example, Class is a hosted option. It can be used
like -H:Class=Main. The runtime MaximumHeapSizePercent option can be used like -R:MaximumHeapSizePercent=80.