Windows¶

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

Linux¶

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

Building the Examples (Linux / OS X)¶

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

cd openeye/toolkits/examples
./configure
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.

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)
• If using a later gcc, uncomment the line for the c++11 flag

cmake_minimum_required(VERSION 2.8.9)

# GCC versions 4.7 and higher need this extra flag for language
# compatibility, so uncomment if necessary.
# 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)

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

4. Run make within your project 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 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.

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.