I am new to OpenMS. What should I do first?
Is there a central URL for OpenMS developers?
https://sourceforge.net/apps/trac/open-ms/
In the TRAC has a Wiki with important links, the svn timeline and more.
How do I update the website?
Login to the wordpress admin area at www.openms.de/wp-admin with your username and password assigned by the current Homepage maintainers.
Can I use QT designer to create GUI widgets?
Yes! If you want to create a class called Widget:
Create .ui-File with QT designer and store it as Widget.ui
.
sources.cmake
. From the .ui-File the file include/OpenMS/VISUAL/UIC/ClassTemplate.h
is generated by the build system.
DO NOT CHECK-IN THIS FILE, AS IT IS GENERATED AUTOMATICALLY, WHEN NEEDED!!!
Widget
from WidgetTemplate
. You need to check in the Widget.h
and Widget.C
files. Can the START_SECTION-macro not handle template methods that have two or more arguments?
Put round brackets around the method declaration. Then it should work.
Are there binary installers created from the SVN HEAD?
Currently binary installers from the HEAD are available only for Windows:
http://ftp.mi.fu-berlin.de/bielow/OpenMS/
What is CMake?!
CMake builds BuildSystems for different platforms, e.g. VisualStudio Solutions on Windows, Makefiles on Linux etc. This allows us to define in one central location (namely CMakeLists.txt) how OpenMS is build and have the platform specific stuff handled by CMake. See http://www.cmake.org for more information.
How do I use CMake?!
See Installation instructions for your platform. In general, you call CMake(.exe) with some parameters to create the native build-system. Afterwards you can (but usually don't have to edit the current configuration using a GUI named ccmake (or CMake-GUI in Windows), which ships with CMake).
Note: whenever ccmake is mentionend in this document, substitute this by CMake-GUI if your OS is Windows. You can also edit the CMakeCache.txt file directly.
How do I generate a build-system for Eclipse, KDevelop, CodeBlocks etc?!
Type cmake
into a console. This will list the available code generators available on your platform, which you can pass to CMake using the -G
option.
What are user definable CMake Cache Variables?!
They allow the user to pass options to CMake which will influence the build system. The most important option which should be given when calling CMake.exe is:
cmake -D CMAKE_FIND_ROOT_PATH:PATH="D:\\svn\\contrib"
Everything else can be edited using ccmake afterwards. The following options are of interest:Can I use another solver than GLPK?!
Yes, but by default the build system only links against GLPK (this is how OpenMS binary packages must be build!). To use another solver try cmake ... -D USE_COINOR=1 ....
And look at the documentation of the LPWrapper class.
How do I switch to Debug/Release configuration?!
For Makefile generators (typically on Linux) you can set the CMAKE_BUILD_TYPE variable to either Debug or Release by calling ccmake.
For Visual Studio, this is not necessary as all configurations are generated and you can choose the one you like within the IDE itself.
The 'Debug' configuration enabled debug information. The 'Release' configuration disables debug information and enables optimization.
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. You can simply delete the CMakeCache.txt, but all other custom settings will be lost as well.
What are the most useful (make) targets?!
In Visual Studio you can see all targets on the left. For Makefiles type make help
.
However, this list is quite long. 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)! What now?
CMake finds QT by looking for 'qmake' in your PATH or for the Environment Variable QTDIR! Set these accordingly.
If the problem still persists: do you have a second installation of Qt (especially the MinGW version?)? This might lead CMake to the wrong path (it's searching for the Qt*.lib files). You should only move/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?
Use the latest if you can. 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 do I add a new class MyClass
to the build system?
How do I add a new directory MYDIR
to the build system?
How do I add a new test for the class MyClass
?
How do I add a new TOPP test?
Add commands to OpenMS/source/TEST/TOPP/CMakeLists.txt (where it fits alphabetically).
How do I add a new GUI test (for QT Gui classes) for the class MyClass
?
(Linux) When executing 'make test', all tests fail.
Please check the LD_LIBRARY_PATH environment variable:
Build with several threads.
If you have several pocessors/cores you can build OpenMS classes/tests and TOPP tools in 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 VS uses all available cores of the machine.
How do I run a single test?
You can can execute an OpenMS class test using the CTest regular expressions:
> ctest -V -R "^<class>_test"
To build a class test, you simply call the respective make target in ./source/TEST:
> make <class>_test
To run a TOPP test, you can use:
> ctest -V -R "TOPP_<tool>"
To build the tool, use:
> make <tool>
How do I debug uncaught exceptions?
There is a mechanism to have a core dumped if an uncaught exception occurs.
To enable it, the environment variable OPENMS_DUMP_CORE has to be set.
Each time an uncaught exception occures, the OPENMS_DUMP_CORE variable is checked and a segmentation fault is caused, if it is set.
(Linux) Why is no core dumped, although a fatal error occured?
Try the ulimit -c unlimited command. It sets the maximum size of a core to unlimited.
Note: We observed that, on some systems, no core is dumped even if the size of the core file is set to unlimited. We are not sure what causes this problem.
(Linux) How can I set breakpoints in gdb to debug OpenMS?
Imagine you want to debug the TOPPView application and you want it to stop at line 341 of SpectrumMDIWindow.C.
Run gdb:
shell> gdb TOPPView
Start the application (and close it):
gdb> run [arguments]
Set the breakpoint:
gdb> break SpectrumMDIWindow.C:341
gdb> run
How can I find out which shared libraries are used by an application?
Linux: ldd <application>
Windows (Visual studio console): Try "Dependency Walker"(http://www.dependencywalker.com/) (use x86 for 32bit builds and the x64 version for 64bit builds. Using the wrong version of depends.exe will give wrong results!) or dumpbin /DEPENDENTS OpenMS.dll
How can I get a list of the symbols defined in a (shared) library or object file?
Linux: 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): dumpbin /ALL <library>
You can use dumpbin on object files (.o) or (shared) library files (.lib) or the DLL itself e.g. dumpbin /EXPORTS OpenMS.dll
OpenMS runs on three major platforms, each one having its own ways of doing things. Here are the most prominent causes of "it runs on Platform A, but not on B. What now?"
Reading/Writing binary files causes different behaviour ...
Usually Linux does not make a difference between text-mode and binary-mode when reading files. This is quite different on Windows as some bytes are interpreted as EOF, which lead might to a premature end of the reading process. Thus, if reading binary files make sure that you explicitly state that the file is binary when opening it!
During writing in text-mode on windows a line-break (\n) is expanded to (\r\n). Keep this in mind or use the eol-style property of subversion to ensure that line endings are correctly checked out on non-Windows systems.
unsigned int vs size_t (UInt and Size)
UInt and Size are the same on Linux GCC (i.e. both have the same size, 32bit on 32bit systems, 64bit on 64 bit systems), however on Windows this only holds for 32bit. On a 64bit Windows the UInt type is still 32bit, Size is (obviously) 64bit. This might lead to warnings (at best) or overflows and other nasty stuff. So make sure you do not rely on UInt being equal to Size - because they're not.
Paths and system functions...
This is trivial but hardcoding something like
is a big no-no! This must fail on Windows! Use Qt's QDir to get a path to the systems temporary directory if required.
Also calling things like uname
which are only available on Linux: don't!
When working with files or directories, it is usually safe to use "/" on all platforms. Even Windows understands that. Take care of spaces in directory names though. You should always quote paths if they are used in a system call to ensure that the subsequent interpreter takes the spaced path as a single entity.
The $id$ string in my test is not expanded to the SVN id. Why?
In Subversion you have to set the keyword expansion explicitly:
svn propset svn:keywords Id <file>
How do I undo a commit?
Suppose you want to undo the revision 25 in the head branch. Go to your working copy of the head branch and merge in the reversed changes of revision 25:
svn merge -r 25:24 https://open-ms.svn.sourceforge.net/svnroot/open-ms/OpenMS/ .
svn commit -m "Removed revision 25"
How do I create a branch?
svn copy https://open-ms.svn.sourceforge.net/svnroot/open-ms/OpenMS https://open-ms.svn.sourceforge.net/svnroot/open-ms/branches/[name]/
How does merging branches work?
To merge changes from the source
branch into the target
branch, do the following:
target
branch. svn merge -r [from]:[to] https://open-ms.svn.sourceforge.net/svnroot/open-ms/[source]
Example 1: From HEAD to release branch
Suppose you want to merge the changes you made in revision 2325 of the HEAD (/OpenMS) into the current revision of the release branch for target branch (see http://open-ms.svn.sourceforge.net/viewvc/open-ms for the actual names of branches).
svn co https://open-ms.svn.sourceforge.net/svnroot/open-ms/branches/[target]/
rv
in (rv-1):rv
corresponds to your svn-revision number you just committed)svn merge -r 2324:2325 https://open-ms.svn.sourceforge.net/svnroot/open-ms/OpenMS/
Example 2: Merge branch into HEAD
Suppose you want to merge the changes you made to a branch into the HEAD. The current revision is 25 and you added the branch in revision 10.
cd OpenMS/
(HEAD)svn update
svn merge -r 10:25 https://open-ms.svn.sourceforge.net/svnroot/open-ms/branches/[source]/
How do I speed up the SVN Repo and/or upgrade to a new SVN version on the server?
This should only be done if you are sure what you are doing! You might destroy the whole OpenMS SVN!!! Make a backup before (preferably not on SF servers, e.g. by using
$ rsync -av open-ms.svn.sourceforge.net::svn/open-ms/* .
Now here's how you do the upgrade
Where can I find the definition of the main page?
OpenMS/doc/doxygen/public/Main.doxygen
Where can I add a new module?
OpenMS/doc/doxygen/public/Modules.doxygen
How is the parameter documentation for classes derived from DefaultParamHandler created?
You have to add your class to the program OpenMS/doc/doxygen/parameters/DefaultParamHandlerDocumenter.C. This program generates a html table with the parameters. This table can then be included into the class documentation using the following doxygen command:
Note that parameter documentation is automatically generated for TOPP/UTILS included in the static ToolHandler.C tools list. To include TOPP/UTILS parameter documentation use following doxygen command:
or
You can test if everything worked by calling make doc_param_internal . The parameters documentation is written to OpenMS/doc/doxygen/parameters/output/.
How is the command line documentation for TOPP/UTILS tools created?
The program OpenMS/doc/doxygen/parameters/TOPPDocumenter.C creates the command line documentation for all classes that are included in the static ToolHandler.C tools list. It can be included into the documentation using the following doxygen command:
You can test if everything worked by calling make doc_param_internal . The command line documentation is written to OpenMS/doc/doxygen/parameters/output/.
What are the important files for adding a new tutorial section?
OpenMS tutorial:
OpenMS/doc/OpenMS_tutorial/refman_overwrite.tex.in (for PDF tutorials)
OpenMS/doc/doxygen/public/OpenMS_Tutorial_html.doxygen (for html tutorials)
TOPP and TOPPView tutorial:
OpenMS/doc/TOPP_tutorial/refman_overwrite.tex.in (for PDF tutorials)
OpenMS/doc/doxygen/public/TOPP_Tutorial_html.doxygen (for html tutorials)
What is to do for a bugfix?
What has each developer to do for a release?
Each maintainer must check his/her classes and TOPP tools. Keep in mind that missing documention scares off potential users!
Here is a list of what is to do:
How is a major release done?
How is the platform-independent source release package created?
cd <OpenMS> find . -name "*.h" -o -name "*.C" -o -name "*.txt" | xargs sed -i 's/(C) 2003-2011/(C) 2003-2012/g'
CMakeLists.txt
of contrib. CMakeLists.txt
of OpenMS (three OPENMS_PACKAGE_VERSION_* variables, and the contrib version check) source/TEST/VersionInfo_test.C
source/VISUAL/ICONS/
.doc/code_examples/
can be compiled and executed (target 'Tutorials_build' and 'Tutorials_exec') make doc
(not doc_internal
!). make doc_tutorials
. tools/make_source_package.sh
according to the help shown when executed. How is the Windows binary release package created?
https://open-ms.svn.sourceforge.net/svnroot/open-ms/win_installer
win_installer/README
for further instructions How are the binary release packages for different Linux distributions created?
> cmake -D INSTALL_PREFIX=/usr -D PACKAGE_TYPE=rpm/deb ...
/home/myusername/binary_release/OpenMS/share/OpenMS
.make TOPP UTILS doc doc_tutorials
make package
First check that the executable you are calling actually is the correct one (in case you have multiple OpenMS version installed), and also that it uses the correct OpenMS library (check PATH (Win) or LD_LIBRARY_PATH (Linux)). Otherwise you might get the strangest access violations, pointing to arbitrary code.
How can I profile my code?
'valgrind –tool=callgrind <executable> <parameters>'
'callgrind -i [on|off]'
to start/stop the profiling 'kcachegrind callgrind.out.<process id>'
(Linux) How do I check my code for memory leaks?
'valgrind –leak-check=full <executable> <parameters>'
'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 wemory leak, so have a look at the code How to create an icon file for a TOPP tool under Windows?
What do I have to do to add a new TOPP tool?
source/APPLICATIONS/ToolHandler.C
source/APPLICATIONS/TOPP/executables.cmake
What do I have to do to add a new UTILS tool?
source/APPLICATIONS/ToolHandler.C
source/APPLICATIONS/UTILS/executables.cmake
OpenMS / TOPP release 1.11.1 | Documentation generated on Sun Sep 7 2014 06:42:38 using doxygen 1.8.8 |