# NeXtMidas Installation Guide

## Introduction

Before you install NeXtMidas for the first time, please familiarize yourself with the system documentation, software license and Java software requirements discussed in this introduction. 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 and explain files) is available in `$NMROOT/htdocs/nextmidas.html`. You can view a full set of documentation after building the system tree in the section titled Build the NeXtMidas Baseline.

### 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 Requirement

This document assumes a Java Development Kit (JDK) is already installed on your system. NeXtMidas requires Java 1.8_0_312 or later. To see what specific version of Java is installed on your system, type:

    <yourJavaHome>/bin/java -version

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

NOTE: For any text in this document containing the following notation, you must substitute the appropriate update version number for the notation: `<version>`.

For example, if you are installing version 4.0.2 of the NeXtMidas baseline, the following file name:

    nxm<version>.zip

becomes:

    nxm402.zip

IMPORTANT: (Windows Requirement Only)

NeXtMidas will NOT compile on Windows if there are spaces in the Java installation pathname. Therefore, the JDK must be installed in a path that contains no spaces. The default installation path for Java on Windows may look like this:

    c:\Program Files\Java\jdk<version>

To ensure Java is installed without spaces in the pathname, select a Custom (instead of Typical) installation and Browse to change the installation path to:

    c:\Java\jdk<version>

## Installing NeXtMidas

This section explains how to download and install the NeXtMidas code. It directs you through the build, test, and run commands to confirm successful installation. Throughout the instructions, TIPs and NOTEs provide guidance through possible obstacles. If you encounter any problems during or after installation, please check Troubleshooting Tips for solutions to common issues.

NOTE: The initial installation steps (Where to Get the NeXtMidas Code through Set NeXtMidas Environment Variables) require a System Administrator to install and configure the software. Once the variables are set and verified, you can run NeXtMidas on your own.

### Where to Get the NeXtMidas Code

Information on obtaining the NeXtMidas code is available at http://nextmidas.com/. Choose a baseline version and select the appropriate platform (Unix or Windows) distribution file.

### Open the NeXtMidas Distribution

To install NeXtMidas, copy the archive 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>`).

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

To expand the archive file in Windows, use the zip utility:

    unzip nxm<version>.zip

To expand the archive file in Unix, use the `tar` utility:

    For tar.gz archive:
      tar xzvf nxm<version>.tar.gz (-or-)
      gunzip -c nxm<version>.tar.gz | tar xvf -

    For tar.xz archive:
      tar xJvf nxm<version>.tar.xz (RHEL/CentOS 6+ using capital 'J' option) (-or-)
      unxz -c nxm<version>.tar.xz | tar xvf -

To expand a JAR archive file (used for NeXtMidas snapshots) in Windows or Unix, use the `jar` tool (this is part of Java):

    jar xvf nxm<version>.jar

NOTE: If this is the first time NeXtMidas is installed on this particular machine, you must proceed with First-Time Installation. Otherwise, skip to the section titled Set 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. 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. Remember, there can be no spaces anywhere in the path defined by HOME.

2. Ensure NeXtMidas directories are created.

   The default directories are defined in the `$NMROOT/nxm/sys/cfg/nmstartup.mm` configuration file. You can either create these directories on your machine or make a copy of `nmstartup.mm` in your home directory and edit it to contain the directories you want NeXtMidas to use (the file in your home directory is automatically loaded by NeXtMidas and overrides the default settings).

   NOTE: You must configure `nmstartup.mm` for your directory structure. Insert the following line in the file: `debug on trace`. In Windows, if the data files are not on the same drive as the NeXtMidas software you need to specify the drive letter for each directory used.

   The following steps establish default settings for the required directories:

   - Windows

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

   - Unix

         mkdir -p /midas/data1
         mkdir -p /midas/icedisk

     TIP: 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 directories to be owned by the `midas` group:

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

3. Create a data directory for each user.

   NeXtMidas expects to read and write data files for each user in the `AUX.1` directory (`AUX.1` is the NeXtMidas identifier for the first auxiliary, or user, directory). Therefore, you need a directory for each user under the `AUX.1` directory.

   This example creates user directories for John Smith (`smithj`) and Sarah Kim (`kims`) using the default system directory (`/midas/data1/`):

   - Unix

         mkdir -p /midas/data1/smithj
         mkdir -p /midas/data1/kims

     NOTE: Set the ownership so the user owns their own directory.

         chown smithj:smithj /midas/data1/smithj
         chown kims:kims /midas/data1/kims

### Set 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

- It is recommended to set the default shell to C-shell (either `csh` or `tcsh`) to run NeXtMidas

  Set the `JAVAHOME` variable to point to the Java installation directory:

      setenv JAVAHOME /opt/jdk1.8.0_312

  Set the NeXtMidas `NMROOT` environment variable:

      setenv NMROOT /opt/midas/nxm<version>

  Optional: Alias `nmstart` to simplify starting NeXtMidas (note usage of single-quote):

      alias nmstart 'source $NMROOT/os/unix/nmstart'

- To run NeXtMidas with Bash (since NeXtMidas 3.8.0)

  Set the `JAVAHOME` variable to point to the Java installation directory:

      export JAVAHOME=/opt/jdk1.8.0_312

  Set the NeXtMidas `NMROOT` environment variable:

      export NMROOT=/opt/midas/nxm<version>

  Optional: Alias `nmstart` to simplify starting NeXtMidas (note usage of single-quote):

      alias nmstart='source $NMROOT/os/unix/nmstart.sh'

- TIP: Verify the environment variables are set correctly:

      ls $JAVAHOME
      ls $NMROOT

- Windows

  A Windows Batch File is provided that may be used in place of manual Windows environment variable configuration. Click here for more information, or continue with the following tutorial in order to manually configure NeXtMidas environment variables for Windows.

  Set the `JAVAHOME` variable to point to the Java installation directory:

      set JAVAHOME=c:\java\jdk<version>

  Set the NeXtMidas `NMROOT` environment variable:

      set NMROOT=c:\midas\nxm<version>

  Set the user name (`USER`) and the user's home directory (`HOME`):

      set USER=user_name
      set HOME=user_home_directory

  Note that neither the user name or the user's home directory contain spaces.

  Optional: Set `NMSTART` to simplify starting NeXtMidas:

      set NMSTART=%NMROOT%\os\dos\nmstart.bat

  Important Windows Note: All path names, user names and directory names used for NeXtMidas can not have any spaces in them. All the environment variables listed above should NOT CONTAIN SPACES anywhere on the right side of the equals sign (=). The section, First-Time Installation provides more details on creating directories defined by `USER` and `HOME`.

  TIP: Verify the environment variables are set correctly:

      dir %JAVAHOME%
      dir %NMROOT%

- Windows Batch File

  A sample batch script has been provided with the NeXtMidas distribution that simplifies the configuration and startup of NeXtMidas. The batch file is located at:
  `%NMROOT%\os\dos\runNeXtMidas.bat.sample`.

  To use the batch file to run NeXtMidas, first copy the
  `%NMROOT%\os\dos\runNeXtMidas.bat.sample` file to your `C:\midas\nxm<version>` directory and rename the file to `runNeXtMidas411.bat`.

      copy C:\midas\nxm<version>\os\dos\runNeXtMidas.bat.sample
                C:\midas\nxm<version>\runNeXtMidas411.bat

  Open the newly copied `runNeXtMidas411.bat` file with your favorite text editor and replace `JAVAHOME` and `NMROOT` values using the instructions below.

  On line 13 of `runNeXtMidas411.bat`, set the `JAVAHOME` variable to point to the Java installation directory:

      set JAVAHOME=c:\java\jdk<version>

  On line 14 of `runNeXtMidas411.bat`, set the NeXtMidas `NMROOT` environment variable:

      set NMROOT=c:\midas\nxm<version>

  Once finished, you may simply run the `runNeXtMidas411.bat` conveniently as a Windows shortcut, via Windows Explorer, or through the DOS command prompt in place of configuring and typing `NMSTART`.

      C:\midas\nxm<version>\runNeXtMidas411.bat

### Build the NeXtMidas Baseline

To build the NeXtMidas software, you must start an initial session. Once a session is started, build the system tree using the "`nm make`" command:

- Unix

      nmstart
      nm make all

- Windows

      %NMSTART%
      nm make all

(After running `nmstart` a copyright message appears, followed by "NeXtMidas not built yet.")

Notes for Building Native Code

- Unix

  The build scripts are configured for the local GNU C Compiler (`gcc`) to compile all the native code each time the baseline is built. To use an alternate compiler, see the NeXtMidas User's Guide for details.

- Windows

  The baseline ships with pre-compiled DLLs for the `SYS` and `DSP` option trees. For most users, these pre-compiled DLLs are sufficient. However, if you are a Windows software developer and want to compile the native code locally on your Windows machine, you need a copy of the GNU C Compiler (`gcc`) compiler to compile any option trees that contain native code. For details on compiling native code locally on Windows, refer to the appropriate section in the NeXtMidas User's Guide.

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

### Build 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`, enter the NeXtMidas shell and type:

    nM> path add ucl
    nM> make all ucl

### Test NeXtMidas

Your computer system is now ready to use NeXtMidas. To verify a successful installation of NeXtMidas, enter the NeXtMidas shell (using `nm`) and run the automated confidence tests:

    nm
    nM> confidence

This runs a series of non-interactive PASS/FAIL tests and summarizes the results. The confidence test is considered successful if the summary ends with "`ALL TESTS PASSED`."

NOTE: The following message indicates nmstartup.mm was not set to the right directory (see IMPORTANT note in the First-Time Installation section):

    WARNING: CANNOT PERFORM TESTS WRITE PATH /MIDAS/DATA1/<USER> DOES NOT EXIST

Information to run a more interactive set of tests is located in the confidence explain file:

    nM> help confidence

When you complete the test segment, exit the shell:

    nM> exit

### Run NeXtMidas

This section explains how to run the NeXtMidas software. If you get error messages, check Troubleshooting Tips about resolving common problems.

To enter the NeXtMidas shell type `nm`. This puts you at the `nM>` prompt.

To exit the shell, type `exit` at the `nM>` prompt.

This simple example shows how to enter the shell, run a command and exit the shell:

1. Start the shell.

       user> nm

2. Plot a file.

       nM> plot apenny

   A separate window opens with a picture of President Lincoln on the front of a penny. Clicking on the `X` in the upper right corner of the plot closes the window and returns you to the prompt.
3. Exit the shell:

       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:

    user> nm plot apenny

To remove all NeXtMidas variables from the execution window (which were created by the `nmstart` script), type "`nmend`" at the prompt:

    user> nmend

To restart NeXtMidas in the window, run `nmstart` again:

    user> nmstart

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, you are ready to move on.

### On-Line Help

From the NeXtMidas homepage ( http://nextmidas.com/), go to the NeXtMidas Help page or view the local copy (which includes all installed option trees) at `$NMROOT/htdocs/help/index.html`. This on-line help system provides an overview of NeXtMidas concepts and capabilities. Using `HELP/GUI` command is another simple way for beginners to learn their way around NeXtMidas; this graphic interface lets anyone 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 the appropriate sections in the NeXtMidas User's Guide. It provides several enhancement features to tailor NeXtMidas for your specific needs.

## Troubleshooting Tips

This section provides tips for working around common problems that may occur during or following installation.

### Invalid Escape Sequence Errors (Windows Only)

NeXtMidas recognizes the backslash ("\") as the start of an escape sequence. This could cause problems with existing Windows macros that have hard-coded a Windows path using backslashes as the path separator. This issue can be resolved in two ways:

1. (Recommended) In each case that is causing issues, escape the backslash, e.g. the String "my\windows\path" should be written as "my\\windows\\path"
2. Disable the functionality, both in the environment and in NeXtMidas Tables:

           nM> env set IOOptions +DisableEscapeSequences
           nM> env set DefaultTableFlags +DisableEscapeSequences

### Improve Runtime Performance

For large, memory-intensive applications (e.g. displaying large Midas files with the `LIST` command), you can improve runtime performance by starting the Java interpreter with a larger amount of memory.

1. Increase Initial Java Memory Size:

   The initial memory allocated to the Java Virtual Machine (JVM) is increased from the default values by defining the operating system environment variable `NM_USER_JVM_FLAGS`:

   - Unix

         setenv NM_USER_JVM_FLAGS "-Xms<init_memory>[k|m]"

   - Windows

         set NM_USER_JVM_FLAGS=-Xms<init_memory>[k|m]

   `<init_memory>` specifies the initial size of the 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. The default value is 2 MB.
2. Increase Maximum Java Memory Size:

   The maximum memory size the interpreter uses for dynamically allocated objects and arrays is increased by adding a JVM argument to the `NM_USER_JVM_FLAGS` environment variable:

   - Unix

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

   - Windows

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

   `<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 value is typically 64 MB.
3. Increase Both Initial Memory and Maximum Memory Size:

   Memory modifying arguments are combined in the `NM_USER_JVM_FLAGS` environment variable. These examples increase both initial and maximum to 256 MB:

   - Unix

         setenv NM_USER_JVM_FLAGS "-Xms256m -Xmx256m"

   - Windows

         set NM_USER_JVM_FLAGS=-Xms256m -Xmx256m