Information
|
Licensing
|
Technical Specs
|
Support
|
|
Pathway Tools Installation Guide -- Linux and MacOS X
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
IMPORTANT notes for MacOS X:
- 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.
- 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.
- 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.
- 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.
- 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
- The following Steps 1a - 1c only apply if you are installing the 27.5-Beta version of Pathway Tools on an M1 Mac:
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- Once the dmg is open, a Finder window should appear which contains the actual installer.
Double-click the installer file.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
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 as follows if csh is installed:
/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
Important Note For Linux and X11:
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.
For example, in Ubuntu 12.04, you can satisfy the library dependencies by running:
apt-get install libx11-6 libxext6 libxft2 libxmu6 libxp6 libxt6
For version Ubuntu 16.04 based Linux distros, you can satisfy
the library requirements by just installing the libxm4 package and its dependencies:
apt-get install libmotif4
For Ubuntu 18.04 you should be able to install with just
apt-get install libxm4
For CentOS 7 and similar Redhat-based distributions, this works:
yum install motif
- Decide where to install Pathway Tools. For a single user, your
home directory is strongly recommended.
- 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.
- 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.
- 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.
- The installer will suggest you close all applications before
continuing and give you the opportunity to cancel the installation.
Click Next
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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]
- Verify that
Pathway Tools works by briefly running it (assuming it is installed in /usr/local/pathway-tools):
/usr/local/pathway-tools/pathway-tools
- 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
- 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.
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 is stored at (substitute the current version number for VERSION):
pathway-tools/aic-export/pathway-tools/ptools/VERSION/doc/manuals/UserGuide.pdf
|