ConvertBot: creates or modifies a file of various formats

2020-04-27T22:04:33Z

creates or modifies a file of various formats

New page

creates or modifies a file of various formats
<pre>
<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

</pre>

[[Category:NXM_Explain]]

GENERATE - Revision history

ConvertBot: creates or modifies a file of various formats