1. Installation

In this section, we discuss various methods of installation. There are also instructions on how to build the library from source and other comments useful to library developers.

Note

As of yet, the library is only available for Linux and will only run on 64-bit systems. However, support for other platforms is on the roadmap as well. If you are interested in a build for a different platform, feel free to express your wish on the issue tracker.

1.1. Installation with Anaconda

If you want to use the library from Python environment, this is probably the best way for you to install. All you need to do is either get the full Anaconda distribution or its lightweight variant, Miniconda.

Anaconda/Miniconda is essentially a Python distribution, package manager and virtual environment in one and makes setting up a development environment for your projects very easy. After installing Anaconda/Miniconda you need to run the following to install the molpher-lib package in your environment:

conda install -c rdkit -c lich molpher-lib

This will automatically install the latest non-development version of the library in your currently active environment. If you are interested in the development snapshots, you can specify the dev label while you install:

conda install -c rdkit -c lich/label/dev molpher-lib

Development snapshots often have the newest functionality, but may be unstable due to some experimental features.

You can test if the library works as it should by running the Molpher-lib test suite:

from molpher.tests import run

run()

1.2. Building and Installing from Source on Linux

If you want to build the source code yourself, you will have to use cmake. This section describes how to do that on a Linux machine. If you want to build the library on a different platform, this section might provide useful information as well. However, you might need to make some adjustments to the underlying CMakeLists.txt.

Note

If you manage to successfully build the library on a platform other than Linux, please, consider making a pull request and contributing your code to the official GitHub repository. Also consider giving this issue a bump up if you are interested in Windows build support.

1.2.1. Prerequisites

In order to build the library, you will need to have some tools and libraries setup on your system. You can learn about them here (if you want to get started quickly, just see the following section):

  • git – You will use it to check out the source code from the repository.

  • cmake – This tool will generate the Makefiles for the project and configure the build (searches for dependencies, makes sure libraries are correctly linked, etc.). You should use version 3.9 and higher.

  • build-essential – You will need this package in order to be able to build software on most Linux platforms. It contains a compiler and other tools important for the build.

    Note that you might encounter some problems if you decide to use an ancient compiler with poor support for the newer C++ standards (C++11 onwards). For example, g++ 5.4 and newer should be OK, but even slightly older compilers could work with no problems.

  • swig – It is used to generate the Python wrapping code (we are using version 3.0.12 at the moment).

    SWIG is only required if you made changes to the binary interface (header files under include/) and want to configure cmake with the -DRUN_SWIG=ON option (see the description of the molpher_install_python target in the section below). If this option is turned on, SWIG will be invoked by make upon build with the swig command so make sure the SWIG executable is available in the working environment or that you have correctly specified the -DCONDA_PREFIX directive, in that case cmake will look for swig in your conda environment.

  • setuptools – This Python package is needed to build and install the Molpher-lib Python package.

  • python{version}-dev – You will need this package to build Python bindings for your Python version.

    If you get ‘Missing Python.h’ compiler errors, you probably do not have this package installed.

  • dependencies – Molpher-lib depends on three third-party libraries:

    • tbb (most versions should work fine, 2019 onwards)
    • boost (most reasonably new versions should work fine, but we build against 1.73.0)
    • rdkit (there were some changes to the names of RDKit libraries, versions older than 2019.03.4 may have issues during build)
    • numpy (RDKit dependency in Python, not required if you are only building the C++ code)

    You can install these dependencies in a conda environment (see Using Conda to Manage Build Environment below) you want to use for building the library or you can build them separately in the deps subdirectory of the project repository. There is a bash script (deps/build_deps.sh) which can download and build the dependencies automatically (should only download versions that were tested with the newest version of the library). It should then be sufficient to just run:

    ./build_deps.sh --all

    If you want to obtain the dependencies yourself, you should install them in the deps/ folder in the repository root. For each dependency, there should be a folder of the same name under deps/ (for example, the path to the tbb files would be deps/tbb/). The CMakeLists.txt is configured to automatically identify and prioritize dependencies in this directory.

    You can also leverage the libraries already installed on your system. In that case, cmake should automatically find them on your path and link them during the build. The CMakeLists.txt file is configured to link against dynamic versions of all libraries so make sure you have those installed.

1.2.2. Using Conda to Manage Build Environment

If you want to use conda to manage your build environment, you can start with the environment.yml file in the root directory of the project repository (download it here):

conda env create -f environment.yml

This will create a working build environment with all libraries and tools installed. You can then point cmake to the environment prefix with -DCONDA_PREFIX=/path/to/your/env/ or set this as an environment variable. It will instruct the build system to search for python and swig commands and the required dependencies in this environment.

1.2.3. Building the Library

When your environment is set, you can start building. If you have not done so already, you need to check out the code and create a build directory

git clone https://github.com/lich-uct/molpher-lib.git
REPOSITORY_ROOT="`pwd`/molpher-lib"
mkdir ${REPOSITORY_ROOT}/cmake-build/
cd ${REPOSITORY_ROOT}/cmake-build/

Then you can initialize the cmake project:

export CONDA_PREFIX=/path/to/your/env/ # if you are using a conda build environment
cmake ..

This is the simplest configuration with default options, but sometimes you may require more customization. The cmake configuration file recognizes a few options. For example, the following will force debug mode and Python 3 during build:

cmake .. -DCMAKE_BUILD_TYPE=Debug -DPYTHON_EXECUTABLE=python3

If you want to recreate the Python wrapping code during build, you should add -DRUN_SWIG=ON. Remember, that you need to have SWIG installed in a standard location for this to work. Alternatively, you can add swig to your PATH or use -DSWIG_EXECUTABLE=/path/to/swig to tell cmake where to look for it.

When the makefile is created, you can use make to build the Molpher-lib targets:

make $CONFIG # $CONFIG is a configuration target's name

There are three important configuration targets:

  1. molpher – Builds the binaries for the C++ part of Molpher-lib.

  2. molpher_install – Will install the library in the given location.

    By default, this location is the dist/ folder in the repository root. This can be changed when the cmake project is initialized by setting CMAKE_INSTALL_PREFIX. By default, the required dependency libraries are not installed. If you want to install them with the library, you can configure cmake to do so by setting the following: -DINSTALL_TBB=ON -DINSTALL_Boost=ON -DINSTALL_RDKit=ON.

  3. molpher_install_python – This builds the C++ Python extension and installs the Python package into CMAKE_INSTALL_PREFIX.

    By default, the primary Python distribution on the system is used. You can specify a different executable with -DPYTHON_EXECUTABLE.

    If you want to update the SWIG wrapping code before this target is run, you can instruct cmake to do so with the -DRUN_SWIG=ON option. Do not forget to specify the swig path with -DSWIG_EXECUTABLE if it is installed in a non-standard location.

    When this target finishes, all required files should be in place and you should be able to import the molpher Python package, provided that your PYTHONPATH and LD_LIBRARY_PATH are set appropriately. Here is an example of how these variables can be set if standard locations are used:

    export CMAKE_INSTALL_PREFIX="${REPOSITORY_ROOT}/dist"
export DEPS_DIR=${CMAKE_INSTALL_PREFIX}/../deps
export PYTHONPATH=${DEPS_DIR}/rdkit/:${CMAKE_INSTALL_PREFIX}/lib/python3.5/site-packages
export LD_LIBRARY_PATH=${DEPS_DIR}/tbb/lib/intel64/gcc4.7:${DEPS_DIR}/rdkit/lib/:${DEPS_DIR}/boost/stage/lib:${CMAKE_INSTALL_PREFIX}/lib

    You should then be able to successfully run the Python test suite:

    from molpher.tests import run

run()

1.2.4. Building the Documentation

This documentation was generated using the build_docs.sh script under the doc directory. However, you will need a few Python packages in order to successfully build it. The build environment file defines these requirements. You can install this environment like so:

conda env create -f environment.yml

The resulting environment will be called molpher-lib-build and you can activate it by sourcing the source_2_activate file in REPOSITORY_ROOT:

. source_2_activate

This will make sure that all paths are correctly set so that you can use the version of Molpher-lib built from the current source code (using the molpher_install_python target).

Once your environment is activated, you can generate the documentation:

cd doc
./build_docs.sh

To update the GitHub pages, it is possible to run the build_docs.sh script with the `--upload` option:

build_docs.sh --upload

Note

You will need write access to the repository to be able to do this.

1.2.5. Building Conda Packages

If you want to package the build as a conda package, you can use a python script located in conda subdirectory of the repository root:

cd ${REPOSITORY_ROOT}/conda
python build.py

Attention

You will need conda-build and the jinja2 Python library to do that. These are both part of the molpher-lib-build conda environment we introduced before. It is enough to just do conda activate molpher-lib-build.

The built packages will be located at /tmp/conda-bld (from there they can be uploaded to Anaconda Cloud, for example).