manpagez: man pages & more
man jmod(1)
Home | html | info | man
jmod(1)                          JDK Commands                          jmod(1)




NAME

       jmod - create JMOD files and list the content of existing JMOD files


SYNOPSIS

       jmod (create|extract|list|describe|hash) [options] jmod-file

       Includes the following:

       Main operation modes

       create Creates a new JMOD archive file.

       extract
              Extracts all the files from the JMOD archive file.

       list   Prints the names of all the entries.

       describe
              Prints the module details.

       hash   Determines  leaf modules and records the hashes of the dependen-
              cies that directly and indirectly require them.

       Options

       options
              See Options for jmod.

       Required

       jmod-file
              Specifies the name of the JMOD file to create or from  which  to
              retrieve information.


DESCRIPTION

       Note:  For  most  development tasks, including deploying modules on the
       module path or publishing them to a Maven repository, continue to pack-
       age  modules  in modular JAR files.  The jmod tool is intended for mod-
       ules that have native libraries or other  configuration  files  or  for
       modules  that you intend to link, with the jlink tool, to a runtime im-
       age.

       The JMOD file format lets you aggregate files other than .class  files,
       metadata,  and  resources.   This  format is transportable but not exe-
       cutable, which means that you can use it during compile  time  or  link
       time but not at run time.

       Many  jmod  options involve specifying a path whose contents are copied
       into the resulting JMOD files.  These options copy all the contents  of
       the  specified  path,  including subdirectories and their contents, but
       exclude files whose names match the pattern specified by the  --exclude
       option.

       With  the  --hash-modules  option or the jmod hash command, you can, in
       each module's descriptor, record hashes of the content of  the  modules
       that  are  allowed  to depend upon it, thus "tying" together these mod-
       ules.  This enables a package to be exported to one or more specifical-
       ly-named  modules and to no others through qualified exports.  The run-
       time verifies if the recorded hash of a module matches the one resolved
       at run time; if not, the runtime returns an error.


OPTIONS FOR JMOD

       --class-path path
              Specifies  the  location of application JAR files or a directory
              containing classes to copy into the resulting JMOD file.

       --cmds path
              Specifies the location of native commands to copy into  the  re-
              sulting JMOD file.

       --config path
              Specifies  the  location of user-editable configuration files to
              copy into the resulting JMOD file.

       --dir path
              Specifies the location where jmod puts extracted files from  the
              specified JMOD archive.

       --dry-run
              Performs a dry run of hash mode.  It identifies leaf modules and
              their required modules without recording any hash values.

       --exclude pattern-list
              Excludes files matching  the  supplied  comma-separated  pattern
              list, each element using one the following forms:

              o glob-pattern

              o glob:glob-pattern

              o regex:regex-pattern

              See  the  FileSystem.getPathMatcher  method  for  the  syntax of
              glob-pattern.   See  the  Pattern  class  for  the   syntax   of
              regex-pattern, which represents a regular expression.

       --hash-modules regex-pattern
              Determines the leaf modules and records the hashes of the depen-
              dencies directly and indirectly requiring  them,  based  on  the
              module  graph  of  the modules matching the given regex-pattern.
              The hashes are recorded in the JMOD archive file being  created,
              or a JMOD archive or modular JAR on the module path specified by
              the jmod hash command.

       --header-files path
              Specifies the location of header files to copy into the  result-
              ing JMOD file.

       --help or -h
              Prints a usage message.

       --help-extra
              Prints help for extra options.

       --legal-notices path
              Specifies the location of legal notices to copy into the result-
              ing JMOD file.

       --libs path
              Specifies location of native libraries to copy into the  result-
              ing JMOD file.

       --main-class class-name
              Specifies main class to record in the module-info.class file.

       --man-pages path
              Specifies  the  location of man pages to copy into the resulting
              JMOD file.

       --module-version module-version
              Specifies the module version to record in the  module-info.class
              file.

       --module-path path or -p path
              Specifies  the module path.  This option is required if you also
              specify --hash-modules.

       --target-platform platform
              Specifies the target platform.

       --version
              Prints version information of the jmod tool.

       @filename
              Reads options from the specified file.

              An options file is a text file that  contains  the  options  and
              values that you would ordinarily enter in a command prompt.  Op-
              tions may appear on one line or on several lines.  You  may  not
              specify  environment  variables for path names.  You may comment
              out lines by prefixinga hash symbol (#) to the beginning of  the
              line.

              The following is an example of an options file for the jmod com-
              mand:

                     #Wed Dec 07 00:40:19 EST 2016
                     create --class-path mods/com.greetings --module-path mlib
                       --cmds commands --config configfiles --header-files src/h
                       --libs lib --main-class com.greetings.Main
                       --man-pages man --module-version 1.0
                       --os-arch "x86_x64" --os-name "Mac OS X"
                       --os-version "10.10.5" greetingsmod


EXTRA OPTIONS FOR JMOD

       In addition to the options described in Options for jmod, the following
       are extra options that can be used with the command.

       --do-not-resolve-by-default
              Exclude from the default root set of modules

       --warn-if-resolved
              Hint  for  a  tool to issue a warning if the module is resolved.
              One of deprecated, deprecated-for-removal, or incubating.


JMOD CREATE EXAMPLE

       The following is an example of creating a JMOD file:

              jmod create --class-path mods/com.greetings --cmds commands
                --config configfiles --header-files src/h --libs lib
                --main-class com.greetings.Main --man-pages man --module-version 1.0
                --os-arch "x86_x64" --os-name "Mac OS X"
                --os-version "10.10.5" greetingsmod


JMOD HASH EXAMPLE

       The following example demonstrates what happens when you try to link  a
       leaf  module (in this example, ma) with a required module (mb), and the
       hash value recorded in the required module doesn't match  that  of  the
       leaf module.

       1. Create and compile the following .java files:

           o jmodhashex/src/ma/module-info.java

                    module ma {
                      requires mb;
                    }

           o jmodhashex/src/mb/module-info.java

                    module mb {
                    }

           o jmodhashex2/src/ma/module-info.java

                    module ma {
                      requires mb;
                    }

           o jmodhashex2/src/mb/module-info.java

                    module mb {
                    }

       2. Create a JMOD archive for each module.  Create the directories jmod-
          hashex/jmods and jmodhashex2/jmods, and then run the following  com-
          mands  from  the jmodhashex directory, then from the jmodhashex2 di-
          rectory:

           o jmod create --class-path mods/ma jmods/ma.jmod

           o jmod create --class-path mods/mb jmods/mb.jmod

       3. Optionally preview the jmod hash command.  Run the following command
          from the jmodhashex directory:

           jmod hash --dry-run -module-path jmods --hash-modules .*

           The command prints the following:

                  Dry run:
                  mb
                    hashes ma SHA-256 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a

           This  indicates  that  the jmod hash command (without the --dry-run
           option) will record the hash value of the leaf  module  ma  in  the
           module mb.

       4. Record  hash values in the JMOD archive files contained in the jmod-
          hashex directory.  Run the following command from the jmodhashex di-
          rectory:

                  jmod hash --module-path jmods --hash-modules .*

           The command prints the following:

                  Hashes are recorded in module mb

       5. Print  information  about  each  JMOD archive contained in the jmod-
          hashex directory.  Run the highlighted commands from the  jmodhashex
          directory:

                  jmod describe jmods/ma.jmod

                  ma
                    requires mandated java.base
                    requires mb

                  jmod describe jmods/mb.jmod

                  mb
                    requires mandated java.base
                    hashes ma SHA-256 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a

       6. Attempt  to  create a runtime image that contains the module ma from
          the directory jmodhashex2 but the module mb from the directory jmod-
          hashex.  Run the following command from the jmodhashex2 directory:

           o Linux and OS X:

                    jlink --module-path $JA-
                    VA_HOME/jmods:jmods/ma.jmod:../jmod-
                    hashex/jmods/mb.jmod --add-modules ma --output ma-app

           o Windows:

                    jlink --module-path %JA-
                    VA_HOME%/jmods;jmods/ma.jmod;../jmod-
                    hashex/jmods/mb.jmod --add-modules ma --output ma-app

           The command prints an error message similar to the following:

                  Error: Hash of ma (a2d77889b0cb067df02a3abc39b01ac1151966157a68dc4241562c60499150d2) differs to
                  expected hash (07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a) recorded in mb



JDK 15                               2020                              jmod(1)

openjdk 15.0.2 - Generated Tue Feb 23 16:03:56 CST 2021
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.