Prerequisites

1. For building on any platform, CMake 3.19 and above is required to follow the build instructions included in this document. This tool provides the simplest method of building code that utilizes OpenEye C++ toolkits. CMake downloads can be found at https://cmake.org/download/

2. A platform dependent compression utility (e.g. WinZip for Windows or tar for Linux/macOS).

3. Linux requires the zlib and libcairo libraries be available. To ensure they are installed on Ubuntu run:

   sudo apt-get update -y
   sudo apt-get install -y zlib1g-dev
   sudo apt-get install -y libcairo2-dev
   

or on CentOS:

sudo yum update -y
sudo yum install zlib-devel
sudo yum install cairo-devel

4. GCC 7.4 is the minimum required compiler on Linux.

5. The minimum recommended GNU binutils version is 2.26 for the C++ single build Linux packages.

6. A compatible compiler must be installed to build any code that uses the libraries. The following are lists of supported compilers and their versions, on Windows, Linux, and macOS operating systems.

Windows

The following packages are supported:

• Visual Studio 2017 (x64)

• Visual Studio 2019 (x64)

Note

• Examples should be built in a Visual Studio command window.

• cmake.exe version 3.16 or higher should be in the system or user’s PATH.

• Only RELEASE builds are currently supported (Visual Studio normally defaults to DEBUG).

• Visual Studio needs to be installed with the C++ compiler enabled, which is not the default. Select the Desktop development with C++ option as depicted below when installing or re-installing Visual Studio.

Visual Studio Installation

Linux

The following platforms are supported with 2 single build Linux packages for g++7.x and g++9.x.

• RHEL7

  • gcc/g++ 7.4 (x64)

• RHEL8

  • gcc/g++ 8.2 (x64)

• Ubuntu 18.04

  • gcc/g++ 7.4 (x64)

• Ubuntu 20.04

  • gcc/g++ 9.3 (x64)

macOS

The following platforms are supported with a single build package

• macOS 10.14

  • clang 10.x (x64)

• macOS 10.15

  • clang 11.x (x64)

• macOS 11

  • clang 12.x (x64)

GPU Prerequisites

GPU-Related Requirements

The following is required in order to use GPU-accelerated OpenEye toolkits and applications:

Supported Platforms

CUDA-enabled OpenEye software is only available on supported Linux platforms. For supported Linux platforms see above and/or the Platform Support Page

Supported GPUs

An NVIDIA Tesla, Quadro, or GeForce GPU with a compute capability of 3.5 or higher is required on your system. For a comprehensive table of which GPUs fall into which compute capability category please refer to the CUDA wikipedia page.

NVIDIA Drivers

• Minimum NVIDIA Driver version: 450.x.

• CUDA is not required to be installed.

We recommend driver 450.80.02 and we strongly advise manually downloading and installing the appropriate NVidia driver for your system as opposed to using a package manager.

To install, root privilege is required. Follow these steps:

1. Download the driver to the machine you are installing it on.

2. chmod +x the driver package to make it executable.

3. Ensure you have disabled X-server by killing any running sessions. Reboot may be required if X-server is still running after this step.

   Warning

   Disabling X-server requires different processes to be killed depending on your Linux distribution. See Nvidia installation guide for more details.

   Warning

   The NVidia kernel module can often conflict with the open source Nouveau display drivers depending on your specific Linux distribution. The NVidia documentation is a much more complete and up-to-date source for information on how to work around this issue. See Disabling Nouveau on the NVIDIA website.

4. Install the driver by sudo ./NVIDIA-Linux-x86_64-450.80.02.run and follow the step-by-step installation instructions.

For more details on driver installations see the CUDA Installation Guide

Note

The output of the nvidia-smi command is extremely useful when debugging GPU issues. Please include the output from nvidia-smi in any request to support@eyesopen.com.

Performance Tuning

To get the most performance out of an NVIDIA Graphics card, use the persistence daemon to switch persistence mode on across all cards on the system (root privilege required):

sudo nvidia-persistenced --user foo

This will automatically enable persistence mode after reboot.

For full instructions on persistence daemon see the Persistence daemon section of the NVIDIA docs.

Licensing

A license file from OpenEye Scientific Software is required to run any OpenEye toolkit. A license file can be requested/obtained by contacting OpenEye at sales@eyesopen.com.

At startup, the toolkit looks for a valid license in the following default locations:

• In a file specified by the environment variable OE_LICENSE.

• In a file named oe_license.txt in the directory specified by the environment variable OE_DIR.

• In a file named oe_license.txt in the user’s platform-specific local OpenEye application data directory. The location of this directory is detailed below:

  • Microsoft Windows:

    C:\Users\USERNAME\AppData\Local\OpenEye

• In a file named oe_license.txt in the current working directory

• License failure results in fatal error. The examples in OEChemIsLicensed show how to check if a valid license is available.

Download the OpenEye C++ distribution

Download a toolkit distribution for your target platform from http://www.eyesopen.com/downloads and follow the directions on the form.

Installation

To install the toolkits, you simply need to expand the downloaded distribution file into the directory where you want the toolkits to reside on your machine.

For example, on a Linux or macOS command line, you can use the following command:

> tar -xzf <distribution name>.tar.gz

On a Windows machine, you can double-click on the distribution file, which will have a .zip extension, and extract the compressed contents with the WinZip utility.

Extraction of the distribution file will create a directory called openeye, with the following structure:

openeye/
   toolkits/
      <VERSION>/
      examples/
      include/
      lib/

Note

Your installation will have a sub-directory named as a version number in the form, Year.Major#.Minor#.

Toolkit Examples

This chapter will guide you in building C++ example code distributed with the OpenEye toolkits that makes use of the toolkits. Several example code files are distributed with the toolkits to demonstrate how the toolkits can be used. These files are meant to be buildable, runnable programs, that can be compiled on your target machine.

Building the Examples (Linux / macOS)

Follow these steps to compile the examples on Linux/macOS:

cd openeye/toolkits/examples
./configure
make

Note

The configure script invokes the cmake tool to build a Makefile for make.

Once built, the example executables will be placed in the openeye/toolkits/examples/bin or openeye/toolkits/examples/bin/docs directories.

Building the Examples (Windows)

Follow these steps to compile the examples from a Vistual Studio Developer Command Prompt:

1. From the examples directory where you installed the toolkits, execute configure.bat.

2. Execute MSBuild OpenEye-Toolkits.sln  /p:Configuration=Release.

3. The compiled examples can then be found in examples/bin/docs/Release/.

Alternatively, the following steps can be used to build without a command prompt

1. In a File Explorer window, navigate to the examples directory in the folder where you installed the toolkits.

2. Double-click on the file configure.bat. A Visual Studio solution file named OpenEye-Toolkits.sln will be created in the examples folder.

3. Double-click on the file OpenEye-Toolkits.sln to open the generated solution with Visual Studio.

5. In Visual Studio, select Release for the build type and select Build Solution from the Build drop down menu.

Once built, the example executables can be found in examples\bin\docs\Release.

Running the Examples

To run an executable, go to the openeye/toolkits/examples/bin or openeye/toolkits/examples/bin/docs directory in a command line shell and invoke the program with appropriate arguments. All examples offer command line help to learn more about their command line options. For some of the examples, invoking the executable with the --help option will display this help documentation. For others, invoking the executable with no arguments displays the help documentation.

Note

Many of these programs require one or more input data files. These files are not distributed with the toolkit examples.

Building Toolkit Projects

This chapter will guide you in building C++ code that makes use of the OpenEye toolkits.

Building with CMake (Linux / macOS)

Using CMake as described in this section is the recommended method of building a project with the OpenEye toolkits. With CMake, a project can be quickly tailored to match the compilation environment used to build the toolkit code. In addition, CMake can be used to easily generate project files for the build environment meant for your system (i.e. the system that the toolkit distribution was built for).

1. Create a new directory for your project and copy or move your project files into the new directory.

2. Create a text file named CMakeLists.txt in your project’s directory, copy the below text into that file, and modify the following example parameter values:

• Change the value of OE_DIR to match the directory where the toolkits are installed on your machine. The below example assumes you’ve unpacked the distribution into the root of your source tree by using the ${PROJECT_SOURCE_DIR} CMake variable.

• Change the value of OE_LIBS to include the names of all OpenEye toolkit libraries that your project depends on (oechem will always be included). For other examples, see the example projects in openeye/toolkits/examples.

• Change SRCS to match the name of your application (the first argument)

cmake_minimum_required(VERSION 3.7.2)

set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11")

# specify where the OpenEye C++ distribution can be found
set (OE_DIR "${PROJECT_SOURCE_DIR}/openeye/toolkits")

# specify which OpenEye libraries to link against
set (OE_LIBS
    oechem
    oesystem
    oeplatform
)

# specify where CMake can find the OpenEye libraries
include_directories ( ${OE_DIR}/include )
link_directories ( ${OE_DIR}/lib )

# tell CMake to build the text2hex utility for creating .itf files from .txt files
set (CMAKE_RUNTIME_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/bin/)
add_executable(text2hex ${OE_DIR}/examples/text2hex.cpp)

# link all required OpenEye system libraries
set (LIBS "${OMPLIBS};${OE_LIBS};${SYSRASTERLIBS};${SYSLIBS};${SYSZLIB}")

# applications to build and their sources
set (SRCS
    "my_app my_app.cpp my_app.itf"
)

# enables OpenMP compiler flags
add_definitions("${OMPCFLAGS}")

# include the OpenEye boilerplate CMake code
include (${OE_DIR}/examples/ExamplesTemplate.cmake)

Note

The text2hex CMake code is only required when a .itf file is specified as a source file to build from, otherwise it can be omitted. .itf files are an OpenEye specific file extension to specify that a .txt file of command line interface options should be automatically compiled into a .itf file. For more information on interface files, see the chapter on Command Line Interface Definition in the OEChem TK theory documentation.

3. From your project directory, run the openeye/toolkits/examples/configure script.

Note

If you are running on Linux, and your C and C++ compilers are not the defaults (i.e. /usr/bin/gcc and /usr/bin/g++, respectively), then you will need to temporarily modify the CMAKE_C_COMPILER and CMAKE_CXX_COMPILER options in the configure script.

Note

This warning can be safely ignored if you are not using the OEDepict toolkit: Manually-specified variables were not used by the project: SYSRASTERLIBS

4. Run make within your project directory.

Note

This or a similar linker warning can be safely ignored: ld: warning: directory not found for option '-L<project path>/../lib'

Note

To display all possible make targets, run make help in your project’s directory.

Single-Build Distributions (Linux)

The single-build Linux distribution contains libraries built to be maximally-compatible with Linux-based systems. It is built specifically to take advantage of the Linux cross-version compatibility guarantees in such a way that executables built using the single-build distribution will run across many common Linux platforms without rebuilding.

This distribution is built on the oldest version of Linux we support. This means that the libraries will only depend on older Linux system functions (e.g. glibc). Since Linux guarantees forwards compatibility, this means that the distribution will work across most modern Linux distributions.

The distribution is built using a later g++ compiler toolchain. This allows us to take advantage of optimizations and language features only available in later g++ compiler versions (we’re not tied to the old g++ from the older Linux OS). This does create a new dependency on later versions of C++ runtime libraries (libstdc++.so, libgcc_s.so, libgomp.so). These three files are shipped with the single-build distribution and they, or later versions of them, must be available when running programs built with the distribution. This new dependency can be satisfied in one of three ways:

• The three files can be copied with the executables, and using a link-time option (-rpath) can be found by the executables at runtime

• The three files can be put in a common location, and runtime environment variables such as LD_LIBRARY_PATH can be used to find the files

• If the system already has a newer g++ installed on the system, the files in that toolchain will satisfy the dependency by default

The configure script and cmake files in the examples directory uses the first strategy since it doesn’t depend on any additional system configuration. The required operations are as follows:

• Include the -rpath=’$ORIGIN’ option in the link (ld) step when building executables. This tells the linker that the executable should look in its own directory for any runtime libraries before looking in system locations.

• Copy the three runtime files into the executable directory with the built executables. At execution time the needed libraries will be found before any other system libraries.

Finally, be aware that if the executables are moved to other machines, the three C++ system libraries should be copied with them. Best practice is to archive the entire bin directory and move it to the target platform(s).

The most common error seen when using programs built with the single-build distribution is a runtime error containing either GLIBCXX or CXXABI, as in the following examples:

cansmi: /usr/lib/x86_64-linux-gnu/libstdc++.so.6: version 'GLIBCXX_3.4.21'
not found (required by cansmi)

This message indicates that the program is using an older libstdc++.so file rather than the one shipped with the single-build distribution. It could be that the libstdc++.so file is not in the directory with the executable or that -rpath was not properly set. Use the ‘ldd’ and ‘readelf’ commands to isolate the problem.

Building with CMake (Windows)

Using CMake as described in this section is the recommended method of building a project with the OpenEye toolkits. With CMake, a project can be quickly tailored to match the compilation environment used to build the toolkit code. In addition, CMake can be used to easily generate project files for the build environment meant for your system (i.e. the system that the toolkit distribution was built for).

1. Create a new directory for your project and copy or move your project files into the new directory.

2. Create a text file named CMakeLists.txt in your project’s directory, copy the below text into that file, and modify the following example parameter values:

• Change the value of OE_DIR to match the directory where the toolkits are installed on your machine.

• Change the value of OE_LIBS to include the names of all OpenEye toolkit libraries that your project depends on (oechem will always be included). For other examples, see the example projects in openeye\toolkits\examples.

• Change SRCS to match the name of your application (the first argument) and include all the source files to be compiled.

cmake_minimum_required(VERSION 3.1.3)

set (OE_DIR "C:/Users/<USERNAME>/Documents/openeye/toolkits")

set (OE_LIBS
    oechem
)

include_directories ( ${OE_DIR}/include )
link_directories ( ${OE_DIR}/lib )

set (LIBS "${OE_LIBS};${SYSLIBS};${SYSZLIB}")

set (SRCS
    "my_app main.cpp"
)

include (${OE_DIR}/examples/ExamplesTemplate.cmake)

3. From your project directory, run the configure.bat script that resides in the openeye\toolkits\examples directory.

Note

This warning can be safely ignored if you are not using the OEDepict toolkit: Manually-specified variables were not used by the project: SYSRASTERLIBS

4. Open the generated project file Project.sln with the version of Visual Studio the toolkit distribution was created for, and build the project within the Visual Studio application.

Building Directly with Other Build Tools

If you are building your project directly with a build tool by hand (i.e not relying on build files generated by a configure or configure.bat script), you need to inform the tool about the locations of the include and lib folders of the toolkits distribution (i.e. openeye/toolkits/include and openeye/toolkits/libs, respectively). The compiler and compiler options for your C++ project should also match the ones used to build the toolkit example programs. Please reference openeye/toolkits/examples/configure for the compiler used to build the toolkits, as well as the compiler options.