General

What is the difference between an OpenMS tool and util?

A tool starts its lifecycle in UTILS and may exist without being thoroughly tested. Tools may be promoted from UTILS to TOOLS if they are stable enough, are fully tested, fully documented, and a test workflow exists.

I have written a class for OpenMS. What should I do?

Follow the Coding Conventions coding conventions.

To summarize:

The coding style (brackets, variable names, etc.) must conform to the conventions.
The class and all the members should be properly documented.
Check your code with the tool tools/checker.php. Call php tools/checker.php for detailed instructions.

Please open a pull request and follow the pull request guidelines.

How to use QT designer to create GUI widgets?

Create a class called Widget: Create .ui-File with QT designer and store it as Widget.ui.. Add the class to sources.cmake. From the .ui-File the file include/OpenMS/VISUAL/UIC/ClassTemplate.h is generated by the build system.

Note: Do not check in this file, as it is generated automatically when needed.

Derive the class Widget from WidgetTemplate. For further details, see the Widget.h and Widget.cpp files.

Can the `START_SECTION-macro` not handle template methods that have two or more arguments?

Insert round brackets around the method declaration.

Where are the binary installers created?

View the binary installers at the build archive.

Please verify the creation date of the individual installers, as there may have been an error while creating the installer.

Build system

The following questions are related to the build system.

View the cmake website for more information.

What are user definable `CMake` cache variables?

User definable CMake cache variables allow the user to pass options to CMake which will influence the build system. The most important option that should be given when calling CMake.exe is:

CMAKE_FIND_ROOT_PATH, which is where CMake will search for additional libraries if they are not found in the default system paths. By default we add OpenMS/contrib.

If you have installed all libraries on your system already, there is no need to change CMAKE_FIND_ROOT_PATH. For contrib libraries, set the variable CMAKE_FIND_ROOT_PATH.

On Windows, the contrib folder is required, as there are no system developer packages. To pass this variable to CMake use the -D switch e.g. cmake -D CMAKE_FIND_ROOT_PATH:PATH="D:\\somepath\\contrib".

Everything else can be edited using ccmake afterwards.

The following options are of interest:

CMAKE_BUILD_TYPE: To build Debug or Release version of OpenMS. Release is the default
CMAKE_FIND_ROOT_PATH: The path to the contrib libraries.
Note
Provide more then one value here (e.g., -D CMAKE_FIND_ROOT_PATH="/path/to/contrib;/usr/" will search in your contrib path and in /usr for the required libraries).
STL_DEBUG: Enables STL debug mode.
DB_TEST (deprecated): Enables database testing.
QT_DB_PLUGIN (deprecated): Defines the db plugin used by Qt.

View the description for each option by calling ccmake.

Can I use another solver other than GLPK?

Other solvers can be used, but by default, the build system only links to GLPK (this is how OpenMS binary packages must be built). To to use another solver, use cmake ... -D USE_COINOR=1 .... and refer to the documentation of the LPWrapper class.

I changed the `contrib` path, but re-running `CMake` won't change the library paths?

Once a library is found and its location is stored in a cache variable, it will only be searched again if the corresponding entry in the cache file is set to false.

Warning: If you delete the `CMakeCache.txt`, all other custom settings will be lost.

The most useful targets will be shown to you by calling the targets target, i.e. make targets.

`CMake` can't seem to find a Qt library (usually `QtCore`).

CMake finds QT by looking for qmake in your PATH or for the Environment Variable QTDIR. Set these accordingly.

Make sure there is no second installation of Qt (especially the MinGW version) in your local environment.

Warning: This might lead CMake to the wrong path (it's searching for the Qt*.lib files). You should only move or delete the offending Qt version if you know what you are doing.

A save workaround is to edit the CMakeCache file (e.g. via ccmake) and set all paths relating to QT (e.g. QT_LIBRARY_DIR) manually.

(Windows) What version of Visual Studio should I use?

It is recommended to use the latest version. Get the latest CMake, as its generator needs to support your VS. If your VS is too new and there is no CMake for that yet, you're gonna be faced with a lot of conversion issues. This happens whenever the Build-System calls CMake (which can be quite often, e.g., after changes to CMakeLists.txt).

How to speed up the compile process

To speed up the compile process of OpenMS, use several threads. If you have several processors/cores, build OpenMS classes/tests and TOPP tools in several threads. On Linux, use the make option -j: make -j8 OpenMS TOPP test_build.

On Windows, Visual Studio solution files are automatically build with the /MP flag, such that Visual Studio uses all available cores of the machine.

Continuous integration

How does `travis` work?

Travis is an automated system for continuous integration and each new commit and pull request is automatically run through the travis build system. This is controlled by a .travis.yaml file in the source tree.

What can we do if `travis` times out?

First, restart travis, as it sometimes hangs. Since travis builds on shared infrastructure, the next build may work better. This needs to be done by an OpenMS core developer.

Since we use extensive caching, the build may take much longer when many files are touched and may never complete (running into the travis time limit). In that case, we can rebuild the cache using the following approach:

$ git cherry-pick <git-sha>
$ git push origin develop
# Now wait for the build to complete
$ git revert <git-sha>
$ git push origin develop

Working in IDEs

Why are there no `source/TEST` and `source/APPLICATIONS/TOPP|UTILS` folder?

All source files added to an IDE are associated with their targets. Find the source files for each test within its own subproject. The same is true for the TOPP and UTILS classes.

I'm getting the error "Error C2471: cannot update program database"

Warning: This is a bug in Visual Studio and there is a bug fix. Only apply it if you encounter the error. The bug fix might have unwanted side effects!

Visual Studio can't read the clang-format file.

Depending on the Visual Studio version it might get an error like Error while formating with ClangFormat. This is because Visual Studio is using an outdated version of clang-format. Unfortunately there is no easy way to update this using Visual Studio itself. There is a plugin provided by LLVM designed to fix this problem, but the plugin doesn't work with every Visual Studio version. In that case, update clang-format manually using the pre-build clang-format binary. Both the binary and a link to the plugin can be found here. To update clang-format download the binary and exchange it with the clang-format binary in your Visual Studio folder. For Visual Studio 19 it should be located at: C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/Llvm/bin.

The indexer gets stuck at a file that includes the directive `#includes seqan`

It seems that SeqAn code is not compatible with older eclipse C++ indexers. You should upgrade to eclipse galileo (CDT 6.0.x). Also, increase the available memory limit in eclipse.ini, e.g. -Xmx1024m for one gig.

The parser is confused after OPENMS_DLLAPI and does not recognize standard C++ headers

Go to Project > Properties > C/C++ Include Paths and Preprocessor Symbols > Add Preprocessor symbol -> "OPENMS_DLLAPI=". This tells eclipse that the macro is defined empty. In the same dialog add an external include path to e.g. /usr/include/c++/4.3.3/, etc. The issue with C++ headers was fixed in the latest galileo release.

Hints to resolve the OPENMS_DLLAPI issue using the cmake generator are welcome.

What is the difference between class tests and tool tests?

Class tests are unit tests that typically test the functionality of a class. They get built as standalone "additional" executables that include the class to be tested and the testing utility classes to test outcomes of single functions of the class. Unless you've added functions that are intended to be used outside of your new additional mode, you don't need to add anything.

Tool tests are using the tool executable that the user would also receive. We use those executables to run the full algorithm on a small test dataset, to ensure that from version to version, the results stay the same.

How to add a new TOPP test

Each tool test consists of:

An executable call on a test dataset (by using either fixed command line parameters or a .ini file).
A FuzzyDiff call that compares the temporary output file of the last call and a reference test output that you have to provide.
A line to add a dependency of the FuzzyDiff call on the actual executable call (so they get executed after each other). Use e.g., ctest -V -R IDMapper to only test tests that include the regex IDMapper (-V is just verbose). Make sure to build the IDMapper and IDMapper_test executable after it is edited. ctest does not have any automatic dependency on the timestamps of the executables.

How to add a new class test

Add a test to every new class added to OpenMS.

To add a test:

Add the class test to src/tests/class_tests/<sub-project>/ (e.g., src/tests/class_tests/openms/source/NewFileFormat_test.cpp).
Add the test to the executables.cmake file in the test folder.
Add them to git with the command git add

A test template for your specific class can be generated using the create_test.php script found in tools/.

To generate a test template:

Make sure you generate XML files containing the class information make xml.
Call:
php tools/create_test.php /BUILD_DIRECTORY/ /PATH_TO_HEADER/MyClass.h \

"FIRSTNAME LASTNAME" > ./src/tests/class_tests/openms/source/MyClass_test.cpp

How to add a new GUI test for a class

Suppose you want to create a GUI class for the class called MyClass. To add a new GUI test:

Create the MyClass_test.cpp in src/tests/class_tests/openms_gui/source.
Add it to src/tests/class_tests/openms_gui/CMakeLists.txt in the GUI section.
Have a look at existing GUI tests, as they use the QT TestLib framework and not the OpenMS macros.

All tests fail when executing `make_test`

Check the LD_LIBRARY_PATH environment variable:

Print the LD_LIBRARY_PATH with echo $LD_LIBRARY_PATH. If your /lib/ folder is included, check that libOpenMS.so is present. With the ldd command, you can show the libraries used by an executable, e.g. ldd /bin/ClassTest_test.

Debugging

The following section provides information on how to debug your code.

How to find out which shared libraries are used by an application

Linux: Use ldd.

Windows (Visual studio console): See Dependency Walker (use x86 for 32 bit builds and the x64 version for 64 bit builds. Using the wrong version of depends.exe will give the wrong results) or dumpbin /DEPENDENTS OpenMS.dll.

How to get a list of the symbols defined in a (shared) library or object file?

Linux: Use nm <library>.

Use nm -C to switch on demangling of low-level symbols into their C++-equivalent names. nm also accepts .a and .o files.

Windows (Visual studio console): Use dumpbin /ALL <library>.

Use dumpbin on object files (.o) or (shared) library files (.lib) or the DLL itself e.g. dumpbin /EXPORTS OpenMS.dll.

How to profile code

IBM's profiler, available for all platforms (and free for academic use): Purify(Plus) and/or Quantify.

Windows: this is directly supported by Visual Studio (Depending on the edition: Team and above). Follow their documentation.

Linux:

Build OpenMS in debug mode (set CMAKE_BUILD_TYPE to Debug).
Call the executable with valgrind: valgrind –tool=callgrind.
Warning
Other processes running on the same machine can influence the profiling. Make sure your application gets enough resources (memory, CPU time).
Start and stop the profiling while the executable is running e.g. to skip initialization steps.
Start valgrind with the option –instr-atstart=no.
Call callgrind -i [on|off] to start/stop the profiling.
The output can be viewed with kcachegrind callgrind.out.

How to check code for memory leaks

Build OpenMS in debug mode (set CMAKE_BUILD_TYPE to Debug).
Call the executable with valgrind: valgrind –suppressions=OpenMS/tools/valgrind/openms_external.supp –leak-check=full <executable> <parameters>.

Common errors are:

Invalid write/read ... - Violation of container boundaries.
... depends on uninitialized variable - Uninitialized variables.
... definitely lost - Memory leak that has to be fixed.
... possibly lost - Possible memory leak, so have a look at the code.

For more information see the valgrind documentation.

Release

View preparation of a new OpenMS release to learn more about contributing to releases.

Table of Contents