.. _cplusplus_prerequisites:


Prerequisites
=============

.. index:: CMake, tar, WinZip, compiler, make

1. For building on any platform, CMake 3.21 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 `CMake <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 update -y
        sudo apt install -y zlib1g zlib1g-dev
        sudo apt install -y libcairo2 libcairo2-dev

  or on CentOS or RHEL::

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

4. The make program must be installed on the system.  Type::

    make --version

    If make is installed a version number is printed.  If not, you can install it with a command such as
    the RHEL command::

    sudo yum install make

5. The minimum recommended GNU `binutils <https://www.gnu.org/software/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 minimum
   versions, on Windows, Linux, and macOS operating systems.


Windows
-------

The following platforms are supported with a single package:

* Visual Studio 2022 (x64)
  
.. note::

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

  * cmake.exe version 3.21 or higher should be in the system or user's PATH.

  * 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.


Linux
-----

The following platforms and their default gcc versions are supported 


* RHEL8

  * gcc/g++ 8.2 (x64)

* RHEL9

  * gcc/g++ 11.3 (x64)

* Ubuntu 22.04 
    
  * gcc/g++ 11.4 

* Ubuntu 24.04 (x64)
    
  * gcc/g++ 13.3


macOS
------

The following platforms are supported with a single universal package:

* macOS 13-15


.. _cplusplus_gpu_prerequisites:

GPU Prerequisites
=================

.. include:: ../../common/gpu_prereq.rst


Download the OpenEye C++ distribution
=====================================

.. index:: downloading, CMake

Download a toolkit distribution for your target platform from
`OpenEye Applications & Toolkits Downloads <http://www.eyesopen.com/downloads>`_ and follow the directions on the form.

Installation
============

.. index:: installation, tar, WinZip, toolkit directory structure

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#``.

How to Build the Toolkit Examples
====================================

.. index:: toolkit examples

Several example code files are distributed with the toolkits to demonstrate how
the toolkits can be used. This section  guides you in building  the C++ example code distributed with
the OpenEye toolkits.

These files are meant to be buildable, runnable programs that can be compiled
on your target machine.

Building the Examples (Linux / macOS)
--------------------------------------

.. index:: configure, CMake, make, Makefile

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

.. code-block:: bash

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

.. index:: configure.bat, Visual Studio, OpenEye-Toolkits.sln


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

    1. From the ``examples`` directory where you installed the toolkits,
    execute ``configure-VS<ver>x.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
--------------------

.. index:: running toolkit 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
=========================

.. index:: building toolkit projects

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

Building with CMake (Linux / macOS)
------------------------------------

.. index:: Linux, macOS, CMake, gcc, g++, configure

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 in
    ``openeye/toolkits/examples``.

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

.. code-block:: cmake

   cmake_minimum_required(VERSION 3.31)

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

   # 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
       oemath
       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
   :ref:`chapter_oechem_interface` 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.


.. _section_cpp_single_build:

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

.. index:: building toolkit projects, configure.bat, Windows, Visual Studio, Project.sln

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 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.

.. code-block:: cmake

    cmake_minimum_required(VERSION 3.31)

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

.. index:: building toolkit projects

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.
