GENERATE

From ICE Enterprises
Jump to navigation Jump to search

creates or modifies a file of various formats

<FUNC>   - Type of file/action (EXP, EXPStub, JARS, JNLP, ...)
<NAME>   - Root name of file
<P3>     - Optional argument dependent on <FUNC>
<P4>     - Optional argument dependent on <FUNC>
<P5>     - Optional argument dependent on <FUNC>
<P6>     - Optional argument dependent on <FUNC>

Valid <function>s are [APPLETLAUNCHER, BUNdle, EXP, JARS, JNLP, OPER, SIGN].
Generates a file or modifies a file (usually text) of various formats including
JAR files, JNLP (for WEBSTART) files, EXPLAIN files, ...


Functions:
  APPLETLAUNCHER <opt> <dest> <tbl>                                (Since 3.3.0)
    Creates an applet-launcher for that can run a NeXtMidas command in the
    web browser.
      <opt>  Option tree (this is for consistency with BUNDLE and JARS,
             but is largely ignored here).
      <dest> Destination directory for the .html and .jnlp files.   [DEF="jars"]
             Use "bundle" for "$NMROOT/bundle/" or "jars" for "$NMROOT/jars/".
      <tbl>  Table of options for the applet launcher. The table should include:
                Key       | Description               | Default Value
                ----------+---------------------------+-------------------------
                ID        | ID for the applet         | "APPLET"
                NAME      | Name of the applet        | same as ID=
                CODEBASE  | The codebase to use       | --required--
                WEB_PAGE  | Applet web page to create | "index.html"
                WIDTH     | Width of applet (pixels)  | 640
                HEIGHT    | Height of applet (pixels) | 480
                VENDOR    | Vendor of the applet      | --required--
                HOMEPAGE  | Homepage for vendor       | "<CODEBASE>/<WEB_PAGE>"
                NMSTARTUP | NMSTARTUP.MM to use       | --required--
                OPTS      | Option trees to include   | "<opt>,SYS"
                WRITE_AUX | NeXtMidas WRITE AUX       | "RAM"
                READ_AUX  | NeXtMidas READ AUX        | "RAM|DAT"
                COMMAND   | Command to run            | --required--
                DEBUG     | Turn MApplet debugging    | false
                JAVA_VER  | Java version to use       | "1.7+"
                INIT_HEAP | Initial Java heap size    | "512m"
                MAX_HEAP  | Maximum Java heap size    | "512m"
                PROPS     | Java run-time properties  | { }
                ----------+---------------------------+-------------------------

                Note1: The JAVA_VER, INIT_HEAP, and MAX_HEAP are subject to
                       change in future releases without warning.
                Note2: Although it is tempting to use "nxm.sys.cfg.nmstartup.mm"
                       for NMSTARTUP, doing so will override a number of the
                       settings specified here (e.g. OPTS, AUX, etc.).
                Note3: Any tags in PROPS that have a colon in the tag will have
                       the tag converted to lowercase and the colons (":")
                       replaced with periods ("."). This permits Java properties
                       to be entered (e.g. "SUN:JAVA2D:D3D" -> "sun.java2d.d3d")
                       despite the normal Table rules.

  BUNdle <opt> <dest> <keystoreTbl>                                (Since 3.3.0)
    Generate OSGi bundle JAR files for a given option tree. All the options
    are the same as the JARS function, except the generated JARS uses OSGi
    naming conventions (all lower case, dot separated, includes "_<version>").
      <opt>  The option tree.
      <dest> The destination directory for the bundle JAR files, use "bundle"
             for "$NMROOT/bundle/", "jars" for "$NMROOT/jars/".   [DEF="bundle"]
      <keystoreTbl> Optional config table to use a custom jar signing keystore.
             If not set, default self-signed certificate will be used.
             See "Using Custom Keystore" section for details, but here are the
             common required keys to set.                          (Since 3.5.1)
               {KEYSTOREFILE="custom.jks",KEYSTOREPASS="pw",KEYALIAS="keyAlias"}

    This function creates the following JAR files:
      nxm.<opt>_<version>.jar - Java .class files. macros, data files, etc
          (see /FFILT= for a list of files that are included/excluded.

      nxm.<opt>.<osname>.<osarch>_<version>.jar - Native files for current OS.
          The <osname> and <osarch> are derived from the "os.name" and "os.arch"
          system properties, respectively to match the <resources> tag's
          "os" and "arch" attributes in the JNLP file for the current platform.
          Spaces in <osname> and <osarch> are replaced with underscores and it
          is lower-cased. i386 becomes x86 and amd64 becomes x86_64. e.g.
            nxm.sys.linux.x86_3.3.0.jar       (Linux 32-bit)
            nxm.sys.linux.x86_64_3.3.0.jar    (Linux 64-bit)
            nxm.sys.sunos.sparc_3.3.0.jar     (Solaris SPARC)
            nxm.sys.windows.x86_3.3.0.jar     (Windows [XP, 7, etc.] 32-bit)
            nxm.sys.windows.x86_64_3.3.0.jar  (Windows [XP, 7, etc.] 64-bit)

      nxm.<opt>.source_<version>.jar - Source code files (*.java)

  EXP <name> <dest>
    Generates an explain file from the comments in the source code between the
    first /** and */.
      <name> - The command name
      <dest> - Optional full path destination [DEF=<exp area of option tree>]

    Modifiers:
      /S - Generates an explain file STUB by searching for "MA.",
           "msg.name.equals", and other references in the source code.

  JARS <opt> <dest> <keystoreTbl>
    Generate Java WebStart compatible JAR files for a given option tree.
      <opt>  The option tree.
      <dest> The destination directory for the JAR files.           [DEF="jars"]
             Use "jars" for "$NMROOT/jars/".
      <keystoreTbl> Optional config table to use a custom jar signing keystore.
             If not set, default self-signed certificate will be used.
             See "Using Custom Keystore" section for details, but here are the
             common required keys to set.                          (Since 3.5.1)
               {KEYSTOREFILE="custom.jks",KEYSTOREPASS="pw",KEYALIAS="keyAlias"}

    This function creates the following JAR files:
      nxm-<opt>.jar - Java .class files. macros, data files, etc (see /FFILT=
          for a list of files that are included/excluded.

      nxm-<opt>-native-<osname>-<osarch>.jar - Native files for current OS.
          The <osname> and <osarch> are derived the "os.name" and "os.arch"
          system properties, respectively to match the <resources> tag's
          "os" and "arch" attributes in the JNLP file for the current platform.
          Spaces in <osname> and <osarch> are replaced with underscores and it
          is lower-cased. i386 becomes x86 and amd64 becomes x86_64. Since 2.9.2
          Some examples for SYS:
            nxm-sys-native-linux-x86.jar      (Linux 32-bit)
            nxm-sys-native-linux-x86_64.jar   (Linux 64-bit)
            nxm-sys-native-sunos-sparc.jar    (Solaris SPARC)
            nxm-sys-native-windows-x86.jar    (Windows XP 32-bit)
            nxm-sys-native-windows-x86_64.jar (Windows 7  64-bit)

    The following switches apply to JARS:
      /FFILT=    - Filter for files to include/exclude.
      /NOTEST    - Exclude /test directories in the output JAR (since 3.3.4)
      /NODOCS    - Exclude /docs directories in the output JAR (since 3.3.4)

    The default value for /FFILT= are taken from jnlp.file_filter in the
    nxm/<opt>/cfg/build.props file for the option tree. If they are not
    specified for the given option tree, the ones from SYS are used. These
    use the standard mask syntax so that /FFILT="+*.xyz" would mean: "in
    addition to all the files specified in build.props, also include all
    files matching '*.xyz'." Any entries with no '/' are applied to file
    names, entries with a '/' are based on path (e.g. /FFILT="-*/temp/*"
    would exclude any directory named temp and /FFILT="-test/*" would
    exclude anything under the test area of the option tree).

  JNLP <name> <opts> <dest> <codebase>
    Generate a skeleton jnlp file, called <name>.jnlp containing the minimum
    information to run a NeXtMidas command via JNLP. The macro that is executed
    is specified by the name parameter. The file will be written into the <dest>
    directory.

    <name>     - Root name of the JNLP file (case-sensitive) [DEF=BOGUS]
    <opts>     - A "|" delimited string specifying the option trees that are
                 required by the jnlp.  [DEF="SYS"]
    <dest>     - The name of a destination directory. [DEF=$NMROOT/jars]
    <codebase> - Specifies the codebase  for the application. Codebase is also
                 used as base URL for all relative URLs in href attributes.
                 [DEF="http://localhost/nmroot/jars"]
    <href>     - The "href" URL for the JNLP file (attribute of the <jnlp> tag).
                 The URL from which remote users access this application.
                 [DEF="<codebase>/<name>.jnlp"]

  JNLP/GUI   <name> <properties>
    Brings up a GUI with which to build the JNLP file. See JNLP/TABLE for a list
    of the properties that can be customized before presenting GUI to user.

  JNLP/TABLE <name> <properties>
    Generates a JNLP file based on a table of properties.
    <name>       - Root name of the JNLP file (case-sensitive) [DEF=BOGUS]
    <properties> - Table of properties for JNLP file generation.

    The table should specify the following properties.
      CODEBASE   - The "codebase" for the JNLP jars and is also  [Required]
                   used as the base URL for all relative URLs in
                   href attributes.
      JNLPHREF   - The "href" URL for the JNLP file.             [Required]
      COMMAND    - The name of the command and arguments to run. [Required]
      USENATIVE  - Enables native libraries (TRUE/FALSE).        [DEF=FALSE]
      OPTS       - The option trees required.                    [DEF=SYS]
      TITLE      - Title of the application.                     [DEF="MyApp"]
      DESCR      - Description of the application.               [DEF=title]
      SHORTDESCR - Short description of the application.         [DEF=descr]
      VENDOR     - The ID of the vendor.                         [DEF="ICE"]
      HOMEPAGE   - The homepage of the application.       [DEF="nextmidas.html"]
      JAVAVER    - The Java versions that can be used.           [DEF="1.7+"]

  OPER
    Generate math operators code (see nxm.sys.libm.Generate for documentation on
    the doOpers method) as defined in $NMROOT/nxm/sys/libm/Operators.cnf file.

  SIGN <name> <keystoreTbl>
    Signs the named jar file.
      <name> path to jarfile to sign.
      <keystoreTbl> Optional config table to use a custom jar signing keystore.
             If not set, default self-signed certificate will be used.
             See "Using Custom Keystore" section for details, but here are the
             common required keys to set.                          (Since 3.5.1)
               {KEYSTOREFILE="custom.jks",KEYSTOREPASS="pw",KEYALIAS="keyAlias"}


Keystore: Using Custom Keystore to sign jars                       (Since 3.5.1)
  Several functions (e.g. BUN, JARS, SIGN) allow an optional keystore config
  table to specify a custom java keystore for signing jar files.

  The custom keystore configuration table (i.e. <keystoreTbl>) should include:
    Key          | Value description
    -------------+--------------------------------------------------------------
    KEYSTOREFILE | path to custom keystore file
    KEYSTOREPASS | password for keystore file [1,3]
    KEYALIAS     | alias to private key/entity inside keystore file
    KEYPASS      | private key password (optional if same as KEYSTOREPASS) [1-3]
    MOREOPTIONS  | more options to add to executed jarsigner command (optional)

    Note1: The password shouldn't be specified on the command line or in a
           macro/script unless it is for testing purposes, or you are on a
           secure system.
    Note2: If KEYPASS is different than KEYSTOREPASS, it MUST be provided as the
           jarsigner password prompt for user input is NOT redirected from STDIN
           since it is run in a separate process.
    Note3: If using Java 7+, the password value, can have either one of the
           following prepend: ":env" or ":file", then a space, then the password
           to have jarsigner get the password from an OS environment variable or
           from a file, respectively.

  To use a custom code signing certificate in another format, it MUST be
  imported into a Java keystore file. Java's keytool -importcert option can
  import X.509 v1, v2, and v3 certificates, and PKCS#7 formatted certificate.


Examples:
  1. Generate ALL math operators (under LIBM area)
      nM> GENERATE OPER ALL

  2. Generate the LN (Natural Logarithm) operator (under LIBM area)
      nM> GENERATE OPER LN

  3. Generate the JARs for the DSP tree.
      nM> GENERATE JARS DSP

  4. Generate the JARs for the SYS tree, but exclude any .tmp or .prm files.
      nM> GENERATE JARS SYS /FFILT="-*.tmp|-*.prm"

  5. Generate the JARs for the SYS tree, but add in any .for and .inc files.
      nM> GENERATE JARS SYS /FFILT="+*.for|+*.inc"

  6. Generate the JARs for the AUDIO tree, but do not include any dir that
     is named "sounds".
      nM> GENERATE JARS SYS /DFILT="-sounds"

  7. Generate the JARs for the DSP tree, but put it in "/home/webstart/"
      nM> GENERATE JARS DSP "/home/webstart/"

  8. Generate the JARs for the SYS tree, but skip copying and signing the
     jar files from the JAR area (directory), since this step have
     previously been executed and none of the jar files have changed.
      nM> GENERATE JARS SYS /SKIP="COPYJARS"

  9. Same as example 8 above, but also skip jarring up native OS libraries.
      nM> GENERATE JARS SYS /SKIP="COPYJARS|JARNATIVE"

  10. Generate the JARs for the SYS tree, but exclude /test and /docs
       nM> GENERATE JARS SYS /NOTEST /NODOCS

  11. Generate the JARs for the SYS tree using a customized keystore for
      signing (where keypass is the same as storepass).
       nM> set ksCfgTbl {KEYSTOREFILE="/path/to/custom.jks",KEYSTOREPASS="pw",\
                         KEYALIAS="aliasToKey"}
       nM> GENERATE JARS SYS ,, ksCfgTbl

  12. same as #11 above but keypass is different from storepass and add
      "-verbose" option to jarsigner command.
       nM> set ksCfgTbl {KEYSTOREFILE="/path/to/custom.jks",KEYSTOREPASS="pw",\
                         KEYALIAS="aliasToKey",KEYPASS="diffThanStorePass"}
       nM> GENERATE JARS SYS ,, ksCfgTbl "-verbose"

  13. Sign a jar file.
       nM> GENERATE SIGN /path/to/MyJarFile.jar

  14. Sign a jar file with a customized keystore.
       nM> set tbl {KEYSTOREFILE="custom.jks",KEYSTOREPASS="pw",KEYALIAS="test"}
       nM> GENERATE SIGN MyJarFile.jar ,, tbl

  15. Generate the OSGi bundles for the SYS option tree.
       nM> GENERATE BUNDLE SYS

  16. Generate the bundles for DSP, but put it in "/home/osgibundles/"
       nM> GENERATE BUN DSP "/home/osgibundles/"

  17. Generate the bundles for the SYS tree, but skip bundling source code and
      use custom keystore to sign the jar files.
       nM> set tbl {KEYSTOREFILE="custom.jks",KEYSTOREPASS="pw",KEYALIAS="test"}
       nM> GENERATE BUN SYS ,, tbl /SKIP="BUNDLESOURCE"

  18. Write a JNLP file called shellgui.jnlp into your $NMROOT/jars path that
      will run the shellgui macro and executes the SHELLGUI command when run.
       nM> GENERATE JNLP shellgui

  19. Write a JNLP file called scanner.jnlp into your $NMROOT/jars path that
      relies on the ICE option tree and executes the scanner command when run.
       nM> GENERATE JNLP scanner ice

  20. Write a JNLP file called scanner.jnlp into the directory
      /home/midas/scanner that relies on the ICE option tree and executes
      the scanner command when run.
       nM> GENERATE JNLP scanner ice /home/midas/scanner


SWITCHES:
  /ALLOWEMPTYNATIVEJAR - For FUNC=JARS, create "empty" native placeholder jar
               with .keepme entry even when there are no native libraries.
               Prior to NeXtMidas 3.5.4 this was always true.        [DEF=false]
               This is a provisional switch name subject to change.(Since 3.5.4)
               this defaults to false if there are no native files.
  /ARCH=     - Override the default platform name when creating native JARs.
               Usually used in combination with /OS=.              (Since 3.3.0)
  /DFILT=    - Filter for directories to search (FUNC=JARS option).
  /EDIT      - For FUNC=EXP, launch the editor defined by the result ENV.EDITOR.
  /EMBEDJARS - For FUNC=BUNDLE, embed option tree's jar files under <opt>/jars
               into bundle. [DEF=TRUE]                             (Since 3.3.0)
  /FFILT=    - Filter for files to include (FUNC=JARS|BUNDLE option) for
               standard jar/bundle file creation.
  /NEW       - Overwrite the existing explain file (EXP, EXPStub ONLY)
  /OS=       - Override the default OS name when creating native JARs. Usually
               used in combination with /ARCH=.                    (Since 3.3.0)
  /QUALVER=  - For FUNC=BUNDLE, set qualifier part of version string.
               INTERNAL USE ONLY                        [DEF=null] (Since 3.5.1)
  /ROOT=     - Override the search root when building a JAR file. (This option
               is typically used when searching for native libraries that are
               not in the normal option tree directory structure.) (Since 3.3.0)
  /SKIP=     - For FUNC=JARS, skip specified step(s) options mask value:
                                                                   (Since 2.9.0)
                 JARSTANDARD - Skip standard jar file creation
                 JARNATIVE   - Skip JAR of native library files for current OS
                 COPYJARS    - Skip copying and signing jar files from JAR area
               For FUNC=BUNDLE, skip options mask value:           (Since 3.3.0)
                 BUNSTANDARD - Skip standard OSGi bundle file creation
                 BUNNATIVE   - Skip native libraries OSGi bundle file creation
                 BUNSOURCE   - Skip source code OSGi bundle file creation
  /SIGNOPTIONS= - FUNC=BUNDLE|JARS|SIGN, additional jarsigner options/flags to
               append before jarfile when invoking the command.    (Since 3.5.2)
  /WARN      - Show warnings [DEF=TRUE]

  /KEEP      - DEPRECATED: Only used with FUNC=JAR and FUNC=NJAR.
  /SIGN      - DEPRECATED: Only used with FUNC=JAR and FUNC=NJAR.

SEE ALSO: nxm.sys.libm.Operators.cnf nxm.sys.cfg.build.props