If OpenMS' TOPP tools are not enough in a certain scenario, you can either request a change to OpenMS, if you feel this functionality is useful for others as well, or modify/extend OpenMS privately. For the latter, there are multiple ways to do this: You can modify the developer version of OpenMS by changing existing tools or adding new ones. Or you use an External Project to write a new tool, while not touching OpenMS itself (see below on how to do that). Once you've finished your new tool, and it only needs to run on the development machine, you're done. If you want to ship it to a new client machine, see Shipping your external code to a new machine .

Compiling external code

It is very easy to set up an environment to write your own programs using OpenMS. Make sure you downloaded and installed the source package of OpenMS/TOPP properly. Note that you cannot use the 'install' target when working with the development version of OpenMS - it must be built and used within the build tree.

All important compiler settings and preprocessor definitions along with the OpenMS library will be available to you. The most important variables are:

OpenMS_INCLUDE_DIRECTORIES - all include directories containing OpenMS headers

and the OpenMS target itself (which you can link against).

The example that follows will be explained in details:

cmake_minimum_required(VERSION 3.24 FATAL_ERROR)
 
### example CMakeLists.txt to develop C++ programs using OpenMS
project("Example_Project_using_OpenMS")
 
## list all your executables here (a corresponding .cpp file should exist, e.g. Main.cpp)
set(my_executables
  Main
)
 
## list all classes here, which are required by your executables
## (all these classes will be linked into a library)
set(my_sources
  ExampleLibraryFile.cpp
)
 
## find OpenMS: provides the imported targets OpenMS::OpenMS (the library) and OpenMS::OpenSwathAlgo.
## If this fails, point CMake at an installation or build tree with -DOpenMS_DIR=<prefix>/lib/cmake/OpenMS
## (<prefix>/CMake on Windows, or the OpenMS build directory), or add <prefix> to CMAKE_PREFIX_PATH.
find_package(OpenMS CONFIG REQUIRED)
message(STATUS "Found OpenMS ${OpenMS_VERSION} at ${OpenMS_DIR}")
 
## library with additional classes from above
add_library(my_custom_lib STATIC ${my_sources})
target_link_libraries(my_custom_lib PUBLIC OpenMS::OpenMS)
 
## add targets for the executables
foreach(i ${my_executables})
  add_executable(${i} ${i}.cpp)
  ## link executables against OpenMS
  target_link_libraries(${i} PRIVATE OpenMS::OpenMS my_custom_lib)
endforeach(i)

The command project defines the name of the project - the name is only of interest of you're working in an IDE or want to export this project's targets. To compile your program just append it to the my_executables list. If you also use object files (classes which do not contain a main program), append them to the my_sources list. In the next step CMake creates a statically linked library of the object files, listed in my_sources. This simple CMakeLists.txt example can be extended to also build shared libraries, include other external libraries and so on.

An example external project can be found in OpenMS/share/OpenMS/examples/external_code. Copy these files to a separate directory and use CMake to configure it (here as an in-source build).

cd <path_to_external_project>

cmake -G "<generator>" .

For more information visit the website of cmake at cmake.org and consult the documentation.
Have fun coding with OpenMS!

Shipping your external code to a new machine

If you've modified OpenMS itself and not used an external project you can just use our installer scripts to build your own OpenMS installer for your platform and ship that to a client machine.

If you've used an external project and have a new executable (+ an optional new library), you can use the installer approach as well, and manually copy the new executable to the TOPP binary directory (e.g. on Windows this could be c:/program files/OpenMS/bin, on Linux it could be /bin.

If you do NOT use the installer, you can copy all required files manually, plus a few extra steps - see below. What needs to be done is a little platform dependent, thus very cumbersome to explain. You should look at the cmake installer scripts, to see whats required (for Mac and Linux see OpenMS/cmake/package*.cmake, for Windows see https://github.com/OpenMS/windows-installer/OpenMS_installer.nsi ).
In short:

copy the OpenMS/share/OpenMS directory to the client machine (e.g. <client/my_dir>/share) and set the environment variable OPENMS_DATA_PATH to this directory
copy the OpenMS library (OpenMS.dll for Windows or OpenMS.so/.dylib for Linux/Mac) to <client/my_dir>/bin
[Windows only] if you built without vcpkg and linked third-party libraries (e.g. libxml2) as DLLs, copy those DLLs to <client/my_dir>/bin as well. A vcpkg build links them statically, so nothing needs to be copied for them.
[Windows only] install the VS redistributable package (see Microsoft Homepage) on the client machine which corresponds to the VS version that was used to compile your code (use the correct redistributable package! , i.e. architecture 32|64bit, VS version, VS Service Pack version). If you choose the wrong redistributable package, you will get "Application failed to initialize properly..." error messages.

Boost is an implementation dependency

The installed shared OpenMS library can be used without Boost headers or a Boost CMake package. Boost is still required to build OpenMS itself and may remain a runtime dependency of its binaries. Static consumers also need its link dependencies.

Use OpenMS::RegularExpression for the compiled-pattern overloads of SpectrumNativeIDParser::extractScanNumber and SpectrumLookup::extractScanNumber. Named groups and the existing regex syntax are retained. In pyOpenMS, pass a pattern string and the explicit no_error argument; the two-argument overload still accepts a native-ID CV accession.

IdentificationData collections preserve uniqueness, ordered traversal and stable references, but they are std::set-based IDDataContainers now, and their iterators are the set's. Use the OpenMS aliases instead of naming Boost.MultiIndex types. Boost-specific container operations outside the IDDataContainer interface need to be adapted: modify() takes the position by reference and leaves it on the record (or, after a rejected duplicate, on the next one), and getStepsAndScoresByStep() returns a lightweight lookup view (find(), end(), modify()) by value. Internal headers such as ANALYSIS/ID/IDBoostGraph.h are not part of the installed interface. Indistinguishable protein groups are available through BasicProteinInferenceAlgorithm::annotateIndistinguishableGroups().

RandomShuffler retains its seeded shuffle sequence; use its seed() method instead of accessing a Boost engine. Checked integer conversions in public templates now throw OpenMS::Exception::OutOfRange on overflow.

These changes affect the C++ ABI: rebuild applications and extensions against the new headers and library. Applications that use Boost independently must locate and link their own Boost targets.

The same rule applies to the other implementation dependencies. A header whose declarations name an Arrow, OpenTIMS, libxml2 or SQLite type is internal and is not installed: FORMAT/ParquetFile.h and FORMAT/ZipRandomAccessFile.h (Arrow builders, tables and files) and FORMAT/RationalScan2ImConverter.h (an OpenTIMS converter subclass) joined that group, as did ML/CLUSTERING/HashGrid.h, whose Boost.Unordered containers are what make QT clustering produce the same result on every platform. The installed readers and writers built on them – XICParquetFile, QPXFile, BrukerTimsFile and the rest – take and return OpenMS types and need none of those packages. A build that configures OpenMS fails outright if a public header includes anything but OpenMS headers, the C++ standard library, operating-system headers and the headers of the public dependencies (OpenMP), so a dependency added later is kept out of the installed headers too.