ConvertBot: displays or defines an option tree path

2020-04-27T22:05:07Z

displays or defines an option tree path

New page

displays or defines an option tree path
<pre>
<NAME> - Name of the option tree (or * to define all under specified path)
<PATH> - Path to the named option tree (or physical path when /CREATE
is used and OPT.name is a link)

This command is used to define a NeXtMidas option tree path. Option trees in
NeXtMidas are implemented using Java packages. The root package name is "nxm",
followed by the "option name", and then functional subdirectories. Use the
/CREATE switch to create a new option tree (see below).

When OPTION is used with no arguments, it lists all configured option trees.
When used with just <NAME> it shows the location of the named option tree
(see below for examples).

NOTE: The association of an option name with a particular path lasts only
as long as your NeXtMidas session. When you log in the next day, that mapping
will be gone. Therefore, OPTION <optname> <path> definitions which are
intended to be permanent are usually put in the user's %nmstartup macro.

Option trees are typically set up in the user's nmstartup.mm macro, for example:
startmacro
option ice "/user/xmopts/ice279/"
option geo "/user/geo100/nxm/geo/"
path set ice geo
endmacro

Option trees located under $NMROOT/nxm or with a link from $NMROOT/nxm/<opt>
(see below) are automatically added to the list of options and can be viewed
using OPTION with no arguments.

REQUIRED DIRECTORY STRUCTURE
----------------------------
The Java package facility requires the source file directories to mirror the
package naming scheme. The option path must point to a directory that contains
an "nxm" directory with a directory below this MATCHING the option name.

The recommended approach is to create a base directory to hold all application
required option trees under an "nxm" directory structure outside $NMROOT.
Creating your option trees in a separate directory will allow you to easily
upgrade and/or switch NeXtMidas versions without having to modify anything
under the NeXtMidas baseline. For example:
/path/to/nmopts
+- nxm
| +- myopt
| | +- cfg
| | +- mcr
| | +- prim
| | +- test
| +- coolapp
| | +- cfg
| | ...
| +- yetanotheropt --> ../yetanotheropt102
|
+- yetanotheropt102 (version 1.0.2 of user option tree)
| +- cfg
| ...

Then define the above option trees:
nM> option myopt /path/to/nmopts/nxm/myopt
nM> option coolapp /path/to/nmopts/nxm/coolapp
nM> option yetanotheropt /path/to/nmopts/nxm/yetanotheropt
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
** Notice how the <optname> must match the directory basename **

Another approach on Unix is to have a symbolic link from $NMROOT/nxm/<optname>
to the base directory of the option tree (this is the recommend approach on
Unix since most IDEs will find these option trees automatically). For example:
$NMROOT
+- nxm
+- myopt --> /home/smith/myopt123
+- sys <existing>
+- ucl <existing>

/home/smith/myopt123
+- cfg
+- prim
+- mcr

On Unix systems, this may be a also be done via a "backlink", pointing back to
the top of the tree branching off to the areas inc/lib/cfg/prim/etc (this
approach is STRONGLY DISCOURAGED and WILL CAUSE ECLIPSE, JBUILDER, ETC. TO
CRASH). For example:
/home/smith/myopt123
+- nxm
| +- myopt --> ../ <recursive link>
+- cfg
+- prim
+- mcr

On Windows (which does not have symbolic links prior to Windows Vista and the
mklink and junction commands) the option tree must be physically located under
a nxm directory and have the option tree name as its base. The version.txt
file in the option tree's root directory is the only means of identifying the
option tree's version number. This approach works on all systems
(Windows/Unix/etc). For example:
/home/smith/myopt123
+- nxm
+- myopt
+- cfg
+- prim
+- mcr
JAR FILES
---------
To use a raw Java jar (or directory of classes) with NeXtMidas, simply define
the full path name as the option then use the PATH command to add this option
to the path. For example:
nM> option JYTHON /path/to/jython.jar
nM> path add JYTHON

"OPTION" vs "RES OPT"
---------------------
When you use this OPTION command it lists ALL option trees and shows the base
directory of the option tree (this is the directory that "cfg" and "prim" are
in). The OPTION command also shows any links used (Unix only).

When you use RES OPT you are shown only the option trees not located under
$NMROOT (option trees using a link pointing from $NMROOT/nxm/<opt> to the
location of the option tree are considered to be under $NMROOT). Also
RES OPT will show the root directory of the option tree (this is the directory
that "nxm" is in).

The reason for this difference is both practical and historical. The OPTION
command shows the directory that users will be working in (when you use
"nmd . <opt>" this is where you go). Using RES OPT shows the directory that
Java needs to use on the classpath (RES OPT excludes option trees under
$NMROOT since it is already part of the classpath).

In general users should only use OPTION to find out where an option tree is
located. Macros that need to find the location of an option tree should NOT
use RES.<opt> since it does not include all option trees and is not
platform-independent (future releases of NeXtMidas may deprecate use of the
OPT table). Macro users should use the following for getting directories in
an option tree:
nM> invoke path nxm.sys.lib.OptionTree.getOptPath(<opt>,<area>)

CREATING TREES AUTOMATICALLY
----------------------------
The /CREATE switch may be used to create the option tree defined by the
result parameter OPT.<optname> where tree is the name of the option tree.
There are a number of options for creating your option tree ALL of which must
obey the Java package naming rule.

1. Create a new option tree called myopt (this is the recommend approach on
Windows and works well on Unix too). This approach also allows you to
easily upgrade your NeXtMidas version without having to modify it:
nM> option/create myopt /home/smith/myopt123/nxm/myopt

Creates the following:
/home/smith/myopt123
+- nxm
+- myopt
+- cfg
| +- commands.cnf
+- prim
+- mcr

2. (Unix Only) Create a "flat" option tree (similar to X-Midas) called myopt
with a symbolic link to it from $NMROOT/nxm/<opt>. This approach is no
longer recommended since it requires you to create a symbolic link under
the NeXtMidas baseline (under $NMROOT/nxm/ directory):
nM> option/create/link=nxm myopt /home/smith/myopt123

Creates the following:
$NMROOT
+- nxm
+- myopt --> /home/smith/myopt123
+- sys <existing>
+- ucl <existing>

/home/smith/myopt123
+- cfg
| +- commands.cnf
+- prim
+- mcr

3. (Unix Only) Create a link outside of $NMROOT/nxm pointing to the physical
option tree path (this works well for existing X-Midas option trees).

nM> option/create/link="/home/midas/nxm/" myopt /home/midas/myopt123

4. (Unix Only) Create a new option tree called myopt with a recursive link.
This keeps the option tree "flat" (X-Midas style) but uses a "back-link"
to maintain the Java package names.
(** THIS WILL CAUSE ECLIPSE, JBUILDER, ETC. TO CRASH **)

nM> option/create/link=recursive myopt /home/smith/myopt123

Creates the following:
/home/smith/myopt123
+- nxm
| +- myopt --> ../ <recursive link>
+- cfg
| +- commands.cnf
+- prim
+- mcr

5. The entire option tree can be placed under $NMROOT/nxm/ (like the option
trees that come with NeXtMidas). This will work on all platforms, but is
strongly discouraged since your option tree may be lost when you upgrade
to a new version of NeXtMidas; hence, there is no OPTION/CREATE that will
do this for you.

CONFIGURING EXISTING X-MIDAS OPTION TREES (Unix Only)
-----------------------------------------------------
There are a number of ways to configure an existing X-Midas option tree
for NeXtMidas use.

1. The recommended approach is to create a base directory to hold your option
trees under an "nxm" directory structure outside $NMROOT (see "REQUIRED
DIRECTORY STRUCTURE" section above).

2. Create a link under $NMROOT/nxm which points to the existing option tree
(this is not recommend since it requires you to modify your NeXtMidas
distribution directory).

nM> opt/create/link=NXM myopt "/home/midas/myxmopt123"

3. Create a directory called 'nxm' which is at the same level as the existing
option tree. Then place a link under 'nxm' pointing to the existing tree.
(this approach is DISCOURAGED since it can cause Eclipse and JBuilder
to crash if used to edit the NeXtMidas files in the option tree).

nM> opt/create/link="/home/midas/xmopts/nxm/" myxmopt &
"/home/midas/xmopts/myxmopt123"

USE STAR OPTION NAME (to define all option tree under specified path):
----------------------------------------------------------------------
All option trees under a specified path can be defined using the star "*"
character as the name for the option tree. This will ignore sub-directories
with dots (since that is not a valid option tree name). Since NeXtMidas 2.9.3.

nM> option * /path/to/nmopts/nxm/

The above will define the following option trees using example
directory structure from the REQUIRED DIRECTORY STRUCTURE section above:
myopt = /path/to/nmopts/nxm/myopt
coolapp = /path/to/nmopts/nxm/coolapp
yetanotheropt = /path/to/nmopts/nxm/yetanotheropt

FIND and DEFINE OPTION TREE from CLASSPATH: (Since NeXtMidas 3.3.0)
-------------------------------------------
Option trees in the CLASSPATH can be found via the /FIND switch or found and
defined using reserved "CLASSPATH" (upper-case) word for the <path> argument.

1. Find and define option tree from CLASSPATH (errors if MYOPT is not found)
nM> option MYOPT "CLASSPATH"

2. Find option tree and save it's URL/path to results, and define it if found:
option/find=myres MYOPT
if myres NisNull then
option MYOPT myres
path add MYOPT
else
warning "Unable to find MYOPT option tree..."
endif

EXAMPLES:
(See above for examples of using OPTION/CREATE to create option trees.)

1. Show all configured option trees:
nM> OPTION
Available Option Trees (<n> = index on path):
AUDIO = /home/smith/nxm240/nxm/audio/
<1> DSP = /home/smith/nxm240/nxm/dsp/
<2> HWC = /home/smith/nxm240/nxm/hwc/
MAP = /home/smith/nxm240/nxm/map/ -> /home/smith/map120/
<3> SYS = /home/smith/nxm240/nxm/sys/
UCL = /home/smith/nxm240/nxm/ucl/

2. Show a single option tree:
nM> OPTION UCL
UCL = /home/smith/nxm240/nxm/ucl/

3. Define an option tree definition for MYOPT located under the
/midas/nmopts/nxm/myopt directory:
nM> option MYOPT /midas/nmopts/nxm/myopt/

4. Undefine (remove) the MAP option tree definition
nM> option/delete map

5. Define all option trees under the /path/to/nmopts/nxm/ directory.
nM> option * /path/to/nmopts/nxm/

SWITCHES:
/CREATE - Creates the subdirectories and a stub commands.cnf for the
option tree.
/DELETE - Logically remove the specified option tree definition. The
directory is NOT removed; that must be done explicitly with the
appropriate operating system commands. I.e. this will NOT delete
option trees created with links in $NMROOT. (Since 2.7.0)
/FIND=<res>- Find <name> option tree in CLASSPATH and save path to specified
results label if specified. (Since 3.3.0)
/GET=<res> - Get a comma separated list of ALL defined option trees (not
just those on the path)
/INFO=<res>- Get option tree information parsed from version.txt/manifest.mf
such as version and required option trees. If no results label is
given then info is displayed to terminal. (Since 3.3.0)
See nxm.sys.lib.OptionTree.getInfo(..) for details of output.
/LINK= - Creates a link named by the given option tree when using /CREATE.
[DEF=null]
Options are:
NXM - Creates a link in $NMROOT/nxm
BACK - TBD - Creates an nxm directory with a back link to the
option tree directory
<path> - Creates a link in the given <path>. The path must be
quoted, i.e. inside double quotes and should generally
end with a "nxm" directory name.
/NOEXIT - Prevent class reloading via shell restart when option tree is
defined that has ever been added to the PATH. (Since 2.9.3)
[DEF=FALSE in command-line;TRUE in macro]

See Also: PATH, CONFIGURE

</pre>

[[Category:NXM_Explain]]

OPTION - Revision history

ConvertBot: displays or defines an option tree path