OPTION
Jump to navigation
Jump to search
displays or defines an option tree path
<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