Pathway Tools Installation Guide -- Linux and MacOS X

The following instructions are for the supported UNIX systems, namely modern flavors of Linux x86, Linux x86_64, and MacOS X 10.14+.

Contents

• Installing on MacOS X
  • Important Notes for MacOS X
  • Step-by-step instructions for Mac
• Installing on Linux x86 or x86-64 (Intel / AMD)
  • Important Note for Linux
  • Step-by-step instructions for Linux
• The User Guide --- For All Users and All Distributions

Installing on MacOS X

IMPORTANT notes for MacOS X:

1. Pathway Tools is known to run on MacOS X 10.14 and higher. It may run on earlier versions, but since these versions are no longer supported by Apple, we recommend upgrading your Mac prior to installing Pathway Tools.
2. Pathway Tools is now known to work on M1 Macs, but requires at least MacOS 12 (i.e., Monterery). This version is still under beta testing, and we are referring to it as the 27.5-Beta version in the following.
3. Pathway Tools requires that X11 be installed. In all recent versions of MacOS (10.6+), it should be installed by default. You can check if you have X11 installed by clicking on the Finder menu Go->Utilities. You should see an entry for XQuartz, which is Apple's version of X11. If you do not see an entry for XQuartz, you will need to obtain and install the most recent version from XQuartz.org.
4. You may encounter an error when installing a new version of Pathway Tools on a Mac that has been upgraded from MacOS X 10.14 to 10.15. This is actually a problem with the uninstaller tool that was installed with earlier versions of Pathway Tools. If you encounter this error, please manually delete your Pathway Tools installation folder. This will typically be called pathway-tools and be in your home directory. You shouldn't delete files in your ptools-local folder.
5. The 27.5-Beta version of Pathway Tools that runs on M1 Macs requires at least MacOS 12, and requires that homebrew is installed on your Mac; see below for instructions.

Step-By-Step Guide

1. The following Steps 1a - 1c only apply if you are installing the 27.5-Beta version of Pathway Tools on an M1 Mac:
   1. Open a terminal window (note: the terminal app can be found from the Launchpad using the search bar) and enter

      brew update ; brew upgrade

   If brew isn't installed on your system, you will get a Command not found error message. Then, proceed to Step 1b. Else, brew was already installed - continue to Step 1c after the update.
   2. In the terminal, ensure that the Bash Shell is running by entering into the terminal:

      /bin/bash

      Note that the Bash Shell is still supplied by Apple, even though it is no longer the default terminal shell. In the same terminal running the Bash Shell by now, enter

      /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

      It is easiest to simply do a Copy & Paste (Apple-c, Apple-v) from the above text line into the terminal to avoid typos, followed by Enter. An active internet connection must be available. This command will download and install the homebrew package manager on your Mac.
   3. Install OpenMotif. In the same terminal running the Bash Shell, enter

      /usr/local/bin/brew install openmotif

      If you are getting a Command not found error, try

      /opt/homebrew/bin/brew install openmotif

      instead. An active internet connection must be available. After a few minutes you will have OpenMotif installed. At the time of this writing, we are using OpenMotif version 2.3.8_2.

2. 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.
3. 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 the version you downloaded, for example 24.0, [platform] is "macosx", and [edition] could be "collaborator", "tier1" and so on. An example would be

   pathway-tools-24.0-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.

4. The .dmg files are disk images that can be mounted by opening them. If you double-click on the dmg, you will get a warning about the file coming from an unidentified developer; this warning is intended to protect you from installing malware. To proceed with the install, click the OK button and go to the System Preferences Window (it's on your dock or Apple -> System Preferences) and click the security and privacy icon. The preferences pane will ask whether you want to go ahead and open the dmg you just clicked on. Click OK to proceed with the installation. You can also avoid going through the system preferences by opening the dmg with by right clicking while holding down the option key.
5. Once the dmg is open, a Finder window should appear which contains the actual installer. Double-click the installer file.
6. 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.

7. 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.

8. 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 directory.

9. The system will pop up a dialog describing the installation. Review the information. If you need to change something, you can click the Back button to revisit previous dialogs.

   Click Next to do the actual installation.

10. 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 version of 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!****** If you are upgrading a Pathway Tools install on a Mac running OSX 10.15 (Catalina) that was previously upgraded from 10.14 (Mohave) you may get an error when the uninstaller tries to run. In this case delete the previously installed pathway-tools folder (but not the ptools-local folder) and restart the installation.

11. 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.

    Note: A PDF of the Pathway Tools User Guide is installed in your pathway-tools directory: pathway-tools/aic-export/htdocs/doc/UserGuide.pdf

    Click OK.

12. 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.
13. 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 typing:

    pathway-tools

    in a terminal window.

    Pathway Tools can be run as an Application using AppleScript. To do this, bring up the AppleScript editor. From the Finder menu select Go->Utilities to open the Utilities window and then choose the Script Editor application.
    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 dock.

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

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

/bin/csh

In case csh is not installed, type the following command at shell prompt as per your Linux distro / version.

• Install it on Debian/Ubuntu/Mint Linux: $ sudo apt-get install csh
• Install it on CentOS/RHEL: # yum install tcsh
• Install it on Fedora Linux: $ sudo dnf install tcsh

Although we bundle the Motif library for Pathway Tools, we do not bundle the core X11 libraries that motif depends on. Depending on which Linux distribution you're running, you'll need to install the appropriate libraries. This is especially true for the tier1-tier2-tier3 distribution since it does not include an installer.

apt-get install libx11-6 libxext6 libxft2 libxmu6 libxp6 libxt6

apt-get install libmotif4

apt-get install libxm4

yum install motif

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 the version you downloaded, for example 24.0, [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-24.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-24.0-linux-tier1-install

   You may need to first run

   $ chmod u+x pathway-tools-24.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

   • 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.
   • If you are using Pathway Tools as a single user, do not use /var as your installation directory unless you are able to give yourself write access to the ptools-local directory and its contents. Instead use your home directory (this should be the default if you are not installing as the root user).

   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 MySQL configuration when you were visiting the previous web page, and you've decided to use a RDBMS, be sure to configure it now.
    [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.

For All Users and All Distributions

pathway-tools/aic-export/pathway-tools/VERSION/doc/manuals/UserGuide.pdf