        NeXtMidas Quick Install Guide

Before you install NeXtMidas for the first time, please familiarize
yourself with the system documentation, software license and Java
software requirements discussed below. You should be experienced with the
concepts underlying the MIDAS signal processing family. Fundamental
understanding of signal processing software is also recommended. All
information, illustrations and specifications contained in this guide
are based on the latest product information available at the time of
publication.


DOCUMENTATION
-------------
These instructions assume the NeXtMidas software will be installed in a
directory referred to as $NMROOT.  Documentation for the 'SYS' option
tree  (including Release Notes, explain files) is available in
$NMROOT/htdocs/nextmidas.html. You can view a full set of documentation
after building the system tree in the  "Building NeXtMidas" section below.


SOFTWARE LICENSE
----------------
Use of this software implies that you agree to the terms of the
NeXtMidas license, $NMROOT/nxm/sys/copyright.txt. Please read the
copyright files in the root directory of each installed package
before using it.


SYSTEM REQUIREMENTS
-------------------
These directions assume a Java Software Development Kit (JDK) is
already installed on your system. NeXtMidas requires Java 8u312 or
later. To see what specific version of Java
is installed on your system, type:

  <yourJavaHome>/bin/java -version

To obtain and install Java, go to www.java.oracle.com and download the most
recent Java SE JDK (non-beta version). Do not download the JRE. The Java executables
do NOT need to be in your path to run NeXtMidas.

    IMPORTANT(Windows Only): NeXtMidas will NOT compile on Windows if there are
    spaces in the Java installation pathname. Therefore, the Java Software
    Development Kit (JDK) MUST be installed in a path that contains no spaces
    in the name. The default installation path for Java on Windows may
    look like this  "c:\Program Files\Java\jdk<version>" (note the space in
    "Program Files").  When installing Java, elect a 'Custom' (instead of
    "Typical") installation and 'Browse' to change the installation path to
    "c:\Java\jdk<version>" so that there are no spaces in the pathname.


SYSTEM ADMINISTRATOR
--------------------
The initial installation steps ("Opening the NeXtMidas Distribution"
through "Setting NeXtMidas Environment Variables" may require a System
Administrator to install and configure the software. Once the variables
are set and verified, you can run NeXtMidas on your own.


OPENING THE NEXTMIDAS DISTRIBUTION
-----------------------------------
To install NeXtMidas, copy the zip file to the location where you
wish to put the top directory of the software tree. There is no "standard"
location, so for the purpose of this installation guideline, assume the top
directory is

  /opt/midas/nxm<version>  (Windows:  c:\midas\nxm<version>)

Unpack the file:

  [windows] unzip nxm<version>.zip
  [unix]    tar xzvf nxm<version>.tar.gz

Unpacking NeXtMidas creates an nxm<version> directory (typically referred to as
$NMROOT) and puts all files beneath it.


NEXTMIDAS INSTALLATION
-----------------------
If this is the first time you have installed NeXtMidas on your
machine, you must proceed with the 'First-Time Installation' steps
below.  Otherwise, skip 'Setting NeXtMidas Environment Variables'.



FIRST-TIME INSTALLATION
------------------------
These procedures explain how to establish a user's home and data directories,
which are important the first time NeXtMidas is installed on a machine.


1.  Ensure NeXtMidas directories have been created.

The default directories are defined in $NMROOT/nxm/sys/cfg/nmstartup.mm. You
can either create these directories on your machine or edit the nmstartup.mm
file to contain the directories you want NeXtMidas to use.

    NOTE: You must configure nmstartup.mm for your directory
    structure. In Windows, for example, the data files must be
    installed on the same drive as the NeXtMidas software.

The following steps establish the default settings for the required directories:

Windows:
    c:\midas\data1
    c:\midas\icedisk

Unix:
    mkdir -p /midas/data1
    mkdir -p /midas/icedisk


    Unix Tip:  Be sure to set the ownership of these directories
    appropriately.  For example, create a group called 'midas' in
    which all users are a member.  Then set the ownership of these
    top-level directories to be owned by the 'midas' group:

      chgrp -R midas /midas
      chmod -R g+w /midas


2.  Create a data directory for each user.

NeXtMidas expects to read and write data files for each user in the AUX.1
directory. Therefore, you need a directory for each USER under the AUX.1
directory.

This example creates a user directory for John Smith (whose USER is
"smithj") using the default system directories:

Unix:
   mkdir -p /midas/data1/smithj
   (be sure to set the ownership so the user owns his directory)


3.  Create HOME directories.(Windows Only)

For each user, NeXtMidas writes the execution state files (user command
history, etc.) to the HOME directory.  Additionally, any user-specific NeXtMidas
startup files should be located in the HOME directory. If the directory
specified in HOME does not already exist, it should be created now (use the
Windows Explorer  program). Remember that there can be no spaces anywhere in the
path defined by  HOME.


SETTING NEXTMIDAS ENVIRONMENT VARIABLES
----------------------------------------
NeXtMidas requires several environment variables to be defined before
building or running the software. Create a script or edit
your login script to set the environment variable NMROOT to point to the
top level directory where NeXtMidas is installed. For the purpose of this
installation guideline, let's continue to assume the top directory is
/opt/midas/nxm<version>. You may also set up an alias to easily start
a session. Use the command sequence appropriate for your system.


Unix (run from the C shell):

  setenv JAVAHOME /opt/java/openjdk-17.0.2
  setenv NMROOT /opt/midas/nxm<version>
  alias nmstart 'source $NMROOT/os/unix/nmstart'

  TIP:  Verify the environment variables are set correctly:

    ls $JAVAHOME
    ls $NMROOT


Windows:

  set JAVAHOME=c:\java\jdk<version>
  set NMROOT=C:\nxm<version>
  set NMSTART=%NMROOT%\os\dos\nmstart.bat
  set USER=user_name_with_no_spaces
  set HOME=user_home_directory_path_with_no_spaces

  Windows Notes:
  1) All path names, user names, and directory names used for
     NeXtMidas must not have any spaces in them. All the environment
     variables listed above should NOT CONTAIN ANY SPACES anywhere on the
     right side of the equals sign.   (See the "First-Time Installation"
     section for details on creating directories defined by USER and HOME.)

  2) If you are installing Java or NeXtMidas on a mapped network drive, you
     must use the full path in your environment variables rather than
     the mapped path. For example, if you install NeXtMidas on your
     Z: drive, which is mapped to \\ANetworkComputer\MyDirectory\

     Do this:
     set NMROOT=\\ANetworkComputer\MyDirectory\nxm<version>

     DO NOT do this:
     set NMROOT=Z:\nxm<version>

  TIP:  Verify the environment variables are set correctly:

    dir %JAVAHOME%
    dir %NMROOT%


BUILDING THE NEXTMIDAS BASELINE
-------------------------------
To build the NeXtMidas software, you must execute an initial session.
Once a session is started, build the system tree using the "nm make" command.

  user> nmstart   (%nmstart% on Windows)

A copyright message appears, and then you'll see "NextMidas not built yet."
At the prompt, type:

  user> nm make all

Note: The NeXtMidas configuration is not set to run native code directly from
      a clean install. To run native code immediately following a clean
      installation of NeXtMidas after 'nm make all' is performed exit the
      NeXtMidas shell using 'nmend' and reenter the NeXtMidas shell.

Notes for Building Native Code

Unix platforms: The build scripts are configured to use the local
       compiler to compile all the native code each time the baseline
       is  built.

Windows platforms: The baseline ships with pre-compiled DLLs for
       the SYS and DSP option trees.  For most users, these pre-compiled DLLs are
       sufficient.

Windows Software Developers:  If you are a developer and want to compile
       the native code locally on your Windows machine, you need a GCC
       compiler to compile any option trees that contain native code.
       For details on compiling native code on Windows, refer to
       "Compiling Native Code" in the NeXtMidas User's Guide.


BUILDING THE USER-CONTRIBUTED LIBRARY (UCL) (OPTIONAL)
------------------------------------------------------
Building the User-Contributed Library (UCL) option tree not only verifies the
pre-ship test, but provides a software developer with a template for building
option trees. You may choose to design your own directory structure, or use
the UCL option tree as a depository. To compile the UCL, type:

  nM> path add ucl
  nM> make all ucl

Now that the system tree is built, you may view the NeXtMidas HTML documentation
(including release notes and explain files) in a web browser by opening the
NeXtMidas home page: $NMROOT/htdocs/nextmidas.html.


TESTING NEXTMIDAS
------------------
Your computer system is now ready to use NeXtMidas. To verify a successful
installation of NeXtMidas, run the confidence test:

  nM> confidence

This generates a series of non-interactive pass/fail tests and outputs the
results with a summary.  The confidence test is considered successful
if "0 failed" is reported in the summary at the bottom.

NOTE: This message indicates nmstartup.mm was not set to the right directory
(See note in "First-Time Installation" Step 1):

  Warning: CANNOT PERFORM TESTS WRITE PATH /MIDAS/DATA1<user> DOES NOT EXIST

Information on additional confidence tests can be found in the
confidence explain file:

  nM> help confidence

Follow the instructions given in the output from the macro for the tests you
would like to run.

When you complete the test segment, exit the shell:

  nM> exit


RUNNING NEXTMIDAS
------------------
This section explains how to run the NeXtMidas software. If you get error
messages, refer to the "Troubleshooting" section of this document.

Type nm to enter the shell. This puts you at the nM> prompt.
Type exit at the nM> prompt to exit the shell.
This simple example shows how to enter the shell, run a command and exit the
shell:

  user> nm
  nM>  plot apenny
    (you should see the penny in a separate window.  Click
    the X in the top right corner to dismiss the plot.)
  nM> exit


To run the same plot apenny command as a single ("one-shot") NeXtMidas command
from the operating system prompt, precede the command with nm
and a space. For example:

  user> nm plot apenny
    (you should see the penny in a window.  Click the X
    in the top right corner to dismiss the plot.)
  user>


To remove all NeXtMidas variables from the execution window where
NeXtMidas was started:

  user> nmend

  TIP:  If you want to re-start NeXtMidas in the window, you must
  run nmstart again before starting NeXtMidas.



INSTALLATION COMPLETE
----------------------
You installed NeXtMidas, ran the confidence test to verify the baseline
content, brought up the NeXtMidas shell to run commands, terminated the
NeXtMidas shell, and ran a one-shot command outside the shell. As a novice
NeXtMidas user, your are ready to move on.


ON-LINE HELP
------------
nextmidas.com has current contact and release distribution information.
The on-line help described below, is currently not available:

From the NeXtMidas homepage (http://nextmidas.com), go to the
NeXtMidas Documentation page. This on-line help system provides an overview of NeXtMidas
concepts and capabilities. Using HELP/GUI is another simple way for beginners to
learn  their way around NeXtMidas; this graphic interface also lets Midas
veterans look up a detail or two without interrupting their current NeXtMidas
session.

  user> nm
  nM> help/gui

Advanced programmers who want to customize the standard NeXtMidas software
should read "Customizing NeXtMidas" in the NeXtMidas User's Guide. It provides
several enhancement features to tailor NeXtMidas for your specific needs.

=================================
TROUBLESHOOTING
=================================

1. Improving Java Runtime Performance
   ----------------------------------

1a. Increasing Initial Java Memory Size

For large memory-intensive applications (e.g. displaying large MIDAS
files via the LIST command), runtime performance can be improved by
starting the Java interpreter with a larger amount of memory. The
initial memory allocated to the Java Virtual Machine (JVM) can be
increased from the default values by defining the operating system
environment variable NM_USER_JVM_FLAGS correctly.

Unix:
  setenv NM_USER_JVM_FLAGS "-Xms<init_memory>[k|m]"
Windows:
  set NM_USER_JVM_FLAGS=-Xms<init_memory>[k|m]

where <init_memory> specifies the initial size of memory allocation pool.
By default <init_memory> is specified in bytes. This value must be a multiple
of 1024 greater than 1 MB. Append the letter k or K to indicate kilobytes, or
m or M to indicate megabytes.


1b. Increasing Maximum Java Memory Size

The maximum memory size the interpreter uses for dynamically allocated
objects and arrays can be increased by adding a JVM argument to the
NM_USER_JVM_FLAGS environment variable, i.e.:

Unix:
  setenv NM_USER_JVM_FLAGS "-Xmx<max_memory>[k|m]"

Windows:
  set NM_USER_JVM_FLAGS=-Xmx<max_memory>[k|m]

where <max_memory> specifies the maximum size in bytes. This value must
be a multiple of 1024 greater than 2 MB. Append the letter k or K to indicate
kilobytes, or m or M to indicate megabytes. The default is 256 MB.


1c. Increasing Both Memory and Heap Size

Memory-modifying arguments can be combined in the NM_USER_JVM_FLAGS
environment variable, e.g.:

Unix:
  setenv NM_USER_JVM_FLAGS "-Xms256m -Xmx512m"
Windows:
  set NM_USER_JVM_FLAGS=-Xms256m -Xmx512m

2. "font.properties not found" on Linux
   ---------------------------

Description:
All standard distributions of Linux may not include Adobe fonts as defined in the
font.properties file in the JDK. When Linux tries to access the Adobe fonts,
the "font.properties not found" is displayed in the window where NeXtMidas was
started.

Do I have the problem?
Bring up a NeXtMidas plot:

  nM>plot apenny


You have the problem if one or more of the following messages
appear in the window where you started the NeXtMidas software:

  "Font specified in font.properties not found
          [--symbol-medium-r-normal--*-%d-*-*-p-*-adobe-fontspecific]"

Solution:
Edit the font.properties file in the J2SDK you are
using and comment out all references to Adobe fonts. Save the original
font.properties and then edit the file:

  cd <yourJavaHome>/jre/lib
  cp font.properties  font.properties.ORIG
  nedit font.properties

Place a # (pound sign) in front of each line in the file that
contains "adobe-fontspecific" in the line. Save the file.

Note:  This must be done each time a new JDK is utilized. It is suggested
that the old version of the font.properties file be backed-up to
font.properties.old.
