File: FAQ_Internal.html

package info (click to toggle)
openms 1.11.1-5
links: PTS, VCS
area: main
in suites: jessie, jessie-kfreebsd
size: 436,688 kB
ctags: 150,907
sloc: cpp: 387,126; xml: 71,547; python: 7,764; ansic: 2,626; php: 2,499; sql: 737; ruby: 342; sh: 325; makefile: 128
file content (889 lines) | stat: -rw-r--r-- 43,790 bytes
<HTML>
<HEAD>
<TITLE>Internal FAQ</TITLE>
<LINK HREF="doxygen.css" REL="stylesheet" TYPE="text/css">
<LINK HREF="style_ini.css" REL="stylesheet" TYPE="text/css">
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<A href="index.html">Home</A> &nbsp;&middot;
<A href="classes.html">Classes</A> &nbsp;&middot;
<A href="annotated.html">Annotated Classes</A> &nbsp;&middot;
<A href="modules.html">Modules</A> &nbsp;&middot;
<A href="functions_func.html">Members</A> &nbsp;&middot;
<A href="namespaces.html">Namespaces</A> &nbsp;&middot;
<A href="pages.html">Related Pages</A>
<HR style="height:1px; border:none; border-top:1px solid #c0c0c0;">
<!-- Generated by Doxygen 1.8.5 -->
</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">Internal FAQ </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h2 style="border-top:2px solid grey;">General information</h2>
<ul>
<li>
<p class="startli"><b>I am new to OpenMS. What should I do first?</b><br/>
 </p>
<ol>
<li>
Check out the developement version of OpenMS (see website). </li>
<li>
Try and build OpenMS according to the installation instructions. </li>
<li>
Read the OpenMS Coding Convention. </li>
<li>
Read the OpenMS Tutorial. </li>
<li>
Create a SourceForge account and send your account name to your supervisor.<br/>
 He then adds you to the OpenMS developers team. </li>
<li>
Register to the open-ms-general and open-ms-developers mailing list.<br/>
 (You can see the developers list only if you are logged in to Sourceforge and if you are a OpenMS developer). </li>
</ol>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>Is there a central URL for OpenMS developers?</b><br/>
 <br/>
 <br/>
 <a href="https://sourceforge.net/apps/trac/open-ms/">https://sourceforge.net/apps/trac/open-ms/</a> <br/>
 In the TRAC has a Wiki with important links, the svn timeline and more.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>How do I update the website?</b><br/>
</p>
<p>Login to the wordpress admin area at www.openms.de/wp-admin with your username and password assigned by the current Homepage maintainers.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>Can I use QT designer to create GUI widgets?</b><br/>
 Yes! If you want to create a class called <em>Widget:</em> </p>
<ul>
<li>
<p class="startli">Create .ui-File with QT designer and store it as <code>Widget.ui</code>.</p>
<p class="endli"></p>
</li>
<li>
Add the class to the <code>sources.cmake</code>. </li>
<li>
<p class="startli">From the .ui-File the file <code>include/OpenMS/VISUAL/UIC/ClassTemplate.h</code> is generated by the build system. <br/>
 DO NOT CHECK-IN THIS FILE, AS IT IS GENERATED AUTOMATICALLY, WHEN NEEDED!!!</p>
<p class="endli"></p>
</li>
<li>
Derive the class <code>Widget</code> from <code>WidgetTemplate</code>. You need to check in the <code>Widget.h</code> and <code>Widget.C</code> files. </li>
</ul>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>Can the START_SECTION-macro not handle template methods that have two or more arguments?</b><br/>
 Put round brackets around the method declaration. Then it should work.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>Are there binary installers created from the SVN HEAD?</b><br/>
 Currently binary installers from the HEAD are available only for Windows: <br/>
 <a href="http://ftp.mi.fu-berlin.de/bielow/OpenMS/">http://ftp.mi.fu-berlin.de/bielow/OpenMS/</a></p>
<p class="endli"></p>
</li>
</ul>
<h2 style="border-top:2px solid grey;">Build system</h2>
<ul>
<li>
<p class="startli"><b>What is CMake?!</b><br/>
 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 <a href="http://www.cmake.org">http://www.cmake.org</a> for more information.<br/>
</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>How do I use CMake?!</b><br/>
 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).<br/>
 <b>Note:</b> 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.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>How do I generate a build-system for Eclipse, KDevelop, CodeBlocks etc?!</b><br/>
 Type <code>cmake</code> into a console. This will list the available code generators available on your platform, which you can pass to CMake using the <code>-G</code> option.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>What are user definable CMake Cache Variables?!</b><br/>
 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:</p>
<ul>
<li>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 your have installed all libraries on your system already there is no need to change CMAKE_FIND_ROOT_PATH. If you need the contrib, you will need to set this variable. On Windows, you always need the contrib, as there are no system developer packages. To pass this variable to CMake use the -D switch e.g. <code>cmake -D CMAKE_FIND_ROOT_PATH:PATH="D:\\svn\\contrib"</code> Everything else can be edited using ccmake afterwards. The following options are of interest:<ul>
<li>CMAKE_BUILD_TYPE</li>
<li>CMAKE_FIND_ROOT_PATH</li>
<li>STL_DEBUG</li>
<li>DB_TEST</li>
<li>QT_DB_PLUGIN</li>
<li>MT_CUDA_BUILD_TYPE Their description will be displayed when you call ccmake.</li>
</ul>
</li>
</ul>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>Can I use another solver than GLPK?!</b><br/>
 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 <code>cmake ... -D USE_COINOR=1 ....</code> And look at the documentation of the LPWrapper class.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>How do I switch to Debug/Release configuration?!</b><br/>
 For Makefile generators (typically on Linux) you can set the CMAKE_BUILD_TYPE variable to either Debug or Release by calling ccmake. <br/>
 For Visual Studio, this is not necessary as all configurations are generated and you can choose the one you like within the IDE itself. <br/>
 The 'Debug' configuration enabled debug information. The 'Release' configuration disables debug information and enables optimization.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>I changed the contrib path, but re-running CMake won't change the library paths?!</b><br/>
 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.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>What are the most useful (make) targets?!</b><br/>
 In Visual Studio you can see all targets on the left. For Makefiles type <code>make help</code>.<br/>
 However, this list is quite long. The most useful targets will be shown to you by calling the <code>targets</code> target, i.e. <code>make targets</code>.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>CMake can't seem to find a Qt library (usually QtCore)! What now?</b><br/>
 CMake finds QT by looking for 'qmake' in your PATH or for the Environment Variable QTDIR! Set these accordingly.<br/>
 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.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>(Windows) What version of Visual Studio should I use?</b><br/>
 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).</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>How do I add a new class <code>MyClass</code> to the build system?</b><br/>
 </p>
<ol>
<li>
Create the new class (header in include/ and C file in source/) </li>
<li>
Add both to the respective sources.cmake file in the same directory. </li>
<li>
Add them to svn version control and set the svn:eol-style property to native<br/>
 e.g. <div class="fragment"><div class="line">svn propset svn:eol-style native MyClass.h</div>
<div class="line">svn propset svn:eol-style native MyClass.C</div>
</div><!-- fragment --> </li>
</ol>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>How do I add a new directory <code>MYDIR</code> to the build system?</b><br/>
 </p>
<ol>
<li>
Create two new sources.cmake files (one for OpenMS/source/MYDIR, one for OpenMS/include/MYDIR), using existing sources.cmake files as template </li>
<li>
Add the new sources.cmake file from OpenMS/source/MYDIR and OpenMS/include/MYDIR to OpenMS/cmake/includes.cmake. </li>
<li>
If you created a new directory directly under OpenMS/source, then have a look at OpenMS/source/TEST/executables.cmake (1. add a new section that makes the unit testing system aware of the new (upcoming) tests, 2. look at the very bottom and augment "TEST_executables"). Add a new group target to OpenMS/source/TEST/CMakeLists.txt </li>
</ol>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>How do I add a new test for the class <code>MyClass</code>?</b><br/>
 </p>
<ol>
<li>
Create the <em>MyClass_test.C</em> in <em>source/TEST/</em> </li>
<li>
Add it to <em>OpenMS/source/TEST/executables</em>.cmake in the correct section. For a new section: register it at the bottom of the file and add a target in <em>OpenMS/source/TEST/CMakeLists</em>.txt that builds all targets of the new section. A test template for your specific class can be generated by the create_test.php script found in <em>OpenMS/tools/</em>. </li>
</ol>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>How do I add a new TOPP test?</b><br/>
 Add commands to <em>OpenMS/source/TEST/TOPP/CMakeLists</em>.txt (where it fits alphabetically).</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>How do I add a new GUI test (for QT Gui classes) for the class <code>MyClass</code>?</b><br/>
 </p>
<ol>
<li>
Create the <em>MyClass_test.C</em> in <em>source/TEST/GUI</em> </li>
<li>
Add it to <em>OpenMS/source/TEST/executables</em>.cmake in the GUI section. </li>
<li>
Have a look at existing GUI tests, as they use the QT TestLib framework and not the OpenMS macros. </li>
</ol>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>(Linux) When executing 'make test', all tests fail.</b><br/>
 Please check the LD_LIBRARY_PATH environment variable:</p>
<ul>
<li>You can print the LD_LIBRARY_PATH with '<em>echo $LD_LIBRARY_PATH</em>'.</li>
<li>If your <em>&lt;OpenMS&gt;/lib/</em> folder is included, check that <em>libOpenMS.so</em> is present.</li>
<li>With the ldd command, you can show the libraries used by an exutable, e.g. '<em>ldd &lt;OpenMS&gt;/bin/ClassTest_test</em>'.</li>
</ul>
<p class="endli"></p>
</li>
</ul>
<h2 style="border-top:2px solid grey;">How can I speed up the compile process of OpenMS?</h2>
<ul>
<li>
<p class="startli"><b>Build with several threads.</b><br/>
 If you have several pocessors/cores you can build OpenMS classes/tests and TOPP tools in in several threads. On Linux use the <em>make</em> option <em>-j</em>: <code>make -j8 OpenMS TOPP test_build</code></p>
<p>On Windows, Visual Studio solution files are automatically build with the /MP flag, such that VS uses all available cores of the machine.</p>
<p class="endli"></p>
</li>
</ul>
<h2 style="border-top:2px solid grey;">Working in IDE's</h2>
<ul>
<li>
<b>Why are there no source/TEST and source/APPLICATIONS/TOPP|UTILS folder?</b><br/>
 All source files added to an IDE are associated with their targets. You can find the source files for each test within its own subproject.<br/>
 The same is true for the TOPP and UTILS classes. </li>
<li>
<b>[Visual Studio] I'm getting the error "Error C2471: cannot update program database".</b><br/>
 This is a bug in Visual Studio and there is a bugfix: <a href="http://code.msdn.microsoft.com/KB946040" target="_blank">http://code.msdn.microsoft.com/KB946040</a><br/>
 Only apply it if you encounter the error. The bugfix might have unwanted side effects! </li>
<li>
<b>[Eclipse CDT] The indexer gets stuck at some file which #includes seqan</b><br/>
 It seems that SeqAn code is just too confusing for 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. </li>
<li>
<b>[Eclipse CDT] The parser is confused after OPENMS_DLLAPI and does not recognize standard C++ headers</b><br/>
 Go to Project -&gt; Properties -&gt; C/C++ Include Paths and Preprocessor Symbols -&gt; Add Preprocessor symbol -&gt; "OPENMS_DLLAPI=". This tells eclipse that the macro is defined empty.<br/>
 In the same dialog you can also 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! </li>
</ul>
<h2 style="border-top:2px solid grey;">Debugging</h2>
<ul>
<li>
<p class="startli"><b>How do I run a single test?</b><br/>
</p>
<p>You can can execute an OpenMS class test using the CTest regular expressions: <br/>
 <code>&gt; ctest -V -R "^&lt;class&gt;_test"</code> <br/>
 To build a class test, you simply call the respective make target in ./source/TEST: <br/>
 <code>&gt; make &lt;class&gt;_test</code></p>
<p>To run a TOPP test, you can use: <br/>
 <code>&gt; ctest -V -R "TOPP_&lt;tool&gt;"</code> <br/>
 To build the tool, use: <br/>
 <code>&gt; make &lt;tool&gt;</code></p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>How do I debug uncaught exceptions?</b><br/>
 There is a mechanism to have a core dumped if an uncaught exception occurs.</p>
<p>To enable it, the environment variable OPENMS_DUMP_CORE has to be set.</p>
<p>Each time an uncaught exception occures, the OPENMS_DUMP_CORE variable is checked and a segmentation fault is caused, if it is set.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>(Linux) Why is no core dumped, although a fatal error occured?</b><br/>
 Try the <em>ulimit</em> <em>-c</em> <em>unlimited</em> command. It sets the maximum size of a core to unlimited.</p>
<p><em>Note:</em> 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.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>(Linux) How can I set breakpoints in <em>gdb</em> to debug OpenMS?</b><br/>
 Imagine you want to debug the <em>TOPPView</em> application and you want it to stop at line 341 of <em>SpectrumMDIWindow.C</em>. <br/>
 </p>
<ol>
<li>
<p class="startli">Run gdb: <br/>
 <code>shell&gt; gdb TOPPView</code></p>
<p class="endli"></p>
</li>
<li>
<p class="startli">Start the application (and close it): <br/>
 <code>gdb&gt; run [arguments]</code></p>
<p class="endli"></p>
</li>
<li>
<p class="startli">Set the breakpoint: <br/>
 <code>gdb&gt; break SpectrumMDIWindow.C:341</code></p>
<p class="endli"></p>
</li>
<li>
Start the application again (with the same arguments): <br/>
 <code>gdb&gt; run</code> </li>
</ol>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>How can I find out which shared libraries are used by an application?</b> <br/>
 Linux: <code>ldd &lt;application&gt;</code> <br/>
 Windows (Visual studio console): Try "Dependency Walker"(<a href="http://www.dependencywalker.com/">http://www.dependencywalker.com/</a>) (use x86 for 32bit builds and the x64 version for 64bit builds. Using the wrong version of depends.exe will give wrong results!) or <code>dumpbin /DEPENDENTS OpenMS.dll</code></p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>How can I get a list of the symbols defined in a (shared) library or object file?</b> <br/>
 Linux: <code>nm &lt;library&gt;</code> Use <code>nm -C</code> to switch on demangling of low-level symbols into their C++-equivalent names. <code>nm</code> also accepts <code>.a</code> and <code>.o</code> files. <br/>
 Windows (Visual studio console): <code>dumpbin /ALL &lt;library&gt;</code> <br/>
 You can use dumpbin on object files (.o) or (shared) library files (.lib) or the DLL itself e.g. <code>dumpbin /EXPORTS OpenMS.dll</code></p>
<p class="endli"></p>
</li>
</ul>
<h2 style="border-top:2px solid grey;">Cross-platform thoughts</h2>
<p>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?"</p>
<ul>
<li>
<p class="startli"><b>Reading/Writing binary files causes different behaviour ...</b><br/>
 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!</p>
<p>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.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>unsigned int vs size_t (UInt and Size)</b><br/>
 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.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>Paths and system functions...</b><br/>
 This is trivial but hardcoding something like </p>
<div class="fragment"><div class="line">String tmp_dir = <span class="stringliteral">&quot;/tmp&quot;</span>;</div>
</div><!-- fragment --><p> 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.<br/>
 Also calling things like <code>uname</code> which are only available on Linux: don't!<br/>
 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.</p>
<p class="endli"></p>
</li>
</ul>
<h2 style="border-top:2px solid grey;">SVN</h2>
<ul>
<li>
<p class="startli"><b>The $id$ string in my test is not expanded to the SVN id. Why?</b><br/>
 In Subversion you have to set the keyword expansion explicitly: <br/>
<code>svn propset svn:keywords Id &lt;file&gt;</code></p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>How do I undo a commit?</b><br/>
 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: <br/>
<code>svn merge -r 25:24 <a href="https://open-ms.svn.sourceforge.net/svnroot/open-ms/OpenMS/">https://open-ms.svn.sourceforge.net/svnroot/open-ms/OpenMS/</a> .</code> <br/>
<code>svn commit -m "Removed revision 25"</code></p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>How do I create a branch?</b><br/>
 <code>svn copy <a href="https://open-ms.svn.sourceforge.net/svnroot/open-ms/OpenMS">https://open-ms.svn.sourceforge.net/svnroot/open-ms/OpenMS</a> <a href="https://open-ms.svn.sourceforge.net/svnroot/open-ms/branches/">https://open-ms.svn.sourceforge.net/svnroot/open-ms/branches/</a>[name]/</code></p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>How does merging branches work?</b><br/>
 To merge changes from the <code>source</code> branch into the <code>target</code> branch, do the following:<br/>
 </p>
<ol>
<li>
Check out the <code>target</code> branch. </li>
<li>
Merge the desired revisions into the branch:<br/>
 <code>svn merge -r [from]:[to] <a href="https://open-ms.svn.sourceforge.net/svnroot/open-ms/">https://open-ms.svn.sourceforge.net/svnroot/open-ms/</a>[source]</code> </li>
<li>
Resolve conflicts and make sure all tests run </li>
<li>
Commit the changes </li>
</ol>
<p><b>Example 1: From HEAD to release branch</b><br/>
 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 <a href="http://open-ms.svn.sourceforge.net/viewvc/open-ms">http://open-ms.svn.sourceforge.net/viewvc/open-ms</a> for the actual names of branches). </p>
<ol>
<li>
Check out the release branch:<br/>
 <code>svn co <a href="https://open-ms.svn.sourceforge.net/svnroot/open-ms/branches/">https://open-ms.svn.sourceforge.net/svnroot/open-ms/branches/</a>[target]/</code> </li>
<li>
Merge the changes into the the branch (where the <code>rv</code> in <code>(rv-1):rv</code> corresponds to your svn-revision number you just committed)<br/>
 <code>svn merge -r 2324:2325 <a href="https://open-ms.svn.sourceforge.net/svnroot/open-ms/OpenMS/">https://open-ms.svn.sourceforge.net/svnroot/open-ms/OpenMS/</a></code> </li>
<li>
Resolve conflicts and run tests </li>
<li>
Commit </li>
</ol>
<p><b>Example 2: Merge branch into HEAD</b><br/>
 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. </p>
<ol>
<li>
Go to the HEAD and update it:<br/>
 <code>cd OpenMS/</code> (HEAD)<br/>
 <code>svn update</code><br/>
 </li>
<li>
Merge the changes in the branch into the HEAD: <code>svn merge -r 10:25 <a href="https://open-ms.svn.sourceforge.net/svnroot/open-ms/branches/">https://open-ms.svn.sourceforge.net/svnroot/open-ms/branches/</a>[source]/</code> </li>
<li>
Resolve conflicts and run tests </li>
<li>
Commit </li>
</ol>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>How do I speed up the SVN Repo and/or upgrade to a new SVN version on the server?</b><br/>
</p>
<p>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</p>
<p>$ rsync -av open-ms.svn.sourceforge.net::svn/open-ms/* .</p>
<p>Now here's how you do the upgrade</p>
<div class="fragment"><div class="line"><span class="preprocessor">## login to SF</span></div>
<div class="line"><span class="preprocessor"></span>ssh -t &lt;yourusername&gt;,open-ms@shell.sf.net create</div>
<div class="line"></div>
<div class="line">adminrepo --checkout svn</div>
<div class="line"></div>
<div class="line">svnadmin dump /svnroot/open-ms &gt; oms_dump.txt</div>
<div class="line"><span class="preprocessor">## make a backup</span></div>
<div class="line"><span class="preprocessor"></span>cp /svnroot/open-ms oms_backup</div>
<div class="line"><span class="preprocessor">## reload repo (instead of using svnadmin upgrade, which might not be optimal for performance)</span></div>
<div class="line"><span class="preprocessor"></span>rm -rf /svnroot/open-ms<span class="comment">/*</span></div>
<div class="line"><span class="comment">svnadmin create /svnroot/open-ms</span></div>
<div class="line"><span class="comment">svnadmin load /svnroot/open-ms &lt; oms_dump.txt</span></div>
<div class="line"><span class="comment"></span></div>
<div class="line"><span class="comment">## increase speed (can be done regularly, without dump/load block above)</span></div>
<div class="line"><span class="comment">svnadmin pack /svnroot/open-ms</span></div>
<div class="line"><span class="comment"></span></div>
<div class="line"><span class="comment">## check integrity</span></div>
<div class="line"><span class="comment">svnadmin verify /svnroot/open-ms</span></div>
<div class="line"><span class="comment">## get latest revision number</span></div>
<div class="line"><span class="comment">svnlook youngest /svnroot/open-ms</span></div>
<div class="line"><span class="comment">## check some revisions</span></div>
<div class="line"><span class="comment">svnlook info -r &lt;XXX&gt; /svnroot/open-ms</span></div>
<div class="line"><span class="comment"># e.g. </span></div>
<div class="line"><span class="comment"># svnlook info -r 100 /svnroot/open-ms</span></div>
<div class="line"><span class="comment"># svnlook info -r 8635 /svnroot/open-ms</span></div>
<div class="line"><span class="comment"></span></div>
<div class="line"><span class="comment">adminrepo --save svn</span></div>
</div><!-- fragment --><p class="endli"></p>
</li>
</ul>
<h2 style="border-top:2px solid grey;">Doxygen documentation</h2>
<ul>
<li>
<p class="startli"><b>Where can I find the definition of the main page?</b><br/>
 <em>OpenMS/doc/doxygen/public/Main</em>.doxygen</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>Where can I add a new module?</b><br/>
 <em>OpenMS/doc/doxygen/public/Modules</em>.doxygen</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>How is the parameter documentation for classes derived from DefaultParamHandler created?</b><br/>
 You have to add your class to the program <em>OpenMS/doc/doxygen/parameters/DefaultParamHandlerDocumenter.C</em>. This program generates a html table with the parameters. This table can then be included into the class documentation using the following doxygen command: </p>
<div class="fragment"><div class="line">@htmlinclude OpenMS_&lt;class name&gt;.parameters</div>
</div><!-- fragment --><p> 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: </p>
<div class="fragment"><div class="line">@htmlinclude TOPP_&lt;tool name&gt;.parameters</div>
</div><!-- fragment --><p> or </p>
<div class="fragment"><div class="line">@htmlinclude UTILS_&lt;tool name&gt;.parameters</div>
</div><!-- fragment --><p>You can test if everything worked by calling <em>make</em> <em>doc_param_internal</em> . The parameters documentation is written to <em>OpenMS/doc/doxygen/parameters/output/</em>.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>How is the command line documentation for TOPP/UTILS tools created?</b><br/>
 The program <em>OpenMS/doc/doxygen/parameters/TOPPDocumenter.C</em> 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: </p>
<div class="fragment"><div class="line">@verbinclude TOPP_&lt;tool name&gt;.cli</div>
</div><!-- fragment --><p> You can test if everything worked by calling <em>make</em> <em>doc_param_internal</em> . The command line documentation is written to <em>OpenMS/doc/doxygen/parameters/output/</em>.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>What are the important files for adding a new tutorial section?</b><br/>
 OpenMS tutorial: <br/>
OpenMS/doc/OpenMS_tutorial/refman_overwrite.tex.in (for PDF tutorials) <br/>
OpenMS/doc/doxygen/public/OpenMS_Tutorial_html.doxygen (for html tutorials)</p>
<p>TOPP and TOPPView tutorial: <br/>
OpenMS/doc/TOPP_tutorial/refman_overwrite.tex.in (for PDF tutorials) <br/>
OpenMS/doc/doxygen/public/TOPP_Tutorial_html.doxygen (for html tutorials)</p>
<p class="endli"></p>
</li>
</ul>
<h2 style="border-top:2px solid grey;">Bug fixes</h2>
<ul>
<li>
<p class="startli"><b>What is to do for a bugfix?</b> </p>
<ul>
<li>
Submit the bug to the tracker (TRAC) </li>
<li>
Fix the bug and add a test for it in the HEAD </li>
<li>
Commit bugfix and test as a single commit and add the bug number to the comment.<br/>
E.g.: "[FIX] Fixed bug #123" </li>
<li>
Close the bug in the tracker and add the the revision of the fix to the comment.<br/>
E.g.: "Fixed in revision [3005]" </li>
<li>
Merge the revision into the current release branch (see SVN section above) </li>
</ul>
<p class="endli"></p>
</li>
</ul>
<h2 style="border-top:2px solid grey;">Releases</h2>
<ul>
<li>
<b>What has the release manager to do for a release?</b> <ol>
<li>
Create release branch </li>
<li>
Add release branch to CDASH </li>
<li>
Distribute tasks among developers: <ul>
<li>
Fix automatic tests </li>
<li>
Fix release critical bugs </li>
<li>
Fix compile warnings </li>
<li>
Fix checker violations </li>
<li>
Fix code analysis (e.g. cpplint, cppcheck) violations </li>
</ul>
</li>
<li>
Update the list of active maintainers in tools/ACTIVE_MAINTAINERS </li>
<li>
Declare release candidate and distribute tasks: <ul>
<li>
</li>
</ul>
installation on target platforms <ul>
<li>
</li>
</ul>
if all installed tools can be executed <ul>
<li>
</li>
</ul>
if documentation is available and correct (e.g. version numbers) <ul>
<li>
</li>
</ul>
if pipelines run <ul>
<li>
</li>
</ul>
if interactive applications work correctly (e.g. TOPPView, TOPPAS, INIFileEditor, IDEvalutator ...) <ul>
<li>
</li>
</ul>
KNIME installation on target platforms <ul>
<li>
</li>
</ul>
if automatic update in KNIME works </li>
<li>
Organise packaging </li>
</ol>
</li>
<li>
<p class="startli"><b>What has each developer to do for a release?</b> </p>
<p>Each maintainer must check his/her classes and TOPP tools. Keep in mind that missing documention scares off potential users! </p>
<p>Here is a list of what is to do: </p>
<ol>
<li>
Remove classes not ready for release from the release branch. </li>
<li>
Update the CHANGELOG file (also document all parameter names of TOPP tools which have changed!<ul>
<li>the easiest way to do this: take all INI files from previous release and call: "&lt;tool&gt; -write_ini bla.ini -ini &lt;previous.ini&gt;" and look at output) </li>
</ul>
</li>
<li>
Check the test builds of the latest gcc/cl version for compiler warnings (32 and 64 bit) </li>
<li>
Check if all examples in <em>OpenMS/doc/code_examples/</em> compile. </li>
<li>
Make sure the binary packages can be compiled for all platforms (see below). Between releases, the build system usually catches a bug, and you need to fix this! </li>
<li>
Correct errors found by <em>tools/checker.php</em>. <ul>
<li>
The option <em>-u</em> <em>&lt;maintainer&gt;</em> restricts the output to one maintainer </li>
<li>
More options are given with <em>&ndash;help</em> </li>
</ul>
</li>
<li>
Documentation: <ul>
<li>
OpenMS <ul>
<li>
Write / correct tutorial </li>
<li>
Write / correct class documentation </li>
<li>
Complete method documentation </li>
</ul>
</li>
<li>
TOPP <ul>
<li>
Write / correct tutorial </li>
<li>
Check if each TOPP/UTIL is listed on the TOPP/UTIL documentation page </li>
<li>
Write / correct doxygen documentation of each tool </li>
<li>
Proof-read the output of <em>&lt;TOPP-tool&gt;</em> <em>&ndash;help</em> </li>
<li>
Check if all parameters and sections are documented in INI files (<em>-write_ini</em> and <em>INIFileEditor</em>). </li>
</ul>
</li>
</ul>
</li>
</ol>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>How is a major release done?</b> </p>
<ul>
<li>
Create the binary/source release packages (see below) </li>
<li>
Upload the Source and Binary packages to SourceForge: <ol>
<li>
Go to the <a class="el" href="namespaceOpenMS.html" title="Main OpenMS namespace. ">OpenMS</a>' sourceforge site &amp; log in </li>
<li>
Create a new folder for the release, e.g., OpenMS-1.9 and upload files to this folder </li>
</ol>
</li>
<li>
Copy the HTML documentation and PDF tutorials of the release to your own FTP server (e.g., <br/>
 <a href="http://ftp.mi.fu-berlin.de/OpenMS/doc-1.9-official">http://ftp.mi.fu-berlin.de/OpenMS/doc-1.9-official</a>). </li>
<li>
Update the redirection rule on the website for <em><a href="http://www.openms.de/current_doxygen">http://www.openms.de/current_doxygen</a></em> to point to the current documentation </li>
<li>
Check the function of the public search engine at <em><a href="http://www-bs2.informatik.uni-tuebingen.de/services/OpenMS-release/search.php">http://www-bs2.informatik.uni-tuebingen.de/services/OpenMS-release/search.php</a></em> </li>
<li>
Update the website (news, changelog, XML schema files, links for docu and download) </li>
<li>
Send a mail notification to the announcements mailing list and the general mailing list </li>
</ul>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>How is the platform-independent source release package created?</b> </p>
<ol>
<li>
Year numbers update in: <ol>
<li>
&lt;OpenMS&gt;/source/COPYRIGHT </li>
<li>
All headers and C files and License.txt (adapt years accordingly) <code> cd &lt;OpenMS&gt; find . -name "*.h" -o -name "*.C" -o -name "*.txt" | xargs sed -i 's/(C) 2003-2011/(C) 2003-2012/g' </code> </li>
</ol>
</li>
<li>
Version Number update in: <ol>
<li>
<code>CMakeLists.txt</code> of contrib. </li>
<li>
<code>CMakeLists.txt</code> of OpenMS (three OPENMS_PACKAGE_VERSION_* variables, and the contrib version check) </li>
<li>
<code>source/TEST/VersionInfo_test.C</code> </li>
<li>
TOPPView and TOPPAS splash screen <code>source/VISUAL/ICONS/</code>.<br/>
 The GIMP/PhotoShop files can be found in the <em>images</em> SVN module. </li>
</ol>
</li>
<li>
Run cmake </li>
<li>
Make sure that the tutorial examples in <code>doc/code_examples/</code> can be compiled and executed (target 'Tutorials_build' and 'Tutorials_exec') </li>
<li>
Commit the changes to the SVN repository </li>
<li>
Build the documentation that is needed for the release <ol>
<li>
Check out a fresh working copy of OpenMS </li>
<li>
Build the library, and build the documentation using <code>make doc</code> (not <code>doc_internal</code>!). </li>
<li>
Build the PDF tutorials using <code>make doc_tutorials</code>. </li>
<li>
Make sure that the Parameter documentation was created (see TOPP documentation of a arbitrary TOPP tool). </li>
<li>
Make sure the include paths in the documentation are correct. </li>
</ol>
</li>
<li>
Run the script <code>tools/make_source_package.sh</code> according to the help shown when executed. </li>
<li>
Test installation of contrib and OpenMS from release package </li>
</ol>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>How is the Windows binary release package created?</b> </p>
<ol>
<li>
Check out the Windows installer scripts from <code><a href="https://open-ms.svn.sourceforge.net/svnroot/open-ms/win_installer">https://open-ms.svn.sourceforge.net/svnroot/open-ms/win_installer</a></code> </li>
<li>
see <code>win_installer/README</code> for further instructions </li>
</ol>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>How are the binary release packages for different Linux distributions created?</b> </p>
<ol>
<li>
Prerequisites: make sure the 'rpm' or respective package creation utilities are installed. </li>
<li>
Check out the release branch and contrib </li>
<li>
Build the contrib libraries </li>
<li>
Configure OpenMS using <br/>
 <code>&gt; cmake -D INSTALL_PREFIX=/usr -D PACKAGE_TYPE=rpm/deb ...</code> </li>
<li>
Set the environment variable 'OPENMS_DATA_PATH' to your OpenMS share directory, e.g. <code>/home/myusername/binary_release/OpenMS/share/OpenMS</code>.<br/>
 Explanation follows (just read if interested): When using INSTALL_PREFIX, running any OpenMS executable before installation will result in an error because the SHARE/OpenMS directory will not be found (it is already hardcoded to the future install directory). As 'make doc' etc require OpenMS executables (TOPPDocumenter,...) this step is required. </li>
<li>
Build OpenMS: <code>make TOPP UTILS doc doc_tutorials</code> </li>
<li>
Build the package using <code>make package</code> </li>
<li>
Rename the package to this naming schema: <br/>
 OpenMS-&lt;version&gt;-&lt;package-nr&gt;_&lt;dist&gt;-&lt;dist-version&gt;_&lt;dist-arch&gt;.&lt;rpm/deb&gt; </li>
</ol>
<p class="endli"></p>
</li>
</ul>
<h2 style="border-top:2px solid grey;">Profiling and memory leaks and strange behaviour</h2>
<p><b> 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)).</b> Otherwise you might get the strangest access violations, pointing to arbitrary code.</p>
<ul>
<li>
<p class="startli"><b>How can I profile my code?</b> </p>
<ul>
<li>
Try IBM's profiler, available for all platforms (and free for academic use): Purify(Plus) and/or Quantify. </li>
<li>
Windows: this is directly supported by Visual Studio (Depending on the edition: Team and above). Follow their documentation. </li>
<li>
Linux: <ol>
<li>
build OpenMS in debug mode (set CMAKE_BUILD_TYPE to 'Debug') </li>
<li>
call the executable with valgrind: <code>'valgrind &ndash;tool=callgrind &lt;executable&gt; &lt;parameters&gt;'</code> <ul>
<li>
Note: other processes running on the same machine can influence the profiling. Make sure your application gets enough resources (memory, CPU time). </li>
<li>
You can start and stop the profiling while the executable is running e.g. to skip initialization steps: <ul>
<li>
start valgrind with the option <em>&ndash;instr-atstart=no</em> </li>
<li>
call <code>'callgrind -i [on|off]'</code> to start/stop the profiling </li>
</ul>
</li>
</ul>
</li>
<li>
The output can be viewed with <code>'kcachegrind callgrind.out.&lt;process id&gt;'</code> </li>
</ol>
</li>
</ul>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>(Linux) How do I check my code for memory leaks?</b> </p>
<ol>
<li>
build OpenMS in debug mode (set CMAKE_BUILD_TYPE to 'Debug') </li>
<li>
call the executable with valgrind: <code>'valgrind &ndash;leak-check=full &lt;executable&gt; &lt;parameters&gt;'</code> </li>
<li>
Common errors are: <ul>
<li>
<code>'Invalid write/read ...'</code> - Violation of container boundaries </li>
<li>
<code>'... depends on uninitialized variable'</code> - Uninitialized variables: </li>
<li>
<code>'... definitely lost'</code> - Memory leak that has to be fixed </li>
<li>
<code>'... possibly lost'</code> - Possible wemory leak, so have a look at the code </li>
</ul>
</li>
<li>
For more information see the valgrind documentation at <a href="http://valgrind.org/docs/manual/">http://valgrind.org/docs/manual/</a> </li>
</ol>
<p class="endli"></p>
</li>
</ul>
<h2 style="border-top:2px solid grey;">TOPP/UTILS</h2>
<ul>
<li>
<p class="startli"><b>How to create an icon file for a TOPP tool under Windows?</b> </p>
<ol>
<li>
Create an <em>.ico</em> file: <ol>
<li>
first, you need some graphics program (The GIMP is recommended) </li>
<li>
think of a motive and remind yourself that you have limited space. <a href="http://msdn2.microsoft.com/en-us/library/ms997636.aspx" target="_blank">http://msdn2.microsoft.com/en-us/library/ms997636.aspx</a> gives some useful hints. </li>
<li>
create at least a 16x16, 32x32, 48x48 and 64x64 pixel version and save each of them in a separate layer of the respective size. Do not add any larger sized layers, since Win XP will not display any icon then. </li>
<li>
when saving your image as type <em>.ico</em> the GIMP will ask you for the color depth of each layer. As it is recommended to have multiple color depths of each icon-size, go back to the layers and duplicate each layer twice. That should give you 12 layers. </li>
<li>
now save the image as <em>&lt;binaryname&gt;.ico</em> (e.g. TOPPView.ico) file, giving each group of equal sized layers a 32bit (8bit transparency), 8bit (1bit transparency), 4bit (1bit transparency) color depth. <br/>
Attention: make sure to assign the higher color depth to the upper layers as Windows will not pick the highest possible color otherwise. </li>
</ol>
</li>
<li>
Create a resource file: <ol>
<li>
Create a text file named <em>&lt;binaryname&gt;.rc</em> (e.g. TOPPView.rc) </li>
<li>
Insert the following line:<br/>
 <em>101 ICON "TOPPView.ico"</em><br/>
 , replacing TOPPView with your binary name. </li>
</ol>
</li>
<li>
Put both files in <em>OpenMS/source/APPLICATIONS/TOPP/</em> (you should find some similar files for other TOPP tools already present). </li>
<li>
Re-run cmake and re-link your TOPP tool. </li>
<li>
Voila. You should have an iconized TOPP tool. </li>
</ol>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>What do I have to do to add a new TOPP tool?</b> </p>
<ol>
<li>
Add your tool (with the correct category) to getTOPPToolList() in <code>source/APPLICATIONS/ToolHandler.C</code> <br/>
 This creates a doxygen page with the <em>&ndash;help</em> output of the tool (using TOPPDocumenter). <br/>
 This page must be included at the end of the doxygen documentation of your tool (see other tools for an example). </li>
<li>
Add it to the TOPP docu page (in <em>doc/doxygen/public/TOPP</em>.doxygen) </li>
<li>
Add the executable to the ignore list of the directory (<em>svn</em> <em>propedit</em> <em>svn:ignore</em> <em>source/APPLICATION/TOPP/</em>) </li>
<li>
Add the name to <code>source/APPLICATIONS/TOPP/executables.cmake</code> </li>
<li>
Write a TOPP test (add it to /source/TEST/TOPP/CMakeLists.txt)<br/>
 Warning: handle any kind of input files to your TOPP tool via command line flags and use the ${DATA_DIR_TOPP} prefix. You can use ini-files to specify output-files, but not input-files. Doing otherwise will break out-of-source builds.<br/>
 Hint: add "-test" to the call of your TOPP tool and also create the expected output that you put in source/TEST/TOPP with that flag active. The flag ensures that UniqueId's, dates etc are equal no matter where and when the tool is run. </li>
</ol>
<p class="endli"></p>
</li>
<li>
<p class="startli"><b>What do I have to do to add a new UTILS tool?</b> </p>
<ol>
<li>
Add your tool to getUtilList() in <code>source/APPLICATIONS/ToolHandler.C</code> <br/>
 This creates a doxygen page with the <em>&ndash;help</em> output of the tool (using TOPPDocumenter). <br/>
 This page must be included at the end of the doxygen documentation of your tool (see other tools for an example). </li>
<li>
Add it to the UTILS docu page (in <em>doc/doxygen/public/UTILS</em>.doxygen) </li>
<li>
Add the executable to the ignore list of the directory (<em>svn</em> <em>propedit</em> <em>svn:ignore</em> <em>source/APPLICATION/UTILS/</em>) </li>
<li>
Add the name to <code>source/APPLICATIONS/UTILS/executables.cmake</code> </li>
<li>
Write a test (this is optional for UTILS). See TOPP tools above and add the test to the bottom of /source/TEST/TOPP/CMakeLists.txt. </li>
</ol>
<p class="endli"></p>
</li>
</ul>
</div></div><!-- contents -->
<HR style="height:1px; border:none; border-top:1px solid #c0c0c0;">
<TABLE width="100%" border="0">
<TR>
<TD><font color="#c0c0c0">OpenMS / TOPP release 1.11.1</font></TD>
<TD align="right"><font color="#c0c0c0">Documentation generated on Thu Nov 14 2013 11:19:25 using doxygen 1.8.5</font></TD>
</TR>
</TABLE>
</BODY>
</HTML>