Prerequisites¶
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/
A platform dependent compression utility (e.g. WinZip for Windows or
tar
for Linux/macOS).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
GCC 7.4 is the minimum required compiler on Linux.
The minimum recommended GNU binutils version is 2.26 for the C++ single build Linux packages.
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¶
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 variableOE_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 directoryLicense 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, executeconfigure.bat
.
Execute
MSBuild OpenEye-Toolkits.sln /p:Configuration=Release
.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 namedOpenEye-Toolkits.sln
will be created in theexamples
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 selectBuild Solution
from theBuild
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).
Create a new directory for your project and copy or move your project files into the new directory.
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 inopeneye/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.
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
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).
Create a new directory for your project and copy or move your project files into the new directory.
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 inopeneye\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.