Prerequisites

1. CMake is required to follow the build instructions included in this document. Version 2.8.9 and above is required on most of the platforms, except VS2015 which requires at least 3.1.3. This tool provides the simplest method of building code that utilizes OpenEye C++ toolkits. CMake downloads can be found at http://www.cmake.org/cmake/resources/software.html.

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

3. Linux requires the zlib and libcairo libraries be available. These are usually available on Desktop Linux installations by default, but may not be available on Linux server installations.

4. 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 OS X operating systems.

Windows

  • Visual Studio 2013 (x86 and x64)
  • Visual Studio 2015 (x86 and x64)

Note

For deployment of toolkit programs built with VS2015 onto older systems, one may need to download and install the redistributable VS2015 runtime, available at: https://www.microsoft.com/en-us/download/details.aspx?id=48145 Otherwise one may get messages at execution-time about missing files: msvcp140.dll, vcruntime140.dll and related files.

Linux

  • RHEL5
    • gcc/g++ 4.1 (x64)
  • RHEL6
    • gcc/g++ 4.4 (x64)
    • gcc/g++ 4.8 (x64)
  • RHEL7
    • gcc/g++ 4.8 (x64)
  • Ubuntu 14.04
    • gcc/g++ 4.8 (x64)
  • Ubuntu 16.04
    • gcc/g++ 5.4 (x64)

OS X

  • OS X 10.10
    • clang 6.x (x64)
  • OS X 10.11
    • clang 7.x (x64)
  • OS X 10.12
    • clang 8.x (x64)

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:

    • Linux/UNIX:

      ~USERNAME/.OpenEye

    • Mac OS X:

      /Users/USERNAME/Library/OpenEye

    • Microsoft Windows Vista/7/8.1/10:

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

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

Download the OpenEye C++ distribution

Follow these steps to download a toolkit distribution for your target platform:

1. In your web browser, go to the OpenEye downloads web page: http://www.eyesopen.com/downloads

2. On the downloads page, check the box for your target platform and click the “proceed” button. A list of product download links with product descriptions will appear.

3. Click on a distribution link with the description: toolkits - unified toolkits distribution, C++ API. Be sure to choose a distribution that matches the following characteristics of your target system:

  • Operating system - type and version
  • CPU architecture - 32 or 64 bit
  • Compiler - type and version (must be the same as or compatible with the compiler you plan to use to compile code using the toolkits)

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 OS X 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.Mon.x.

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 / OS X)

Follow these steps to compile the examples on Linux/OS X:

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 on Windows:

1. Open Windows Explorer.

2. Navigate to the openeye\toolkits\examples directory from the folder where you installed the toolkits.

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

4. Double-click on the file OpenEye-Toolkits.sln to open the generated solution with Visual Studio. In Visual Studio, you will see a list of projects included in the solution.

5. In Visual Studio, build the solution. All of the example projects will build.

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

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 / OS X)

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 2.8.9)

# 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 Parsing in the OEChem TK theory documentation.

  1. 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 (eg. 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 2.8.9)

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.