Installation

Document Contents

Items required to install and run the MMTx program and the associated programs:


If you are installing this on a Windows® based machine, open a DOS command window to perform the installation. There is no InstallShield® installation process for this application. Note that on Windows®, shell environment variables have the form %VariableName%, rather than $VariableName as would be seen on in a Unix or bash shell. Installation differences due to platform will be noted below.

Quick guide to the installation process:
  1. Make a top level directory to store the MMTx program. This will become your $MMTX_PATH area.
  2. Go to the Download page from the MMTx homepage.
  3. Download the latest version of MMTx and any of the optional data models into the directory created in #1.
  4. Change directory to the directory created in #1: cd $MMTX_PATH
  5. Run the java jar program on the mmtx_[version].jar file: java sun.tools.jar.Main xf mmtx_[version].jar

    Windows XP users: Unzip this file using winzip, pkzip, or zip! There is a bug in the java jar program that removes file permissions leaving the embedded cygwin executables un-runable.

    NOTE: You don't need to unjar the optional data model files if you downloaded them - they will be processed via the install program.

  6. This will create the nls/mmtx directory under your $MMTX_PATH directory and fill it with all of the program files needed to run the MMTx program.
  7. Now, change to the mmtx directory: cd nls/mmtx
  8. Run the install script: sh ./bin/install.sh

    [On Windows®, run .\bin\install.bat from the DOS command window. Clicking on the script name from the explorer window will not work.]

  9. If you have successfully installed the programs and data, you no longer need the optional data files that you might have downloaded. The *.jar files located in the $MMTX_PATH directory are no longer needed. If you are concerned about disk space, these files may now be deleted.

Detailed description of installation process:

 If you are installing this on a Windows® based machine, open a DOS command window to perform the installation. There is no InstallShield® installation process for this application. Note that on windows, shell environment variables have the form %VariableName%, rather than $VariableName as would be seen on in a Unix or bash shell. Installation differences due to platform will be noted below.

The following section describes the steps you will be going through during the installation process of the MMTx program.

  1. Make a top level directory to store the MMTx program. This will become your $MMTX_PATH area.
  2. Go to the Download page from the MMTx homepage.
  3. Download the latest version of MMTx and any of the optional data models into the directory created in #1.
  4. Change directory to the directory created in #1: cd $MMTX_PATH
  5. Run the java jar program on the mmtx_[version].jar file: jar -xf mmtx_[version].jar If you get a 'Command not found' message when you try this step, then you can access the java class directly with this command: java sun.tools.jar.Main xf mmtx_[version].jar
  6. This will create the nls/mmtx directory under your $MMTX_PATH directory and fill it with all of the program files needed to run the MMTx program.
  7. Now, change to the mmtx directory: cd nls/mmtx
  8. Run the install script: sh bin/install.sh
    [On Windows®, run .\bin\install.bat from the DOS command window. Clicking on the script name from the explorer window will not work.]

    -- The installation program will

    • Validate the environment
    • Set up the config files
    • Set up the bourne or .bat scripts to run MMTx
    • Install the Data File Builder
    • Run an initial test to verify operations
    This install should take no more tha 2 minutes to complete. walk you through the remainder of the installation Click here for a sample run of the installation script.
  9. Attributions

    MMTx uses the following third party software:

    • SleepyCat BerkelyBtree, Java indexing software
    • Jakarta-ORO regular expression software
    • JUnit regression testing software
    • Cygwin, a Linix-like environment for Windows
    • SPECIALIST Lexical Tools
    See the README.TXT file for attributions for each
  10. Validation of the environment
    This step makes sure that you have access to all of the programs necessary to finish the installation process. Specifically, this step verifies that you are running a valid version of Java.
  11. Configuration of the configuration and properties files
    This step sets up paths in the properties files
  12. Creation of the runtime scripts These include the bin/MMTx script to run MMTx from the command line.
  13. Installation the Lexical Tools (LVG) for the Datafile Builder. The Datafile builder generates lexical variants for words and terms found in the custom dataset. It uses LVG to generate these terms.

    A Detail for Windows users only

      The Datafile Builder (DFBuilder) uses CYGWIN Unix tools, when running in Windows. This install includes CYGWIN tools for Windows, and asks to add an entry in the Windows Registry to point to the version of the CYGWIN tools included here.

      If you already have the CYGWIN tools loaded on your machine, answering yes to this question will point the tools to use the version that comes with MMTx.

      WARNING: Answering yest to this question will change a variable in the Registry. Be sure you do not have installed software that will be affected by this change. If you are using any unix untilities like sed or grep, then you may have cygwin tools installed. If you have these tools already installed do not run this script. In particular, this script sets the HKEY_CURRENT_USER\Software\Cygnus Solutions\Cygwin\mounts v2\

      If you already have GNU tools from Cygnus Solutions or other vendors, we can not assure that the Data File Builder scripts will run or create exactly the same output produced by a standard installation. If you get errors while running the scripts due to missing tools (Command not found.) then you may need to download additional CYGWIN packages. The tools distributed with the Data File Builder in mmtx/cygwin are the following packages:

      ash-20011018-1.tar.bz2
      bash-2.05a-2.tar.bz2
      cygwin-1.3.6-6.tar.bz2
      diff.tar.gz
      fileutils-4.1-1.tar.bz2
      grep-2.4.2-1.tar.gz
      gzip-1.3.2-1.tar.bz2
      sed-3.02-1.tar.gz
      sh-utils-2.0-2.tar.gz
      tar-1.13.19-1.tar.gz
      textutils-2.0.16-1.tar.bz2

  14. Running an initial test to verify operations
    The very last thing that the script does is to actually run the MMTx program and compare the results to a previously generated file and tell you whether the installation was successful or not. You are looking for a message similiar to the one below:

    CONGRATULATIONS!! You have successfully installed MMTx

    If there are any problems during the verification, your will receive a description of the problem and suggestions for remedying it.

  • If you have successfully installed the programs and data, you no longer need the optional data files that you might have downloaded. The *.jar files located in the $MMTX_PATH directory are no longer needed. If you are concerned about disk space, these files may now be deleted.

    Installing Tools to Support Data File Builder on the Solaris Platform:

     Use if the Data File Builder module to construct a custom target thesaurus for the Solaris platform requires an installation of GNU utilities. If you do not wish to generate a custom thesaurus and are using one of the provided data models (see the next section for more), you do not need need to do this installation. If you are going to use the Data File Builder, but are not installing on a Solaris platform, you will not need to do this installation.

    In order to assure that the results are consistent, we ask that you run the Data File Builder in an environment with the GNU utilities. The scripts of the Data File Builder module use grep, cut, join, sort, etc. These utilities vary slightly in behavior and options from those found in /bin for Solaris.

    The necessary utilities may be downloaded freely and are installed using the Solaris package manager. Knowledge of the use of pkgadd and root privileges are required to install them but you don't need a C compiler.

    If the GNU utilities are already available on your system you may skip to the Configuring the Shell Environment section below.

    Downloading Software:

    1. Go to Sunfreeware.com (www.sunfreeware.com).
    2. Select your processor and Solaris OS version from the list at the top of the right frame.
    3. Select textutils-2.0 from the list of packages.
    4. Pick the full package, not the source code. Download to a temporary location on your system.
    5. Repeat for the other packages:
      • sed-3.02
      • grep-2.5
        See Sunfreeware.com's Downloading/Installation page for more details.

    Installing GNU Packages:

    Use the tools or commands you are familar with or ask your system administrator to install the packages you downloaded. If you have root privileges then following sample commands may be sufficient. From the directory into which you downloaded the packages, enter:
    • pkgadd -d textutils-2.0-sol8-sparc-local
    • pkgadd -d sed-3.02-sol8-sparc-local
    • pkgadd -d grep-2.5-sol8-sparc-local
    The tool may ask about conflicts or reuse of files. If the questions only concern directories such as /usr/local/bin, then it is probably OK to go ahead.

    Configuring the Shell Environment:

    The GNU utilities were installed above in /usr/local/bin. Before you run BuildDataFiles, you need to run the following command or otheriwse see to it that a 'which grep' returns "/usr/local/bin/grep" and not "/bin/grep" or some other location.
    • setenv PATH /usr/local/bin:$PATH
    See the     Data File Builder Documentation for complete instructions on running BuildDataFiles.

    Loading of optional data models after install:

     This section describes the steps necessary to install optional data models that were either not included in the original installation process or, missing due to errors occurring in the initial installation.
    1. Change directory to the "nls" directory under the directory you created in Step #1 of the installation process: cd $MMTX_PATH/nls In this directory you should see a directory called "mmtx".
    2. If there are any zip files located in this directory, remove them: rm *.zip
    3. Go to the Download page from the MMTx homepage.
    4. Download the optional data models you wish to have loaded into the current directory.

      NOTE: For each year you will need the YYYY_common.zip file along with any of the three models for that year (e.g., YYYY_relaxed_model.zip). You DO NOT need to download the YYYY_common.zip file IF you have already installed one of the three models previously (e.g., during the install process).
    5. Once all of the optional models you wanted loaded have finished downloading, change directory to the mmtx directory: cd mmtx
    6. Run unzip on the optional data model file such as the 2004_relaxed_model.zip or 2004_relaxed_model.zip file:
      > unzip xvf 2004_relaxed_model.zip
      or
      > java sun.tools.jar.Main xvf 2004_relaxed_model.zip
    7. This will add the data model and indexes into the nls/mmtx/data directory under your $MMTX_PATH directory.
    8. Once done, the mmtx program can now use each optional data model by adding one or more parameters to the mmtx command line options.
      • --KSYear=2004
      • --relaxed_model or --moderate_model
      Once successfully installed the *.zip files in the $MMTX_PATH/nls directory are no longer needed. If you are concerned about disk space, these files may now be deleted.