Developer Guidelines For Adding New Dependent Libraries#

Our dependency library philosophy#

In short, requirements for adding a new library are:

  • indispensable functionality

  • license compatibility

  • availability for all platforms

Indispensable functionality#

In general, adding a new dependency library (of which we currently have more than a handful, e.g. Xerces-C or ZLib) imposes a significant integration and maintenance effort. Thus, the new library should add indispensable functionality. If the added value does not compensate for the overhead, alternative solutions encompass:

  • write it yourself and add to the OpenMS library (i.e. its repository) directly

  • write a TOPPAdapter which calls an external executable (placing the burden on the user to supply the executable)

License compatibility#

OpenMS has a BSD-3 clause license and we try hard to remove dependencies of GSL-like libraries. Therefore, a new library with e.g. LGPL-2 would be prohibitive.

C++ standard compatibility#

New dependency libraries needs to be compatible and therefore compilable with the same C++ standard as OpenMS.

Availability for all platforms#

OpenMS has been designed for Windows, macOS, and Linux. Therefore, the new dependency library needs to be designed for these platforms.

  • on WindowsOS this usually means, adding the new library to the Contrib in debug and release variants. In short all recent versions of Visual Studio (VS2008 and onwards) must be supported (or support must be added). This encompasses

    • a solution file (which can be either statically present or generated by a meta-system like CMake) is available

    • The library actually compiles and is linked to the dynamic VS-C++ runtime lib (since this is what the OpenMS lib will link to as well - combining static and dynamic links will lead to linker errors or segfaults).

  • on macOS it should be ensured that the library can be build on recent macOS versions (> 10.10) compiled using the mac specific libc++. Ideally the package should be available via HomeBrew or MacPorts so we can directly use those libraries instead of shipping them via the contrib. Additionally, the MacPorts and HomeBrew formulas for building the libraries can serve as blueprints on how to compile the library in a generic setting inside the contrib which should also be present.

  • on Linux since we (among other distributions) feature an OpenMS Debian package which requires that all dependencies of OpenMS are available as Debian package as well, the new library must be available (or made available) as Debian package or linked statically during the OpenMS packaging build.

How to add it to the contrib build#

Add a CMake file to OpenMS/contrib into the libraries.cmake folder on how to build the library. Preferably of course the library supports building with CMake (see Xerces) which makes the script really easy. It should support static and dynamic builds on every platform. Add the compile flag for position independent code (e.g. -fpic) in the static version. Add patches in the patches folder and call them with the macros in the macros.cmake file. Create patches with diff -Naur original_file my_file > patch.txt. If there are problems during applying a patch, make sure to double check filepaths in the head of the patch and the call of the patching macro in CMake.

  • All the libraries need to go into (e.g. copied/installed/moved) to $buildfolder/lib

  • All the headers under $buildfolder/include/$libraryname (the only exception to leave out the library name subfolder is when the Find$libraryname.cmake does not support this subfolder e.g. because system libraries are not structured like this, see boost).

  • All needed files into $buildfolder/share/$libraryname

Then test the build on your platform including a subsequent build of OpenMS using that library. Submit a pull request to OpenMS/contrib. Submit a pull request to OpenMS/OpenMS that updates the contrib submodule. Make sure the libraries are correctly shipped in pyOpenMS and the packages (especially dynamic libraries and especially on Windows).