Pathway Tools Installation Guide -- Linux and MacOS X (Intel only)

The following instructions are for the supported UNIX systems, namely modern flavors of Linux x86, Linux x86_64, and MacOS X 10.4 and 10.5 (Intel only).

Note: Pathway Tools release 12.5 and later include libXm.so with the distribution, so installing OpenMotif should not be necessary.

Contents


Installing on MacOS X

IMPORTANT notes for MacOS X:

  1. Pathway Tools is known to run on MacOS X 10.4 and higher, Intel only
  2. Pathway Tools requires that X11 be installed. You can tell if you have X11 installed by clicking on the Finder menu Go->Utilities. You should see an entry for X11. If not:
    • On Snow Leopard (MacOS 10.6) X11 is installed by default. If for some reason it is not installed, you must install it from the Apple install DVD (run the "Optional Installs" installer).
    • On Leopard (MacOS 10.5), if X11 is not installed, the Pathway Tools installer will attempt to download and install it for you. Just follow the installer instructions.
    • On Tiger (MacOS 10.4), you must install X11 from the install disks.
  3. When running the uninstaller, the dialog that starts it up may pop up *behind* the main dialog box. You will have to click on it to raise it. We expect that in the next release the installer software will be much more Mac-friendly.

Step-By-Step Guide

  1. Decide where to install Pathway Tools. For a single user, your home directory is strongly recommended. This is the default location suggested by the installer.
  2. Download the Pathway Tools distribution file. Safari users note: You must download the file with Control-Mouseclick, and select "Download Linked File" from the popup.

    These files are of the form

    pathway-tools-[version]-[platform]-[edition]-install.dmg
    where [version] is 14.5 for this release, [platform] is "macosx", and [edition] could be "collaborator", "tier1" and so on. An example would be
    pathway-tools-14.5-macosx-tier1-install.dmg

    The URLs pointing to these distributions can be found in the confirmation email that is sent after signing the license agreement. Please retain this email, as the same URLs will be used for every new release. Please also ensure that the correct distribution is selected for your specific platform.

  3. The .dmg files are disk images that can be mounted by double-clicking on them. A Finder window should appear which contains the actual installer. Double-click the installer file.

  4. A GUI-based installer will guide you through the rest of the installation process. The installer will suggest you close all applications before continuing and give you the opportunity to cancel the installation.

    Click Next

  5. The installer will ask you where you want to install the Pathway Tools system. If you are running as a normal user, it will suggest a location in your home directory. If you are installing as the root user, it will suggest /usr/local/pathway-tools as a location. The latter is convenient if many users will be using Pathway Tools.

    Click Next once you have chosen a suitable location.

  6. Pathway Tools requires a directory where it will store local user data such as created PGDBs and HTML customization files. The installer will ask you to specify a directory path where Pathway Tools can create this "ptools-local" directory. Please make sure that all users who will update PGDBs have write permission to the ptools-local directory and its subdirectories. The default directory is the home directory of whoever is running the installer, which means that the data will reside in a directory called ~/ptools-local.

    IMPORTANT NOTE

    Do not install the ptools-local directory under your Pathway Tools installation directory, since the data in this directory would then be deleted when Pathway Tools is upgraded or reinstalled.

    Click Next once you have chosen a suitable location.

  7. The system will pop up a dialog describing the installation. If the information it gives is not suitable, you can click the Back button to revisit previous dialogs.

    Click Next to do the actual installation.

  8. If you already have Pathway Tools installed, the installer will pop up a dialog asking if it can uninstall this previous installation. We highly recommend that you allow the installer to uninstall the previous version. Incorrect operation may result if the previous version is not uninstalled before installing the new version. Unless you are installing this versionof Pathway Tools in a different place, choose Yes from this dialog to uninstall the previous version.

    The uninstaller for the previous version will then pop up a dialog asking for permission to uninstall the previous version. Answer Yes to continue.

    *****Warning!***** The uninstaller dialog for the old Pathway Tools may pop up ***behind*** the installer window with just the edges visible. Please click on it to bring it to the front.

  9. Once the files are installed, the installer will pop up a pane reminding you of the location of the ptools-local directory. After a successful installation of Pathway Tools, a file with initialization parameters will have been written in this directory, retaining values from a prior installation if possible. The resulting file can be found in ptools-local/ptools-init.dat. This file may be customized and edited to define additional parameters specific to your site. Please see the Pathway Tools User Guide for more details on how to customize the ptools-init.dat file.

    Click OK.

  10. Click Finish to finish installing Pathway Tools. The installer will then pop up a banner saying that it is configuring Pathway Tools. This may take a minute or so depending on the speed of your computer. The installer will then exit.
  11. You may now run Pathway Tools as follows. If you've installed Pathway Tools in your home directory, there will be a script in the pathway-tools directory named pathway-tools. Invoke this script in the terminal window:
    ~/pathway-tools/pathway-tools

    This script may be copied into a location in your execution path for convenient use. For example, you could copy it into /usr/local/bin if you have that directory listed in your PATH environment variable. Then you could bring up Pathway tools by simply typing

    pathway-tools
    in an X11 terminal window.

    Pathway Tools can be run as an Application using AppleScript. To do this, bring up the AppleScript editor. Select Finder->Go->Applications and then choose AppleScript->Script Editor.app.
    Enter the following code snippet into the AppleScript editor:

    on run
    do shell script "$HOME/pathway-tools/pathway-tools > /dev/null 2>&1 &"
    end run

    Save this in "Application" format to your desktop and you should be able to double-click on the resulting icon to bring up Pathway Tools. You can also put this icon on your doc.


Installing on Linux x86 or x86-64 (Intel / AMD)

Important Note For Linux: Please be sure that /bin/csh is present. Some current Linux distributions no longer install csh or tcsh by default. This will cause the installer to fail with a cryptic error message or even fail silently. Type
which csh
Your computer should respond:
/bin/csh

Step-By-Step Guide

  1. Decide where to install Pathway Tools. For a single user, your home directory is strongly recommended.

  2. Download the Pathway Tools distribution file. These files are of the form
    pathway-tools-[version]-[platform]-[edition]-install
    where [version] is 14.0 for this release, [platform] could be "linux" or "linux-64"", and [edition] could be "collaborator", "nav-path-ed-tier1" and so on. An example would be
    pathway-tools-14.0-linux-tier1-install
    If you are downloading the tier1-tier2-tier3 version of Pathway Tools for a 64-bit Linux machine, it will be in a tarball called ptools-linux64.tar.bz2. This distribution contains hundreds of organism-specific databases, and requires special installation instructions. Please proceed to the section
    "Installing Linux-64 BioCyc Tier1-Tier2-Tier3 Distribution".

    The URLs pointing to these distributions can be found in the confirmation email that is sent after signing the license agreement. Please retain this email, as the same URLs will be used for every new release. Please also ensure that the correct distribution is selected for your specific platform.

  3. The distribution files are executable installers. Run the file from the command line in the normal way:
    $ ./pathway-tools-14.0-linux-tier1-install

    You may need to first run

    $ chmod u+x pathway-tools-14.0-linux-tier1-install
    in order to make the file executable.

  4. A GUI-based installer will guide you through the installation process. First, it will ask you if you want to install Pathway Tools on your computer.

    Click Yes.

  5. The installer will suggest you close all applications before continuing and give you the opportunity to cancel the installation.

    Click Next

  6. The installer will ask you where you want to install the Pathway Tools system files. If you are running as a normal user, it will suggest a location in your home directory. If you are installing as the root user, it will suggest /usr/local/pathway-tools as a location. The latter is convenient if many users will be using Pathway Tools.

    If the suggested locations are not suitable, click on the Browse button to navigate to a more appropriate location.

    Click Next once you have chosen a suitable location.

  7. Pathway Tools requires a directory where it will store local user data such as created PGDBs and HTML customization files. The installer will ask you to specify a directory path where Pathway Tools can create this "ptools-local" directory. Please make sure that all users who will update PGDBs have write permission to the ptools-local directory and its subdirectories. The default directory is the home directory of whoever is running the installer, which means that the data will reside in a directory called ~/ptools-local. If you are installing for multiple users, a directory such as /var might be more appropriate.

    IMPORTANT NOTES

    Click Next once you have chosen a suitable location.

  8. The system will pop up a dialog describing the installation. If the information it gives is not suitable, you can click the Back button to revisit previous dialogs.

    Click Next.

  9. At this point, if you have a previous installation of Pathway Tools, you will see a dialog asking if the installer can remove this previous installation. It is highly recommended that you allow the installer to remove the previous installation. Correct operation cannot be ensured if you install Pathway Tools without removing the previous installation. Unless you are installing Pathway Tools in a different location from the previous installation, click Yes to allow the installer to remove the previous installation.

    The uninstaller for the previous installation will run. Follow the instructions it presents.

    Once the uninstaller is finished, the installer will procede to install the files for Pathway Tools.

  10. Once the files are installed, the installer will pop up a pane reminding you of the location of the ptools-local directory. After a successful installation of Pathway Tools, a file with initialization parameters will have been written in this directory, retaining values from a prior installation if possible. The resulting file can be found in ptools-local/ptools-init.dat. This file may be customized and edited to define additional parameters specific to your site. Please see the Pathway Tools User Guide for more details on how to customize the ptools-init.dat file.

    Click OK.

  11. Click Finish to finish installing Pathway Tools. The installer will then pop up a banner saying that it is configuring Pathway Tools. This may take a minute or so depending on the speed of your computer. The installer will then exit.

  12. If you inadvertently skipped Oracle or MySQL configuration when you were visiting the previous web page, and you've decided to use a RDBMS, be sure to configure it now.
    [oracle configuration] [mysql configuration]

  13. Verify that Pathway Tools works by briefly running it (assuming it is installed in /usr/local/pathway-tools):
    /usr/local/pathway-tools/pathway-tools
  14. To allow users to easily start up this program by simply typing pathway-tools, the script in the install directory can be copied into a location accessible by all users. Access as the root user is necessary for this step. Assuming the pathway-tools directory is located in /usr/local and user-accessible binaries in /usr/local/bin, execute the following command:
    rm -f /usr/local/bin/pathway-tools
    cp /usr/local/pathway-tools/pathway-tools /usr/local/bin/pathway-tools
    chmod 755 /usr/local/bin/pathway-tools
  15. Remote Access: Users often like to run Pathway Tools on a fast server and have the windows display on their desktop machine. For this to happen, the X server running on the desktop must allow remote connections.

    By default, most current versions of Linux do not configure the X Server to accept remote connections over the network. If you wish to run Pathway Tools on a server and have its windows show up on your local display, you must do one of the following.

    • Debian and Ubuntu systems need the string "-nolisten tcp" removed from all files in /etc/X11/ and its subdirectories in which the string occurs. Likewise for modern versions of Linux from the RedHat family, X Server security has been tightend. To get around this, the file /etc/X11/gdm/gdm.conf can be edited, to set:
      DisallowTCP=false
    • A different method around these X Server restrictions is to log into the computer with SSH using the -X flag (the -X flag enables forwarding X11 connections):
      ssh -X localhost
      Sometimes the -X argument will not work; in that case using -Y instead may work. For example, displaying Pathway Tools windows remotely on a Mac system seems to require the -Y argument. The -Y argument causes the forwarded connection to be "trusted".
      ssh -Y localhost
      Then, launch Pathway tools from within this session.

Installing Linux-64 BioCyc Tier1-Tier2-Tier3 Distribution

Due to limitations in our installer software, we use the old tarball method distribution of the full tier1-tier2-tier3 configuration.

This configuration contains more than 400 organisms and requires a large amount of memory. You will not be able to run this configuration unless you have at least 16Gb (sixteen gibabytes) of physical memory (RAM); more memory will be even better. Because of its large resource requirements, we do not recommend you use this configuration unless you require access to large numbers of organism databases. Note that you can download individual organism databases from the PGDB registry and add them to a tier1 or tier1-tier2 configuration that does not have very large memory requirements.

Follow these instructions to install:

  1. Determine where you wish to install the software. At least 15 Gb of disk space is required to unpack this software.
  2. Save the distribution file into a convenient directory (here or elsewhere).
  3. Change directory to the place where you wish to install the software.
  4. Extract the distribution:
    tar jxvf *path to tarball*
  5. Run the configuration command:
    ./aic-export/pathway-tools/ptools/14.0/install/config-ptools
    This will ask you for the location of the "ptools-local" directory. If you are installing for many users, the /var directory might be a suitable place for this directory. If you are installing for a single user, that user's home directory might be appropriate.
    Enter pathname of Pathway Tools local directory: /homedir/gilham
  6. See this item in the instructions above for instructions on creating a script for easy execution of Pathway Tools.
Once the software exits the configuration step, your system will be ready for use.

For All Users and All Distributions

The Pathway Tools User's Guide documents the many ways you can configure the ptools-init.dat file to run Pathway Tools (including as a web server). That document is available within the Pathway Tools "Help" menu and for this release (14.0) is stored at:
pathway-tools/aic-export/pathway-tools/ptools/14.0/doc/manuals/UserGuide.pdf