Building Source Code#

The Open Chemistry project uses Git for version control, and CMake to direct the build process. The openchemistry repository contains git submodules with other actively developed projects such as Avogadro and MoleQueue. It will also automatically download and build third party dependencies, with variables named USE_SYSTEM_LIBRARY to attempt to find and build against system versions.

This page goes through the steps of building the Open Chemistry projects using the openchemistry git repository. It is entirely possible to build each project individually without using the “superbuild” approach, but you will need to ensure all dependencies are built and can be found by the project.

Once successfully built you will be left with several build directories which you can treat as normal build directories, developing and compiling from inside them largely ignoring the outer build tree.

Cloning Repositories#

To clone the Open Chemistry repository that contains the other projects as submodules,

git clone --recursive https://github.com/OpenChemistry/openchemistry.git

Or if you have a GitHub account with SSH key (e.g., for contributing changes):

git clone --recursive [email protected]:OpenChemistry/openchemistry.git

Updating#

In order to update the repository from the openchemistry module you can run,

git pull
git submodule update --init

Prerequisites#

The Open Chemistry projects have a number of prerequisites, and these vary by platform. On Windows Visual Studio 2017 is best supported. The superbuild will attempt to build a number of dependencies, on Linux you are likely best off installing these with your package manager, and on macOS the homebrew package manager works well.

We should add a package listing for various Linux distributions, but as a guide you will need:

  • a C/C++ compiler that supports C++17

  • OpenGL

  • Qt 5.6+

  • CMake

  • Python

Debian-based Distribution or Ubuntu#

You can install prerequisites with the following commands:

apt-get update && \
 apt-get install -y cmake curl build-essential qtbase5-dev qtdeclarative5-dev zlib1g-dev libxml2-dev git libqt5svg5-dev libqt5gui5 libqt5concurrent5 rapidjson && \

If you need a newer cmake version (replace aarch64 with your architecture or go to CMake Releases)

apt-get purge cmake && \
 curl -L -v -o /tmp/bin https://github.com/Kitware/CMake/releases/download/v3.26.5/cmake-3.26.5-linux-aarch64.sh && \
 chmod +x /tmp/bin && \
 cd /usr && \
 /tmp/bin

Fedora 39#

sudo dnf update
sudo dnf install -y cmake gcc gcc-g++ qt5-qtbase-devel zlib-devel libxml2-devel git curl qt5-qtsvg-devel kernel-devel glew-devel

Building#

It is recommended that you create a build tree outside of the source tree. Assuming you are in the directory where you cloned the repository the following commands will create a build tree, configure it and build.

mkdir openchemistry-build
cd openchemistry-build
cmake ../openchemistry
cmake --build . --config Release

You may wish to run cmake-gui in the build directory once it has been configured. You can build against system libraries to avoid building them (examples include Boost, Eigen, etc), and turn testing on globally (ENABLE_TESTS) if you would like to ensure all tests are configured and built for sub-projects. The –config argument to cmake –build is only used on the Windows platform with MSVC, and can be removed elsewhere.

Finding Qt, Windows Generators#

We go to great care to use Qt5_DIR as the base for all Qt 5 modules, so setting the correct Qt5_DIR should result in a valid tree, you can also use CMAKE_PREFIX_PATH to point at the install prefix of Qt. When setting Qt5_DIR for Windows, using Qt 5.10.1 as an example, you should set the variable to ‘C:/Qt/Qt5.10.1/5.10.1/msvc2017_64/lib/cmake/Qt5’ (without the quotes). As you upgrade, you can usually just replace the version (that occurs twice), you must also be careful to match the CMake generator to the compiler and architecture on Windows, I recommend ‘Visual Studio 15 2017 Win64’, we no longer build/test 32 bit binaries on any platform.

Normal Development#

You can also open the top-level CMakeLists.txt in Qt Creator, choose the build location, have that configure and build and then open the top-level CMakeLists.txt for each of the sub-projects. When setting the build location choose the openchemistry-build/avogadrolibs for Avogadro, openchemistry-build/molequeue for MoleQueue, etc. Once you have compiled the top-level, for normal day-to-day development you are free to ignore it and perform the majority of work in the project being developed.

Build Tree Layout#

The build tree mirrors the source tree for most active projects. So avogadrolibs is in the same relative path in the source and build trees. For things such as Boost which are built from a source tarball they can be found only in the build tree, and are under thirdparty/boost-prefix, these projects are dependencies but are not expected to be edited in place.

There is a prefix directory in the base of the build tree. This acts as an install prefix for all projects, with the normal include, bin, share and lib directories. This can be used to inject an additional prefix in CMAKE_PREFIX_PATH to ensure projects build by the superbuild are found. It keeps the sub-projects relatively simple as they either find stuff in the prefix, or normal system paths.

Running Executables#

It is recommended that you run the binaries from within the prefix directory in the build tree. The top-level targets (avogadroapp, molequeue, monogochem) all install to the prefix, if running make from within the individual build trees run make install to ensure you are using the latest version. On Linux and Windows running Avogadro 2 looks like,

./openchemistry-build/prefix/bin/avogadro2

On Mac, it might be:

open /Users/your-user/openchemistry-build/avogadroapp/bin/Avogadro2.app

Note that on Mac with Apple Silicon, you must sign all binaries before opening:

codesign --force --deep -s "Developer ID Application: Username (Team ID)" prefix/Avogadro2.app

Building Packages#

The molequeue and avogadroapps projects can build installers. In order to do this you must cd into the appropriate subdirectory and call make package. So to build the Avogadro 2 package,

cd avogadroapp
make package

You may need to run cmake-gui, toggle advanced variables and enable/disable packages you are interested in. They are prefixed by CPACK, and can be toggled before calling make package. A binary installer will be created in the build directory.