 |
OpenMS
|
The following contains answers to typical questions from developers about OpenMS.
Follow the Coding Conventions coding conventions.
To summarize:
tools/checker.php. Call php tools/checker.php for detailed instructions. Please open a pull request and follow the pull request guidelines.
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.
Derive the class Widget from WidgetTemplate. For further details, see the Widget.h and Widget.cpp files.
START_SECTION-macro not handle template methods that have two or more arguments?Insert round brackets around the method declaration.
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.
The following questions are related to the build system.
View the cmake website for more information.
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. -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.
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.
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.
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.
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.
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).
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.
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.
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:
source/TEST and source/APPLICATIONS/TOPP 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 classes.
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.
#includes seqanIt 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.
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.
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.
Each tool test consists of:
.ini file). FuzzyDiff call that compares the temporary output file of the last call and a reference test output that you have to provide. 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. Add a test to every new class added to OpenMS.
To add a test:
src/tests/class_tests/<sub-project>/ (e.g., src/tests/class_tests/openms/source/NewFileFormat_test.cpp). executables.cmake file in the test folder. 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 xml. Suppose you want to create a GUI class for the class called MyClass. To add a new GUI test:
MyClass_test.cpp in src/tests/class_tests/openms_gui/source. src/tests/class_tests/openms_gui/CMakeLists.txt in the GUI section. make_testCheck 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.
The following section provides information on how to debug your code.
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.
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.
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:
CMAKE_BUILD_TYPE to Debug). valgrind –tool=callgrind. valgrind with the option –instr-atstart=no. callgrind -i [on|off] to start/stop the profiling. kcachegrind callgrind.out. CMAKE_BUILD_TYPE to Debug). 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.
View preparation of a new OpenMS release to learn more about contributing to releases.
1.9.1