• Docs »
• Installation and Platform Notes

# Installation and Platform Notes¶

To run ROCS you will need to obtain a license file for ROCS from OpenEye Scientific Software (sales@eyesopen.com). The license file should be pointed to by the environment variable OE_LICENSE.

If you intend on running multi-processor ROCS via Open MPI, only the master machine needs access to the license file.

On Windows, the environment variables can be set under the system Control Panel.

## General Installation¶

### Linux¶

Linux distributions are provided as a gzipped tarball of the distribution tree described below. Installation is performed by simply untarring the file in the desired location. The top-level directory in the tarball is named openeye. Distributions for different Linux variants can be installed into the same location, allowing multiple Linux versions to be run from a single shared directory.

To ensure that the installed applications can be called from the command line, be sure to add the full path of the openeye/bin subdirectory to the PATH environment variable. For instance, if the distribution was installed into /usr/local/openeye, the PATH environment variable should contain: /usr/local/openeye/bin.

Under the top-level openeye directory are the following subdirectories:

arch: This directory contains the collection of platform specific subdirectories. Each subdirectory contains the actual installed executables and support libraries for the associated platform. In the platform specific subdirectory there will be a subdirectory for each application. Within that will be another subdirectory for each version of that application. This directory contains a startup script for each application that has been installed. This script determines, at run-time, what the current platform is and then calls the appropriate executable in the arch. This script enables the easy co-existence of multiple platforms and versions of any OpenEye application in the same distribution tree. This directory contains all of the associated data for the installed applications. There will be a subdirectory for each installed application and within that subdirectory there will be another subdirectory for each specific version of that application. This directory contains all of the documentation associated with the installed applications. There will be a subdirectory for each installed application and within that subdirectory there will be another subdirectory for each specific version of that application. This directory contains all of the examples associated with the installed applications. There will be a subdirectory for each installed application and within that subdirectory there will be another subdirectory for each specific version of that application.

The startup script discussed in the section on the bin directory above will have the same name as the installed executable with which it is associated. When the script is called, it will attempt to determine the current platform and run the appropriate executable if installed. If an appropriate executable cannot be found, the script will report that information, as well as a list of the currently installed platforms. The auto-detection can be overridden by setting one of two environment variables:

• OE_ARCH can be used to specify a colon separated list of compatible distributions for the current platform such as:

redhat-RHEL6-x64:redhat-RHEL5-x64

Specification of this environment variable overrides the auto-detection process, if it is present. If none of the compatible distributions listed are found, the script will fall back to the auto-detection process.

• APPNAME_OE_ARCH can be used to specify a colon separated list of compatible distributions for a specific application (as specified by changing the APPNAME text in the environment variable name) just like OE_ARCH as detailed above.

Specification of this environment variable overrides the OE_ARCH environment variable as well as the auto-detection process. If none of the compatible distributions listed are found, the script will fall back to the OE_ARCH list first and then to the auto-detection process.

Specifying this variable provides a simple way to customize the behavior for individual applications on non-standard platforms.

The startup script also supports a few commandline arguments including:

 -path Specifying this argument will output the full path of the executable to be run. The executable will not be started if this argument is present. -print_arch Specifying this argument will output the details of the current platform as detected by the script as well as which platform-version of the executable is being run. The executable will be started if this argument is present. -use_version Specifying this argument followed by a specific version number allows the user to control which released version of the executable to run.

### Windows¶

Windows distributions are provided as a standard EXE installer. For installation double click the executable and follow the installation instructions. By default, OpenEye applications will install into the C:\Program Files (x86) directory (for 32-bit applications) or C:\Program Files (for 64-bit applications).

Note

Because memory is limited for 32-bit applications, to avoid crashes due to running out of available memory, memory-intensive tasks are best performed using 64-bit applications.

Under the application directory (C:\Program Files\Application Name) there are subdirectories for:

bin: This directory contains the application executable. This directory contains all of the associated data for the installed applications. This directory contains all of the documentation associated with the installed applications. This directory contains all of the examples associated with the installed applications.

An OpenEye group with an application specific subgroup will be added to the Start menu. The application specific subgroup will contain links to the documentation, the uninstaller, and, for some applications, a Windows command shell with PATH settings already defined to allow the user to simply type the executable name at the prompt without concern for where the executable is actually installed. Links are also included to add and remove the installed location to the user’s default path.

For graphical applications, a link to the application will be created on the desktop as well as in the application specific subgroup of the Start menu.

### Mac OS X¶

Mac OS X distributions are provided as a dmg disk image. For installation, double click the .dmg file to open it, and drag the application to the Applications folder.

A folder containing documentation and example data is included in the disk image (Right click, Show Package Contents). Under the top level Contents folder there are subdirectories for:

data: This directory contains all of the associated data for the installed applications. This directory contains all of the documentation associated with the installed applications. This directory contains the application executable.

The documentation and example data can be copied to any convenient location. Graphical applications have built-in documentation, which is available from the application’s Help menu.

For command-line only tools, an application named “Install Command Line Support” can be run from the .dmg file, and this will allow the user to add the application’s location to the user’s PATH environment variable. Command-line applications can also be run from the Applications folder, in which case they will open a terminal window with a properly configured environment.

## MPI¶

### Open MPI¶

This application uses the Open MPI implementation of MPI, found at http://www.open-mpi.org/. This version includes a full Open MPI install, so no additional software is needed.

There are two requirements to run under Open MPI.

• Every machine in the cluster must have the same version of the application installed.
• The path to the application’s bin directory must be in the PATH environment variable on all machines, and be positioned before any other locations that may contain MPI executables (orted, mpirun, etc).

### Using Open MPI¶

To run under Open MPI on a single machine:

> [application executable] -mpi_np [number of processes] [other application options]


To run Open MPI on multiple machines, begin by generating a text file that will include the MPI hosts you plan to use and the number of processes on each (for this example, we’ll call this file hosts). The file should contain a line for each machine with the name of the machine, a space, then slots=N, where N is the number of processors for your run. For this example, the file looks like this:

c1 slots=4
c2 slots=4
c3 slots=4
c4 slots=4
c5 slots=4


The following command-line will then start a job with one master and 19 slaves.

> [application executable] -mpi_hostfile hosts [other application options]


The master will be on c1, where the job is being started. All the input/output for the run is controlled from the master machine, and all results and logging information are combined.

### Windows MPI¶

MPI on Windows requires a valid network connection. If no connection exists MPI will not run. A network connection can be created by installing a Microsoft loopback adapter. Please contact support@eyesopen.com for more details.

Most files in this release are marked with the copyrights of the
organizations who have edited them.  The copyrights below are in no
particular order and generally reflect members of the Open MPI core
team who have contributed code to this release.  The copyrights for
corresponding files.

Copyright (c) 2004-2010 The Trustees of Indiana University and Indiana
University Research and Technology
Copyright (c) 2004-2010 The University of Tennessee and The University
of Tennessee Research Foundation.  All rights
reserved.
Copyright (c) 2004-2010 High Performance Computing Center Stuttgart,
Copyright (c) 2004-2008 The Regents of the University of California.
Copyright (c) 2006-2010 Los Alamos National Security, LLC.  All rights
reserved.
Use is subject to license terms.
Copyright (c) 1998-2005 Forschungszentrum Juelich, Juelich Supercomputing
Centre, Federal Republic of Germany
Copyright (c) 2005-2008 ZIH, TU Dresden, Federal Republic of Germany
Copyright (c) 2008-2009 Institut National de Recherche en
Copyright (c) 2007      Lawrence Livermore National Security, LLC.
Copyright (c) 2012      The University of Wisconsin-La Crosse. All rights
reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

- Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.

- Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer listed
in this license in the documentation and/or other materials
provided with the distribution.

- Neither the name of the copyright holders nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.

The copyright holders provide no reassurances that the source code
provided does not infringe any patent, copyright, or any other
intellectual property rights of third parties.  The copyright holders
disclaim any liability to any recipient for claims brought against
recipient by any third party for infringement of that parties
intellectual property rights.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


## Uninstallation¶

### Linux¶

To uninstall a single distribution of a product the relevant subdirectories for that product and version simply need to be deleted from within the following directories:

arch: In the openeye/arch directory is a platform specific subdirectory. Within this are directories for each installed product and within those are subdirectories for each version of the product. Delete the subdirectory for the version which is to be uninstalled. For example, to delete or uninstall v1.0.0 of a product, delete the folder “/1.0.0”. In the openeye/data directory is a subdirectory for each installed product and within those are subdirectories for each version of the product. Delete the subdirectory for the version which is to be uninstalled. In the openeye/docs directory is a subdirectory for each installed product and within those are subdirectories for each version of the product. Delete the subdirectory for the version which is to be uninstalled. In the openeye/examples directory is a subdirectory for each installed product and within those are subdirectories for each version of the product. Delete the subdirectory for the version which is to be uninstalled.

### Windows¶

OpenEye applications can be uninstalled through the Windows Control Panel. Open the Control Panel and select Programs and features, then select the application and click Uninstall.

For graphical applications, uninstallation also removes the application’s link from the desktop and Start menu.

### Mac OS X¶

To uninstall a single distribution of an application simply drag the application from the Application folder to the Trash.

Some applications may, at the user’s request, install symbolic links in the /usr/local/bin directory, and modify the PATH variable in the .openeyerc.* file(s) in the user’s home directory. The symbolic links may be safely deleted after uninstallation, and the .openeyerc.* file(s) can be edited, if desired, to remove obsolete entries.