Developer Guidelines For Adding New Dependent Libraries#
Our dependency library philosophy#
In short, requirements for adding a new library are:
availability for all platforms
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)
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
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
All the headers under
$buildfolder/include/$libraryname(the only exception to leave out the library name subfolder is when the
Find$libraryname.cmakedoes not support this subfolder e.g. because system libraries are not structured like this, see boost).
All needed files into
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).