diff --git a/docs/additional-resources/openms-git-workflow.md b/docs/additional-resources/openms-git-workflow.md new file mode 100644 index 00000000..dfa2ee22 --- /dev/null +++ b/docs/additional-resources/openms-git-workflow.md @@ -0,0 +1,197 @@ +OpenMS Git Workflow +=================== + +Before getting started, install latest version of git to avoid problems like GitHub https authentication errors +(see [Troubleshooting cloning errors](https://docs.github.com/en/repositories/creating-and-managing-repositories/troubleshooting-cloning-errors) and a solution using [ssh](https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories)). + +OpenMS follows the [git flow workflow](https://nvie.com/posts/a-successful-git-branching-model/). The difference is that +merge commits are managed via pull requests instead of creating merge commits locally. + +## Naming conventions + +Naming conventions for the following apply: + +* A **local repository** is the repository that lies on your hard drive after cloning. +* A **remote repository** is a repository on a git server such as GitHub. +* A **fork** is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project. +* **Origin** refers to a remote repository that you have forked. Call this repository https://github.com/_YOURUSERNAME_/OpenMS. +* **Upstream** refers to the original remote OpenMS repository. Call this repository https://github.com/OpenMS/OpenMS. + +## Create fork + +Start by [forking](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the OpenMS repository. + +To create a fork, click **Fork** under the main menu as shown below. + +![image info](../images/additional-resources/click-fork.png) + +## Clone your fork + +To obtain a local repository copy, clone your fork using: + +```bash +$ git clone https://github.com/_YOURUSERNAME_/OpenMS.git +``` + +This will clone your fork (correctly labelled `origin` by default) into a local copy on your computer. + +## Link remote branches to your local working repository + +After cloning your fork, your local repository should be named origin. Validate this by executing: + +```bash +$ git remote -v + origin https://github.com/_YOURUSERNAME_/OpenMS.git (fetch) + origin https://github.com/_YOURUSERNAME_/OpenMS.git (push) +``` + +Sync data between your local copy, your fork (`origin`) and the remote original OpenMS/OpenMS repository (`upstream`) +by using the following command: + +```bash +$ git remote add upstream https://github.com/OpenMS/OpenMS.git +``` +Verify that upstream was added correctly by calling: + +```bash +$ git remote -v + origin https://github.com/_YOURUSERNAME_/OpenMS.git (fetch) + origin https://github.com/_YOURUSERNAME_/OpenMS.git (push) + upstream https://github.com/OpenMS/OpenMS.git (fetch) + upstream https://github.com/OpenMS/OpenMS.git (push) + +``` + +Fetch changes and new branches from your fork (`origin`) as well as from the central, upstream OpenMS repository by executing: + +```bash +$ git fetch upstream +$ git fetch origin +``` +or + +```bash +$ git fetch --all +``` + +Create a local branch using the following: + +```bash +$ git checkout -b +``` + +Call `git branch -va` to display the status of local and remote branches. You should see an output that looks like this: + +```bash +$ git branch -va +* develop 349ec48 Merge pull request #691 from cbielow/MGF_fix + feature/my_shiny_new_feature 3c05538 [FEATURE] added option to keep, ensure or reassign UIDs during conversion + remotes/origin/SILACAnalyzer 3ceae38 Fixed test. + remotes/origin/antilope 3fe5aa3 git-svn-id: https://open-ms.svn.sourceforge.net/svnroot/open-ms/branches/antilope@12117 6adb6e08-d915-0410-941f-83917bcadc18 + remotes/origin/develop 349ec48 Merge pull request #691 from cbielow/MGF_fix + remotes/origin/master b182ba5 [NOP] first commit after SVN import to git + remotes/origin/msnovogen 93a5e4c [OPT] For faster access to specific amino acids a ResidueServer was added. + remotes/upstream/HEAD -> upstream/develop + remotes/upstream/SILACAnalyzer 3ceae38 Fixed test. + remotes/upstream/antilope 3fe5aa3 git-svn-id: https://open-ms.svn.sourceforge.net/svnroot/open-ms/branches/antilope@12117 6adb6e08-d915-0410-941f-83917bcadc18 + remotes/upstream/develop 349ec48 Merge pull request #691 from cbielow/MGF_fix + remotes/upstream/master b182ba5 [NOP] first commit after SVN import to git + remotes/upstream/msnovogen 93a5e4c [OPT] For faster access to specific amino acids a ResidueServer was added. +``` + +## Keep your fork in sync + +Keep your fork (`origin`) in sync with the OpenMS repository (`upstream`) by following the [GitHub instructions](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork). +In summary, to keep your fork in sync: +1. Fetch changes from upstream and update your local branch. +2. Push your updated local branch to your fork (`origin`). + +```{tip} +To keep track of others repositories, use `git fetch --all --prune` to update them as well. The option `--prune` tells +git to automatically remove tracked branches if they got removed in the remote repository. +``` + +```bash +$ git fetch --all --prune +$ git checkout develop +$ git merge --ff-only upstream/develop +$ git push origin develop +``` +Feel free to experiment within your fork. However, for your code needs to meet OpenMS quality standards to be merged +into the OpenMS repository, + +Follow these rules: +* Never commit directly to the `develop` or `master` branches as it will complicate the merge. +* Try to start every feature from develop and not base features on other features. +* Name the OpenMS remote `upstream` and always push directly to `origin` (`git push origin `). +* When updating your fork, consider using `git fetch upstream` followed by `git merge --ff-only upstream/develop` to + avoid creating merge commits in `develop`. +* If you never commit to `develop` this should always succeed and (if a commit accidentally went to develop) warn you + instead of creating a merge commit. + +## Create new feature + +All features start from `develop`. + +```bash +$ git checkout develop +$ git checkout -b feature/your-cool-new-feature +``` +All commits related to this feature will then go into the branch `feature/your-cool-new-feature`. + +## Keeping your feature branch in sync with develop branch + +While working on your feature branch, it is usual that development continues and new features get integrated into the +main development branch. This means your feature branch lags behind `develop`. To get your feature branch up-to-date, +rebase your feature branch on `develop` using: + +```bash +$ git checkout feature/myfeaturebranch +$ git rebase develop +``` + +The above commands: + +1. Performs a rewind of your commits until the branching point. +2. Applies all commits that have been integrated into `develop`. +3. Reapplies your commits on top of the commits integrated into `develop`. + +For more information, refer to a [visual explanation of rebasing](http://git-scm.com/book/en/v2/Git-Branching-Rebasing). + +```{tip} +Do not rebase published branches (e.g. branches that are part of a pull request). If you created a pull request, you +should only add commits in your feature branch to fix things that have been discussed. After your pull request contains +all fixes, you are ready to merge the pull request into develop without rebasing (see e.g. rebase-vs-merge). +``` + +## Adding a feature to OpenMS + +Features that should go into the main development line of OpenMS should be integrated via a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). This allows +the development community of OpenMS to discuss the changes and suggest possible improvements. + +After opening the pull request via the GitHub web site, GitHub will try to create the pull request against the branch +that you branched off from. Please check the branch that you are opening the pull request against before submitting the +pull request. If any changes are made, a new pull request is required. Select +**Allow others to make changes to this pull request** so that maintainers can directly help to solve problems. + +Open pull requests only after checking code-style, documentation and passing tests. Pull requests that do not pass CI +or code review will not be merged until the problems are solved. It is recommended that you read the +[pull request guidelines](pull-request-checklist.md) before you submit a pull request. + +## Update git submodules + +Start in your local `OpenMS/OpenMS` repository (on your feature/pull request branch). + +The following example uses a submodule called `THIRDPARTY`. + +```bash +$ git submodule update --init THIRDPARTY +$ cd THIRDPARTY +# yes, in the submodules the default remote is origin +# usually you want to pull the changes from master (e.g. after your pull request to OpenMS/THIRDPARTY has been merged) +$ git pull origin master +$ cd .. +$ git status +# Make sure that you see "modified: THIRDPARTY (new commits)" +$ git commit -am "updated submodule" +``` diff --git a/docs/additional-resources/pull-request-checklist.md b/docs/additional-resources/pull-request-checklist.md new file mode 100644 index 00000000..ccb6487c --- /dev/null +++ b/docs/additional-resources/pull-request-checklist.md @@ -0,0 +1,44 @@ +Pull Request Checklist +====================== + +Before opening a pull request, check the following: + +1. **Does the code build?** + Execute `make` (or your build system's equivalent, e.g., `cmake --build . --target ALL_BUILD --config Release` on Windows). +2. **Do all tests pass?** + To check if all tests have passed, execute `ctest`. + If a test that is unrelated to your changes fails, check the [nightly builds](http://cdash.openms.de/index.php?project=OpenMS) + to see if the error is also in `develop`. If the error is in develop, [create a github issue](write-and-label-github-issues.md). +3. **Is the code documented?** + Document all new classes, including their methods and parameters. + It is also recommended to document non-public members and methods. +4. **Does the code introduce changes to the API?** + If the code introduces changes to the API, make sure that the documentation is up-to-date and that the Python bindings + (pyOpenMS) still work. For each change in the C++ API, make a change in the Python API wrapper via the `pyOpenMS/pxds/` files. +5. **Have you completed regression testing?** + Make sure that you include a test in the test suite for: + - Public methods of a class + - TOPP tools + - Bug fixes + +Make sure to: + +- **Rebase before you open a pull request.** + To include all recent changes, rebase your branch on `develop` before opening a pull request. + If you pushed your branch to `origin` before rebasing, git will most likely tell you after the rebase that your + local branch and the remote branch have diverged. If you are sure that the remote branch does not contain any local + commits in the rebased version, you can safely push using `git push -f origin ` to enforce overwrite. If + not, contact your local git expert on how to get the changes into your local branch. + +- **Capture similar changes in a single commit** + Each commit should represent one logical unit. Consolidate multiple commits if they belong together or split single + commits if they are unrelated. For example, committing code formatting together with a one-line fix makes it very hard + to figure out what the fix was and which changes were inconsequential. + +* **Create a pull request for a single feature or bug** + If you have multiple features or fixes in a pull request, you might get asked to split your request and open multiple + pull requests instead. + +* **Describe what you have changed in your pull request.** + When opening the pull request, give a detailed overview of what has changed and why. Include a clear rationale for the + changes and add benchmark data if available. See [this request](https://github.com/bitly/dablooms/pull/19) for an example. diff --git a/docs/additional-resources/reporting-bugs-and-issues.md b/docs/additional-resources/reporting-bugs-and-issues.md new file mode 100644 index 00000000..3ac63aeb --- /dev/null +++ b/docs/additional-resources/reporting-bugs-and-issues.md @@ -0,0 +1,19 @@ +Reporting Bugs and Issues +========================= + +A list of known issues in the current OpenMS release can be found [here](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/known_dev_bugs.html). Please check if your OpenMS version matches the current version and if the bug +has already been reported. + +In order to report a new bug, please create a [GitHub issue](write-and-label-github-issues.md) or [contact us](../contact-us.md). + +Include the following information in your bug report: + +1. The command line (i.e. call) including the TOPP tool and the arguments you used, or the steps you followed in a GUI + tool (e.g. TOPPView) - e.g. `FeatureFinderCentroided -in myfile.mzML -out myfile.featureXML`. +2. The output of OpenMS/TOPP (or a screenshot in case of a GUI problem). +3. Operating system (e.g. "Windows XP 32 bit", "Win 7 64 bit", "Fedora 8 32 bit", "macOS 10.6 64 bit"). +4. OpenMS version (e.g. "OpenMS 1.11.1", "Revision 63082 from the SVN repository"). +5. OpenMS architecture ("32 bit" or "64 bit") + +Please provide files that we need to reproduce the bug (e.g. `TOPP INI` files, data files — usually mzML) via a download +link, via the mailing list or by directly contacting one of the developers. diff --git a/docs/additional-resources/write-and-label-github-issues.md b/docs/additional-resources/write-and-label-github-issues.md new file mode 100644 index 00000000..f1f43192 --- /dev/null +++ b/docs/additional-resources/write-and-label-github-issues.md @@ -0,0 +1,24 @@ +Write and Label GitHub Issues +============================= + +## Create an Issue + +To create an issue: + +1. Go to the [OpenMS codebase](https://github.com/OpenMS/OpenMS). +2. Submit an [issue](https://github.com/OpenMS/OpenMS/issues/new). + +The issue will be listed under **Issues**. + +## Label an Issue + +To label an issue: + +1. On the right of the screen, select the cog icon under **Labels**. +2. Choose a label from the list. Normally, an issue can have one or more of the following labels: + - **defect**: A defect refers to a bug in OpenMS. This is a high priority issue. + - **enhancement**: An enhancement refers to a feature idea to enhance the current OpenMS code. This is a medium + priority issue. + - **task**: A task refers to a single piece of work that a developer can undertake. This is a medium priority issue. + - **refactoring**: A refactoring issue refers to a suggestion to streamline the code without changing how the code function. + - **question**: A question could trigger to a discussion about tools, parameters and scientific tasks. diff --git a/docs/faqs/contributor-faq.md b/docs/faqs/contributor-faq.md new file mode 100644 index 00000000..71e930ce --- /dev/null +++ b/docs/faqs/contributor-faq.md @@ -0,0 +1,250 @@ +Contributor FAQ +=============== + +The following contains answers to typical questions from contributors about OpenMS. + +## General + +The following section provides general information to new contributors. + +### I am new to OpenMS. What should I do first? + +* Check out the development version of OpenMS (see OpenMS [releases and installers](downloads/releases.md)). +* Build OpenMS according to the installation instructions. +* Read the [OpenMS Coding Conventions](https://github.com/OpenMS/OpenMS/wiki/Coding-conventions). +* Read the [OpenMS Tutorial](../tutorials/user-tutorial.md). +* Create a GitHub account. +* Subscribe to the [open-ms-general](https://sourceforge.net/projects/open-ms/lists/open-ms-general) or [contact us](../contact-us.md). + +### 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 [OpenMS coding conventions](). + +Coding style (brackets, variable names, etc.) must conform to the conventions. + +* The class and all the members must be documented thoroughly. +* 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](pull-request-checklist.md). + +## Troubleshooting + +The following section provides information about how to troubleshoot common OpenMS issues. + +### OpenMS complains about boost not being found + +`CMake` got confused. Set up a new build directory and try again. Build from source, deleting the `CMakeCache.txt` +and `cmake` directory might help. + +## Build System + +The following questions are related to the build system. + +### 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`. View the [cmake website](http://www.cmake.org) for more information. + +### How do I use CMake? + +See Installation instructions for your platform. +In general, call `CMake(.exe)` with some parameters to create the native build-system. +Afterwards, (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 mentioned in this document, substitute this by `CMake-GUI` if your OS is Windows. 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, pass them to `CMake` +using the `-G` option. + +### How do I switch to debug or release configuration? + +For Makefile generators (typically on Linux), 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 choose the one you like within +the IDE itself. The 'Debug' configuration enabled debug information. The 'Release' configuration disables debug +information and enables optimisation. + +### How do I add a new class to the build system? + +1. Create the new class in the corresponding sub-folder of the sub-project. The header has to be created in + `src//include/OpenMS` and the cpp file in `src//source`, e.g., + `src/openms/include/OpenMS/FORMAT/NewFileFormat.h` and `src/openms/source/FORMAT/NewFileFormat.cpp`. +2. Add both to the respective `sources.cmake` file in the same directory (e.g., `src/openms/source/FORMAT/` and + `src/openms/include/OpenMS/FORMAT/`). +3. Add the corresponding class test to `src/tests/class_tests//` + (e.g., `src/tests/class_tests/openms/source/NewFileFormat_test.cpp`). +4. Add the test to the `executables.cmake` file in the test folder (e.g., `src/tests/class_tests/openms/executables.cmake`). +5. Add them to git by using the command `git add`. + +### How do I add a new directory to the build system? + +1. Create two new `sources.cmake` files (one for `src//include/OpenMS/MYDIR`, one for + `src//source/MYDIR`), using existing `sources.cmake` files as template. +2. Add the new `sources.cmake` files to `src//includes.cmake` +3. If you created a new directory directly under `src/openms/source`, then have a look at `src/tests/class_tests/openms/executables.cmake`. +4. Add a new section that makes the unit testing system aware of the new (upcoming) tests. +5. Look at the very bottom and augment `TEST_executables`. +6. Add a new group target to `src/tests/class_tests/openms/CMakeLists.txt`. + +## Debugging + +The following section provides information about how to debug your code. + +### How do I run a single test? + +Execute an OpenMS class test using the CTest regular expressions: + +```bash + +$ ctest -V -R "^_test" + +# To build a class test, call the respective make target in ./source/TEST: + +$ make _test +``` +To run a TOPP test, use: + +```bash + +$ ctest -V -R "TOPP_" +``` + +To build the tool, use: + +```bash +$ make +``` +### How do I debug uncaught exceptions? + +Dump a core if an uncaught exception occurs, by setting the environment variable `OPENMS_DUMP_CORE`. + +Each time an uncaught exception occurs, 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? + +The `ulimit -c` unlimited command. It sets the maximum size of a core to unlimited. + +```{attention} +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? + +Debug the TOPPView application to stop at line 341 of SpectrumMDIWindow.C. + +1. Enter the following in your terminal: + + ```bash + Run gdb: + shell> gdb TOPPView +``` + +2. Start the application (and close it): + + ```bash + gdb> run [arguments] +``` + +3. Set the breakpoint: + ```bash + gdb> break SpectrumMDIWindow.C:341 +``` + +4. Start the application again (with the same arguments): + + ```bash + gdb> run + ``` + +## Cross-platform thoughts + +OpenMS runs on three major platforms. Here are the most prominent causes of "it runs on Platform A, but not on B. What now?" + +### Reading or writing binary files + +Reading or 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. + +If reading binary files, make sure to 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. + +### `UInt` vs `Size` + +Both `unsigned int` vs `size_t` `UInt` and `Size` have the same size on Linux GCC (32 bit on 32 bit systems, 64 bit on +64 bit systems), however on Windows this only holds for 32 bit. On a 64 bit Windows, the `UInt` type is still 32 bit, +while the `Size` type is 64bit. This might lead to warnings (at best) or overflows and other drawbacks. + +Therefore, do not assume that `UInt` is equal to `Size`. + +### Paths and system functions + +Avoid hardcoding e.g.`String tmp_dir = "/tmp";`. This will fail on Windows. Use Qt's `QDir` to get a path to the systems +temporary directory if required. + +Avoid names like uname which are only available on Linux. + +When working with files or directories, it is usually safe to use "/" on all platforms. Take care of spaces in directory +names though. 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. + +## Doxygen Documentation + +### Where can I find the definition of the main page? + +Find a definition of the main page [here](https://github.com/OpenMS/OpenMS/edit/develop/doc/doxygen/public/Main.doxygen). + +### Where can I add a new module? + +Add a new module [here](https://github.com/OpenMS/OpenMS/edit/develop/doc/doxygen/public/Modules.doxygen). + + +### How is the command line documentation for TOPP/UTILS tools created? + +The program `OpenMS/doc/doxygen/parameters/TOPPDocumenter.cpp` creates the command line documentation for all classes +that are included in the static `ToolHandler.cpp` tools list. It can be included in the documentation using the following `doxygen` command: + +`@verbinclude TOPP_.cli` + +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? + +View the following OpenMS tutorials: + +* `OpenMS/doc/OpenMS_tutorial/refman_overwrite.tex.in` (for PDF tutorials) +* `OpenMS/doc/doxygen/public/OpenMS_Tutorial_html.doxygen` (for html tutorials) + +View the following TOPP and TOPPView tutorials: + +* `OpenMS/doc/TOPP_tutorial/refman_overwrite.tex.in` (for PDF tutorials) +* `OpenMS/doc/doxygen/public/TOPP_Tutorial_html.doxygen` (for html tutorials) + +## Bug Fixes + +### How do I contribute to a bug fix? + +To contribute to a bug fix: + +1. Submit the bug as a GitHub issue. +2. Create a feature branch (e.g. `feature/fix_missing_filename_issue_615`) from your (up-to-date) develop branch in your fork of OpenMS. +3. Fix the bug and add a test. +4. Create a pull request for your branch. +5. After approval and merge make sure the issue is closed. + diff --git a/docs/faqs/developer-faq.md b/docs/faqs/developer-faq.md new file mode 100644 index 00000000..81b46548 --- /dev/null +++ b/docs/faqs/developer-faq.md @@ -0,0 +1,399 @@ +Developer FAQ +============= + +The following contains answers to typical questions from developers about OpenMS. + +## General + +The following section provides general information to new contributors. + +### I am new to OpenMS. What should I do first? + +* Check out the development version of OpenMS (see website). +* Build OpenMS by following the [installation instructions]() or [from source](../installations/build-openms-from-source.md). +* Read the [OpenMS Coding Conventions]() +* Read the [OpenMS Tutorial](../tutorials/user-tutorial.md). +* Create a GitHub account. +* Subscribe to the [open-ms-general](https://sourceforge.net/projects/open-ms/lists/open-ms-general) or [contact-us](../contact-us.md). + +### 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 [OpenMS coding conventions](). + +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](pull-request-checklist.md). + +### Can I use QT designer to create GUI widgets? + +Yes. 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 can I find the binary installers created? + +View the binary installers at the [build archive](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/OpenMSInstaller/nightly/). +Please verify the creation date of the individual installers, as there may have been an error while creating the installer. + +## Troubleshooting + +The following section provides information about how to troubleshoot common OpenMS issues. + +### OpenMS complains about boost not being found but I'm sure its there + +`CMake` got confused. Set up a new build directory and try again. If you build from source (not recommended), deleting +the `CMakeCache.txt` and `cmake` directory might help. + +## Build System + +The following questions are related to the build system. + +### What is CMake? + +`CMake` builds BuildSystems for different platforms, e.g. VisualStudio Solutions on Windows, Makefiles on Linux etc. +This allows to define in one central location (namely `CMakeLists.txt`) how OpenMS is build and have the platform specific +stuff handled by `CMake`. + +View the [cmake website](http://www.cmake.org) for more information. + +### How do I use CMake? + +See Installation instructions for your platform. +In general, call `CMake(.exe)` with some parameters to create the native build-system. + +```{tip} +whenever `ccmake` is mentioned in this document, substitute this by `CMake-GUI` if your OS is Windows. 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; use them with +`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_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, `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. + ```{tip} + 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. + +### How do I switch to debug or release configuration? + +For Makefile generators (typically on Linux), 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 choose the one you +like within the IDE itself. The 'Debug' configuration enabled debug information. The 'Release' configuration disables +debug information and enables optimisation. + +### 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`). What now? + +`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 do I add a new class to the build system? + +1. Create the new class in the corresponding sub-folder of the sub-project. The header has to be created in `src//include/OpenMS` and the `.cpp` file in `src//source`, e.g., `src/openms/include/OpenMS/FORMAT/NewFileFormat.h` and `src/openms/source/FORMAT/NewFileFormat.cpp`. +2. Add both to the respective `sources.cmake` file in the same directory (e.g., `src/openms/source/FORMAT/` and `src/openms/include/OpenMS/FORMAT/`). +3. Add the corresponding class test to `src/tests/class_tests//` (e.g., `src/tests/class_tests/openms/source/NewFileFormat_test.cpp`). +4. Add the test to the `executables.cmake` file in the test folder (e.g., `src/tests/class_tests/openms/executables.cmake`). +5. Add them to git by using the command `git add`. + +### How do I add a new directory to the build system? + +1. Create two new `sources.cmake` files (one for `src//include/OpenMS/MYDIR`, one for `src//source/MYDIR`), using existing `sources.cmake` files as template. +2. Add the new `sources.cmake` files to `src//includes.cmake` +3. If you created a new directory directly under `src/openms/source`, then have a look at `src/tests/class_tests/openms/executables.cmake`. +4. Add a new section that makes the unit testing system aware of the new (upcoming) tests. +5. Look at the very bottom and augment `TEST_executables`. +6. Add a new group target to `src/tests/class_tests/openms/CMakeLists.txt`. + +### How can I speed up the compile process of OpenMS? + +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. + +## Release + +View [preparation of a new OpenMS release](https://github.com/OpenMS/OpenMS/wiki/Preparation-of-a-new-OpenMS-release#release_developer) to learn more about contributing to releases. + + +## Working in Integrated Development Environments (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" + +This is a bug in Visual Studio and there is a [bug fix](http://code.msdn.microsoft.com/KB946040) 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](https://llvm.org/builds/). +To update clang-format download the binary and exchange it with the clang-format binary in your Visual Studio folder. +For Visual Studio 17 and 19 it should be located at: `C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\Llvm\bin`. + +### The indexer gets stuck at some file which ``#includes seqan`` + +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. + +### 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! + +## Debugging + +The following section provides information about how to debug your code. + +### How do I debug uncaught exceptions? + +Dump a core if an uncaught exception occurs, by setting the environment variable `OPENMS_DUMP_CORE`. + +Each time an uncaught exception occurs, 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? + +The `ulimit -c` unlimited command. It sets the maximum size of a core to unlimited. + +```{warning} +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. + +1. Enter the following in your terminal: + + ```bash + Run gdb: + shell> gdb TOPPView +``` + +2. Start the application (and close it): + + ```bash + gdb> run [arguments] +``` +3. Set the breakpoint: + ```bash + gdb> break SpectrumMDIWindow.C:341 +``` +4. Start the application again (with the same arguments): + + ```bash + gdb> run + ``` + +### How can I find out which shared libraries are used by an application? + +Linux: Use `ldd`. + +Windows (Visual studio console): See [Dependency Walker](http://www.dependencywalker.com/) (use x86 for 32 bit builds +and the x64 version for 64bit builds. Using the wrong version of depends.exe will give the 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: Use `nm `. + +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 ``. + +Use dumpbin on object files (.o) or (shared) library files (.lib) or the DLL itself e.g. `dumpbin /EXPORTS OpenMS.dll`. + +## Cross-platform thoughts + +OpenMS runs on three major platforms.. Here are the most prominent causes of "it runs on Platform A, but not on B. What now?" + +### Reading or writing binary files + +Reading or 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. + +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. + +### Paths and system functions + +Avoid hardcoding e.g.`String tmp_dir = "/tmp";`. This will fail on Windows. Use Qt's `QDir` to get a path to the systems +temporary directory if required. + +Avoid names like uname which are only available on Linux. + +When working with files or directories, it is usually safe to use "/" on all platforms. Take care of spaces in directory +names though. Quote paths if they are used in a system call to ensure that the subsequent interpreter +takes the spaced path as a single entity. + + +## Doxygen Documentation + +### Where can I find the definition of the main page? + +Find a definition of the main page [here](https://github.com/OpenMS/OpenMS/edit/develop/doc/doxygen/public/Main.doxygen). + +### Where can I add a new module? + +Add a new module [here](https://github.com/OpenMS/OpenMS/edit/develop/doc/doxygen/public/Modules.doxygen). + +### How is the parameter documentation for classes derived from DefaultParamHandler created? + +Add your class to the program ``OpenMS/doc/doxygen/parameters/DefaultParamHandlerDocumenter.cpp``. This program generates +a html table with the parameters. This table can then be included in the class documentation using the following +`doxygen` command:`@htmlinclude OpenMS_.parameters`. + +```{note} +Parameter documentation is automatically generated for `TOPP/UTILS` included in the static `ToolHandler.cpp` tools list. +``` + +To include TOPP/UTILS parameter documentation use following `doxygen` command: + + +`@htmlinclude TOPP_.parameters` + +or + +`@htmlinclude UTILS_.parameters` + +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.cpp` creates the command line documentation for all classes +that are included in the static `ToolHandler.cpp` tools list. It can be included in the documentation using the following `doxygen` command: + +`@verbinclude TOPP_.cli` + +Test if everything worked by calling `make doc_param_internal`. The command line documentation is written to +`OpenMS/doc/doxygen/parameters/output/`. + +## Bug Fixes + +### How to contribute a bug fix? + +Read [contributor quickstart guide](../guides/contributors-quickstart-guide.md). + +### How can I profile my 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: + +1. Build OpenMS in debug mode (set `CMAKE_BUILD_TYPE` to `Debug`). +2. 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). + ``` +3. Start and stop the profiling while the executable is running e.g. to skip initialization steps: +4. Start valgrind with the option `–instr-atstart=no`. +5. Call `callgrind -i [on|off]` to start/stop the profiling. +6. The output can be viewed with `kcachegrind callgrind.out`. + +### (Linux) How do I check my 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 ``. + +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](http://valgrind.org/docs/manual/) . diff --git a/docs/guides/contributors-quickstart-guide.md b/docs/guides/contributors-quickstart-guide.md new file mode 100644 index 00000000..a6bb3ccc --- /dev/null +++ b/docs/guides/contributors-quickstart-guide.md @@ -0,0 +1,75 @@ +Contribute to OpenMS +==================== + +To contribute to OpenMS: + +- Familiarise yourself with the [OpenMS online documentation](../index.rst). +- Learn how to [build OpenMS](../installations/build-openms-from-source.md). +- Check out the [OpenMS tutorial for developers](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/release/latest/html/OpenMS_tutorial.html). + +For any questions, please [contact us](../contact-us.md) at [open-ms-general]((https://sourceforge.net/projects/open-ms/lists/open-ms-general) mailing list. + +## Technical documentation + +```{note} +Untested installers and containers are known as the nightly snapshot, are released every night. They generally pass +automated continuous integration tests but no manual tests. +``` + +View the documentation for the nightly snapshot of [OpenMS develop branch](https://github.com/OpenMS/OpenMS/tree/develop) +at the [build archive](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/index.html). + +See the documentation for the [latest release](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/release/latest/html/index.html). + +## Contribution guidelines + +Before contributing to OpenMS, read information on the development model and conventions followed to maintain a coherent +code base. + +### Development model + +OpenMS follows the [Gitflow development workflow](http://nvie.com/posts/a-successful-git-branching-model/). + +Every contributor is encouraged to create their own fork (even if they are eligible to push directly to OpenMS). +To create a fork: + +1. Follow the documentation on [forking](https://help.github.com/articles/fork-a-repo). +2. Keep your fork [up-to-date](https://help.github.com/articles/syncing-a-fork). +3. Create a [pull request](https://help.github.com/articles/using-pull-requests). Before opening the pull request, please + view the [pull request guidelines](../additional-resources/pull-request-checklist.md). + +### Coding conventions + +See the manual for coding style recommended by OpenMS: [Coding conventions](https://github.com/OpenMS/OpenMS/wiki/Coding-conventions). + +```{seealso} +[C++ Guide](https://github.com/OpenMS/OpenMS/wiki/Cpp-Guide). +``` + +OpenMS automatically tests for common coding convention violations using a modified version of `cpplint`. +Style testing can be enabled using `cmake` options. We also provide a configuration file for `Uncrustify` for automated +style corrections (see `tools/uncrustify.cfg`). + +### Commit messages + +View the guidelines for commit messages: [How to write commit messages](https://github.com/OpenMS/OpenMS/wiki/HowTo---Write-Commit-Messages). + +### Automated unit tests + +Nightly tests run on different platforms. It is recommended to test on different platforms. + +```{tip} +This saves time and increases productivity during continuous integration tests. +``` + +Nightly tests: [CDASH](http://cdash.openms.de/index.php?project=OpenMS). + +## Further contributor resources + +Consider the following resources for further information: + +- **Guidelines for adding new dependency libraries**: View the guidelines for [adding new dependency libraries](). +- **Experimental installers**: We automatically build installers for different platforms. These usually contain + unstable or partially untested code. + The nightly (unstable) installers are available at the [build archive](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/OpenMSInstaller/nightly/). +- **Developer FAQ**: Visit the [Developer FAQ](../faqs/developer-faq.md) to get answers to frequently asked questions. diff --git a/docs/images/additional-resources/click-fork.png b/docs/images/additional-resources/click-fork.png new file mode 100644 index 00000000..0ca09e1e Binary files /dev/null and b/docs/images/additional-resources/click-fork.png differ diff --git a/docs/images/tutorials/proteowizard.png b/docs/images/tutorials/proteowizard.png new file mode 100644 index 00000000..64733b22 Binary files /dev/null and b/docs/images/tutorials/proteowizard.png differ diff --git a/docs/images/tutorials/topp/MetaDataBrowser.png b/docs/images/tutorials/topp/MetaDataBrowser.png new file mode 100644 index 00000000..93d88edf Binary files /dev/null and b/docs/images/tutorials/topp/MetaDataBrowser.png differ diff --git a/docs/images/tutorials/topp/TOPPView_statistics.png b/docs/images/tutorials/topp/TOPPView_statistics.png new file mode 100644 index 00000000..84262818 Binary files /dev/null and b/docs/images/tutorials/topp/TOPPView_statistics.png differ diff --git a/docs/images/tutorials/topp/TOPPView_tools.png b/docs/images/tutorials/topp/TOPPView_tools.png new file mode 100644 index 00000000..c7fe7cd8 Binary files /dev/null and b/docs/images/tutorials/topp/TOPPView_tools.png differ diff --git a/docs/index.rst b/docs/index.rst index 63d1ebbe..aab0b3ef 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -48,6 +48,7 @@ Contents :caption: Quick Start Guides guides/user-guides/user-quickstart-guide + guides/contributors-quickstart-guide.md .. toctree:: :maxdepth: 2 @@ -62,6 +63,22 @@ Contents topp/topp.md +.. toctree:: + :maxdepth: 2 + :caption: Frequently Asked Questions + + developer-faq.md + contributor-faq.md + +.. toctree:: + :maxdepth: 2 + :caption: Additional Resources + + additional-resources/openms-git-workflow.md + additional-resources/reporting-bugs-and-issues.md + additional-resources/write-and-label-github-issues.md + additional-resources/pull-request-checklist.md + .. toctree:: :maxdepth: 2 :caption: Downloads diff --git a/docs/installations/build-openms-from-source.md b/docs/installations/build-openms-from-source.md new file mode 100644 index 00000000..6dc18d47 --- /dev/null +++ b/docs/installations/build-openms-from-source.md @@ -0,0 +1,10 @@ +Build OpenMS From Source +======================== + +To build OpenMS, please follow the build instructions for: + +* [Linux](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/release/latest/html/install_linux.html) +* [macOS](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/release/latest/html/install_mac.html) +* [Windows](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/release/latest/html/install_win.html) + +Instructions to build pyOpenMS can be found in the [pyOpenMS documentation](https://pyopenms.readthedocs.io/en/latest/build_from_source.html). diff --git a/openms-wiki/about.md b/openms-wiki/about.md new file mode 100644 index 00000000..79d4233b --- /dev/null +++ b/openms-wiki/about.md @@ -0,0 +1,15 @@ + +About +===== + +OpenMS is an open-source C++ library for Mass Spectrometry (MS) data management and analyses. It offers an infrastructure for the rapid development of mass spectrometry-related software. OpenMS is free software available under the [three-clause BSD license](https://github.com/OpenMS/OpenMS-docs/blob/main/LICENSE). It is available for Windows, macOS and Linux. + +OpenMS comes with a vast variety of pre-built and ready-to-use tools for proteomics and metabolomics data analysis (TOPP tools), and powerful 2D and 3D visualisation (TOPPView). It supports analyses for various quantification protocols, including label-free shotgun proteomics, SILAC, iTRAQ, SRM, and SWATH. It also provides built-in algorithms for peptide/protein identification, both de-novo and via database searching, as well as adapters to state-of-the-art tools like X! Tandem, Mascot, OMSSA, and others. + +Through the TOPP tools concept and unified parameter handling (CTD), OpenMS supports easy integration into workflow engines like TOPPAS (included), KNIME, Galaxy, and WS-PGRADE. + +With pyOpenMS, OpenMS offers Python bindings to a large part of the API to enable rapid computational mass spectrometry development. + +OpenMS supports the Proteomics Standard Initiative (PSI) file formats for MS data. + +The main contributors of OpenMS are currently Eberhard-Karls Universität in Tübingen, Freie Universität Berlin and ETH Zurich. diff --git a/openms-wiki/contributors-quickstart-guide.md b/openms-wiki/contributors-quickstart-guide.md new file mode 100644 index 00000000..a387a9ac --- /dev/null +++ b/openms-wiki/contributors-quickstart-guide.md @@ -0,0 +1,71 @@ +Contribute to OpenMS +==================== + +If you would like to contribute to OpenMS: + +* Familiarise yourself with our [online documentation](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/release/latest/html/index.html). + +* Learn how to [build OpenMS](build-openms-from-source.md). + +* Check out the [OpenMS tutorial for developers](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/release/latest/html/OpenMS_tutorial.html). + +For any questions, please [contact us](contact-us.md) at [open-ms-general]((https://sourceforge.net/projects/open-ms/lists/open-ms-general) mailing list. + +## Technical Documentation +Untested installers and containers are known as the nightly snapshot, are released every night. They generally pass automated continuous integration tests but no manual tests. + +View the documentation for the nightly snapshot of [OpenMS develop branch](https://github.com/OpenMS/OpenMS/tree/develop) at the [build archive](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/index.html). + +View the [doxygen log](https://abibuilder.informatik.uni-tuebingen.de/jenkins/job/openms/job/ntly/job/TstPkg/compiler=appleclang-11.0.0,os_label=catalina/lastBuild/artifact/build/doc/doxygen/doxygen-error.log). + +See the documentation for the [latest release](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/release/latest/html/index.html). + +View the [doxygen log](https://abibuilder.informatik.uni-tuebingen.de/jenkins/job/openms_release_packaging/lastBuild/compiler=appleclang-7.3.0,os_label=elcapitan/artifact/build/doc/doxygen/doxygen-error.log). + +## Contribution Guidelines + +Before contributing to OpenMS, read information on the development model and conventions followed to maintain a coherent code base. + +### Development model + +OpenMS follows the [Gitflow development workflow](http://nvie.com/posts/a-successful-git-branching-model/). + +Every contributor is encouraged to create their own fork (even if they are eligible to push directly to OpenMS). To create a fork: +1. Follow the documentation on [forking](https://help.github.com/articles/fork-a-repo). +2. Keep your fork [up-to-date](https://help.github.com/articles/syncing-a-fork). +3. Create a [pull request](https://help.github.com/articles/using-pull-requests). Before opening the pull request, please view the [checklist](pull-request-checklist.md). + +### Coding conventions + +See the manual for coding style recommended by OpenMS: [Coding conventions](https://github.com/OpenMS/OpenMS/wiki/Coding-conventions). +also see: [C++ Guide](https://github.com/OpenMS/OpenMS/wiki/Cpp-Guide). + +View the [manual]() for creating a new build unit (to be completed). + +OpenMS automatically tests for common coding convention violations using a modified version of `cpplint`. +Style testing can be enabled using `cmake` options. We also provide a configuration file for `Uncrustify` for automated style corrections (see `tools/uncrustify.cfg`). + +### Commit messages + +View the guidelines for commit messages: [How to write commit messages](https://github.com/OpenMS/OpenMS/wiki/HowTo---Write-Commit-Messages). + +### Automated unit tests + +Nightly tests run on different platforms. It is recommended to test on different platforms. This will save you time and surprises during continuous integration tests. + +Nightly tests: [CDASH](http://cdash.openms.de/index.php?project=OpenMS) + +## Further Contributor Resources + +You may want to consider the following resources: +* **Guidelines for adding new dependency libraries** + + View the guidelines for [adding new dependency libraries](). +* **Experimental installers** + + We automatically build installers for different platforms. These usually contain unstable or partially untested code. + + The nightly (unstable) installers are available at the [build archive](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/OpenMSInstaller/nightly/). +* **Developer FAQ** + + Visit the [Developer FAQ](developer-faq.md) to get answers to frequently asked questions. diff --git a/openms-wiki/developer-faq.md b/openms-wiki/developer-faq.md new file mode 100644 index 00000000..960387d1 --- /dev/null +++ b/openms-wiki/developer-faq.md @@ -0,0 +1,491 @@ +Developer FAQ +============= + +The following contains answers to typical questions from developers about OpenMS. + +## General + +The following section provides general information to new contributors. + +### I am new to OpenMS. What should I do first? + +* Check out the development version of OpenMS (see website). +* Try and build OpenMS according to the installation instructions. +* Read the [OpenMS Coding Conventions](https://github.com/OpenMS/OpenMS/wiki/Coding-conventions). +* Read the OpenMS Tutorial. +* Create a GitHub account. +* Subscribe to the [open-ms-general](https://sourceforge.net/projects/open-ms/lists/open-ms-general) and [open-ms-developers]() mailing lists. + > ***_NOTE:_*** You can see the developers list only if you are logged in to Sourceforge and if you are a OpenMS developer. + +### 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 [OpenMS coding conventions](coding-conventions.md). + +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](pull-request-checklist.md). + +### How do I update the [openms.de](https://www.openms.de)? + +Login to the [wordpress admin area](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. 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 can I find the binary installers created? + +View the binary installers at the [build archive](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/OpenMSInstaller/nightly/). +Please verify the creation date of the individual installers, as there may have been an error while creating the installer. + +## Troubleshooting + +The following section provides information about how to troubleshoot common OpenMS issues. + +### OpenMS complains about boost not being found but I'm sure its there + +`CMake` got confused. Set up a new build directory and try again. If you build from source (not recommended), deleting the `CMakeCache.txt` and `cmake` directory might help. + +## Build System + +The following questions are related to the build system. + +### 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`. + +View the [cmake website](http://www.cmake.org) for more information. + +### How do I use CMake? + +See Installation instructions for your platform. +In general, call `CMake(.exe)` with some parameters to create the native build-system. + +> **_NOTE:_** whenever `ccmake` is mentioned in this document, substitute this by `CMake-GUI` if your OS is Windows. 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; use them with `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_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`. If you need the `contrib` libraries, set the variable `CMAKE_FIND_ROOT_PATH`. +On Windows, you always need the `contrib` folder, 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` Define if you want to build Debug or Release version of OpenMS. Release is the default. + +* `CMAKE_FIND_ROOT_PATH` The path to the `contrib` libraries. + > **_NOTE:_** that you can also 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. + +* `MT_CUDA_BUILD_TYPE` ... + +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. + +### How do I switch to debug or 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 optimisation. + +### 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 delete the `CMakeCache.txt`, but all other custom settings will be lost. + +### 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 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? + +Use the latest if possible. 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 to the build system? + +1. Create the new class in the corresponding sub-folder of the sub-project. The header has to be created in `src//include/OpenMS` and the cpp file in `src//source`, e.g., `src/openms/include/OpenMS/FORMAT/NewFileFormat.h` and `src/openms/source/FORMAT/NewFileFormat.cpp`. +2. Add both to the respective sources.cmake file in the same directory (e.g., `src/openms/source/FORMAT/` and `src/openms/include/OpenMS/FORMAT/`). +3. Add the corresponding class test to src/tests/class_tests// (e.g., `src/tests/class_tests/openms/source/NewFileFormat_test.cpp`). +4. Add the test to the `executables.cmake` file in the test folder (e.g., `src/tests/class_tests/openms/executables.cmake`). +5. Add them to git by using the command `git add`. + +### How do I add a new directory to the build system? + +1. Create two new `sources.cmake` files (one for `src//include/OpenMS/MYDIR`, one for `src//source/MYDIR`), using existing `sources.cmake` files as template. +2. Add the new `sources.cmake` files to `src//includes.cmake` +3. If you created a new directory directly under `src/openms/source`, then have a look at `src/tests/class_tests/openms/executables.cmake`. +4. Add a new section that makes the unit testing system aware of the new (upcoming) tests. +5. Look at the very bottom and augment `TEST_executables`. +6. Add a new group target to `src/tests/class_tests/openms/CMakeLists.txt`. + +### Class/Unit tests and TOPP/Tool tests + +Class or unit tests are 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 in question. + +Only add tests for functions added outside of your additional mode. + +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 and are meaningful. + +Each tool test consists of: + +* An executable call on a test dataset (by using either fixed command line parameters or an 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` (if edited) executable first everytime. +`ctest` does not have any automatic dependency on the timestamps of the executables. + +### How do I add a test for a new class? + +You should always add a test alongside every new class added to OpenMS. + +To add a new class test: + +1. Add the class test to `src/tests/class_tests//` (e.g., `src/tests/class_tests/openms/source/NewFileFormat_test.cpp`). +2. Add the test to the `executables.cmake` file in the test folder. +3. Add them to git using the `git add` command. + +A test template for your specific class can be generated by the `create_test.php` script found in `tools/`. + +To generate a test template for your class: + +1. Make sure your generated XML files containing the class information make doc_xml. +2. Call: +```bash +php tools/create_test.php /BUILD_DIRECTORY/ / PATH_TO_HEADER/MyClass.h \ "FIRSTNAME LASTNAME" > ./src/tests/class_tests/openms/source/MyClass_test.cpp +``` + +### How do I add a new GUI test (for QT Gui classes) for the class `MyClass`? +To add a new GUI test: + +1. Create the `MyClass_test.cpp` in `src/tests/class_tests/openms_gui/source`. +2. Add it to `src/tests/class_tests/openms_gui/CMakeLists.txt` in the GUI section. +3. Have a look at existing GUI tests, as they use the `QT TestLib` framework and not the OpenMS macros. + +### (Linux) All tests fail when you execute `make test` + +Check the `LD_LIBRARY_PATH` environment variable: + +You can 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`. + +### How can I speed up the compile process of OpenMS? + +To speed up the compile process of OpenMS, use several threads. If you have several processors/cores, you can 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. + +## Release + +View [Preparation of a new OpenMS release](https://github.com/OpenMS/OpenMS/wiki/Preparation-of-a-new-OpenMS-release#release_developer) to learn more about contributing to releases. + +## Continuous integration + +### How does travis work? + +[Travis](https://travis-ci.org/) is an automated system for continuous integration. 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? + +Try to restart travis, it sometimes hangs and since it builds on shared infrastructure, the next build may work better. This needs to be done by a OpenMS core developer. + +Since we use extensive caching, the build may take much longer when many files are touched and may never complete in that case (running into the travis time limit). In that case we can rebuild the cache using the following approach: +```bash + $ git cherry-pick 89c5cd7f2d9d343b3d63fc6bab18e08dcd969c05 + + $ git push origin develop + + # Now wait for the build to complete + + $ git revert 89c5cd7f2d9d343b3d63fc6bab18e08dcd969c05 + + $ git push origin develop +``` + +## Working in Integrated Development Environments (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. You can find the source files for each test within its own subproject. The same is true for the `TOPP` and `UTILS` classes. + +### How can I easily update a lot of test files (e.g., after a small format change in result files)? + +Using `grep` one can simply extract the lines starting with `diff FILENAME1 FILENAME2` and replace the `diff` by `copy`. + +### I'm getting the error "Error C2471: cannot update program database" + +This is a bug in Visual Studio and there is a [bug fix] (http://code.msdn.microsoft.com/KB946040) 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 you're using you 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. However, you can update clang-format by hand using the pre-build clang-format binary. Both the binary and a link to the plugin can be found [here](https://llvm.org/builds/). +To update clang-format by hand just download the binary and exchange it with the clang-format binary in your Visual Studio folder. +For Visual Studio 17 and 19 it should be located at: `C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\Llvm\bin`. + +### The indexer gets stuck at some file which ``#includes seqan`` + +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. + +### 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 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! + +## Debugging + +The following section provides information about how to debug your code. + +### How do I run a single test? + +You can can execute an OpenMS class test using the CTest regular expressions: + +```bash + +ctest -V -R "^_test" + +# To build a class test, you simply call the respective make target in ./source/TEST: + +make _test +``` +To run a TOPP test, you can use: + +```bash + +ctest -V -R "TOPP_" +``` + +To build the tool, use: + +```bash +make +``` +### How do I debug uncaught exceptions? + +You can dump a core if an uncaught exception occurs, by setting the environment variable `OPENMS_DUMP_CORE`. + +Each time an uncaught exception occurs, 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. + +1. Enter the following in your terminal: + + ```bash + Run gdb: + shell> gdb TOPPView +``` + +2. Start the application (and close it): + + ```bash + gdb> run [arguments] +``` +3. Set the breakpoint: + ```bash + gdb> break SpectrumMDIWindow.C:341 +``` +4. Start the application again (with the same arguments): + + ```bash + gdb> run + ``` + +### How can I find out which shared libraries are used by an application? + +Linux: Use `ldd`. + +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 the 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: Use `nm `. + +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 ``. + +You can use dumpbin on object files (.o) or (shared) library files (.lib) or the DLL itself e.g. `dumpbin /EXPORTS OpenMS.dll`. + +## Cross-platform thoughts + +OpenMS runs on three major platforms.. Here are the most prominent causes of "it runs on Platform A, but not on B. What now?" + +### Reading or writing binary files +Reading or 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. + +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. + +### `UInt` vs `Size` +Both `unsigned int` vs `size_t` `UInt` and `Size` have the same size on Linux GCC (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, while the `Size` type is 64bit. This might lead to warnings (at best) or overflows and other drawbacks. +Therefore, do not assume that `UInt` is equal to `Size`. + +### Paths and system functions + +Avoid hardcoding e.g.`String tmp_dir = "/tmp";`. This will fail on Windows. Use Qt's `QDir` to get a path to the systems temporary directory if required. + +Avoid names like uname which are only available on Linux. + +When working with files or directories, it is usually safe to use "/" on all platforms. 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. + + +## PyOpenMS - Troubleshooting + +The following section contains answers to common issues experienced in pyOpenMS. + +### How can I wrap my new method with PyOpenMS? + +You will have to add an entry to `src/pyOpenMS/pxds/CLASS_NAME.pxd` with the signature of your new method(s). + +### How can I wrap my new class with PyOpenMS? + +You will have to create a new file `src/pyOpenMS/pxds/CLASS_NAME.pxd` that is explained in the [pyOpenMS documentation](https://pyopenms.readthedocs.io/en/latest/wrap_classes.html?highlight=Wrapping%20classes#wrapping-workflow-and-wrapping-new-classes). + +### Can I use output parameters for methods with multiple outputs? + +Python does not support passing primitive types (`int`, `double`, etc.) by reference. Therefore, `void calculate(double &)` will not work. + +## Doxygen Documentation + +### Where can I find the definition of the main page? + +You can find a definition of the main page [here](https://github.com/OpenMS/OpenMS/edit/develop/doc/doxygen/public/Main.doxygen). + +### Where can I add a new module? + +You can add a new module [here](https://github.com/OpenMS/OpenMS/edit/develop/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.cpp``. This program generates a html table with the parameters. This table can then be included in the class documentation using the following `doxygen` command:`@htmlinclude OpenMS_.parameters`. + +> **_NOTE:_** parameter documentation is automatically generated for `TOPP/UTILS` included in the static `ToolHandler.cpp` tools list. + +To include TOPP/UTILS parameter documentation use following `doxygen` command: + + +`@htmlinclude TOPP_.parameters` + +or + +`@htmlinclude UTILS_.parameters` + +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.cpp` creates the command line documentation for all classes that are included in the static `ToolHandler.cpp` tools list. It can be included in the documentation using the following `doxygen` command: + +`@verbinclude TOPP_.cli` + +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? + +View the following OpenMS tutorials: + +* `OpenMS/doc/OpenMS_tutorial/refman_overwrite.tex.in` (for PDF tutorials) +* `OpenMS/doc/doxygen/public/OpenMS_Tutorial_html.doxygen~` (for html tutorials) + +For TOPP and TOPPView tutorials, view: + +* `OpenMS/doc/TOPP_tutorial/refman_overwrite.tex.in` (for PDF tutorials) +* `OpenMS/doc/doxygen/public/TOPP_Tutorial_html.doxygen` (for html tutorials) + +## Bug Fixes + +### How to contribute a bug fix? + +To contribute to a bug fix: +1. Submit the bug as a GitHub issue. +2. Create a feature branch (e.g. `feature/fix_missing_filename_issue_615`) from your (up-to-date) develop branch in your fork of OpenMS. +3. Fix the bug and add a test. +4. Create a pull request for your branch. +5. After approval and merge make sure the issue is closed. + +### How can I profile my code? + +Try 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: + +1. Build OpenMS in debug mode (set `CMAKE_BUILD_TYPE` to `Debug`). +2. Call the executable with valgrind: `valgrind –tool=callgrind`. + > **_NOTE:_** other processes running on the same machine can influence the profiling. Make sure your application gets enough resources (memory, CPU time). + +3. You can start and stop the profiling while the executable is running e.g. to skip initialization steps: +4. Start valgrind with the option `–instr-atstart=no`. +5. Call `callgrind -i [on|off]` to start/stop the profiling. +6. The output can be viewed with `kcachegrind callgrind.out`. + +### (Linux) How do I check my 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 ``. + +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](http://valgrind.org/docs/manual/) . diff --git a/openms-wiki/pull-request-checklist.md b/openms-wiki/pull-request-checklist.md new file mode 100644 index 00000000..1cd0bba7 --- /dev/null +++ b/openms-wiki/pull-request-checklist.md @@ -0,0 +1,48 @@ +Pull Request Checklist +====================== + +Before you open a pull request, make sure you check the following: + +* **Does the code build?** + + Execute `make` (or your build system's equivalent, e.g., `cmake --build . --target ALL_BUILD --config Release` on Windows). +* **Do all tests pass?** + + To check if all tests have passed, execute `ctest`. + If a test that is unrelated to your changes fails, check the [nightly builds](http://cdash.openms.de/index.php?project=OpenMS) to see if the error is also in `develop`. If the error is in develop, [create a github issue](write-and-label-github-issues.md). +* **Is the code documented?** + + Document all new classes, including their methods and parameters. + It is also recommended that you also document non-public members and methods. +* **Does the code introduce changes to the API?** + + If the code introduces changes to the API, make sure that the documentation is up-to-date and that the Python bindings (pyOpenMS) still work. For each change in the C++ API, make a change in the Python API wrapper via the `pyOpenMS/pxds/` files. + +* **Have you completed regression testing?** + + Make sure that you include a test in the test suite for: + + * Public methods of a class + * TOPP tools + * Bug fixes + +Make sure to: +* **Rebase before you open a pull request.** + + To include all recent changes, rebase your branch on `develop` before you open a pull request. + + If you pushed your branch to `origin` before rebasing, git will most likely tell you after the rebase that your local branch and the remote branch have diverged. + + If you are sure that the remote branch does not contain any local commits in the rebased version, you can safely push using `git push -f origin ` to enforce overwrite. If not, contact your local git expert on how to get the changes into your local branch. + +* **Capture similar changes in a single commit** + + Each commit should represent one logical unit. Consolidate multiple commits if they belong together or split single commits if they are unrelated. For example, committing code formatting together with a one-line fix makes it very hard to figure out what the fix was and which changes were inconsequential. + +* **Create a pull request for a single feature or bug** + + If you have multiple features or fixes in a pull request, you might get asked to split your request and open multiple pull requests instead. + +* **Describe what you have changed in your pull request.** + + When opening the pull request, give a detailed overview of what has changed and why. Include a clear rationale for the changes and add benchmark data if available. See [this request](https://github.com/bitly/dablooms/pull/19) for an example. diff --git a/openms-wiki/reporting-bugs-and-issues.md b/openms-wiki/reporting-bugs-and-issues.md new file mode 100644 index 00000000..7d1db3b6 --- /dev/null +++ b/openms-wiki/reporting-bugs-and-issues.md @@ -0,0 +1,15 @@ +Reporting Bugs and Issues +========================= + +A list of known issues in the current OpenMS release can be found [here](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/known_dev_bugs.html). Please check if your OpenMS version matches the current version and if the bug has already been reported. + +In order to report a new bug, please use either our [GitHub issues system](write-and-label-github-issues.md) or [contact us](contact-us.md). + +Include the following information in your bug report: +* the command line (i.e. call) including the TOPP tool and the arguments you used, or the steps you followed in a GUI tool (e.g. TOPPView) - e.g. `FeatureFinderCentroided -in myfile.mzML -out myfile.featureXML` +* the output of OpenMS/TOPP (or a screenshot in case of a GUI problem) +* operating system (e.g. "Windows XP 32bit", "Win 7 64bit", "Fedora 8 32bit", "macOS 10.6 64bit") +* OpenMS version (e.g. "OpenMS 1.11.1", "Revision 63082 from the SVN repository") +* OpenMS architecture ("32 bit" or "64 bit") + +Please provide files that we need to reproduce the bug (e.g. `TOPP INI` files, data files — usually mzML) via a download link, via the mailing list or by directly contacting one of the developers. diff --git a/openms-wiki/users-quickstart-guide.md b/openms-wiki/users-quickstart-guide.md new file mode 100644 index 00000000..a57ae4ed --- /dev/null +++ b/openms-wiki/users-quickstart-guide.md @@ -0,0 +1,10 @@ +Users Quick Start Guide +======================= + +Download the current stable version of OpenMS from the [OpenMS download site](http://open-ms.de/downloads) or via the [OpenMS docker containers](). + +Familiarise yourself with OpenMS by reading [Röst et al, OpenMS: a flexible open-source software platform for mass spectrometry data analysis. Nat Methods. 2016](https://www.ncbi.nlm.nih.gov/pubmed/27575624) as well as [Getting Started](http://www.openms.de/getting-started) on openms.de. + +Read the OpenMS documentation (especially for TOPP) available from the [OpenMS documentation site](http://www.openms.de/current_doxygen) or in the folder `doc/index.html` of stable releases. + +Download some example workflows with optimised parameter settings from the [repository](). To understand which tools are available, read the [TOPP Tool documentation page](http://www.openms.de/current_doxygen/html/TOPP_documentation.html) as well as the [UTILS Tool documentation page](http://www.openms.de/current_doxygen/html/UTILS_documentation.html). diff --git a/openms-wiki/write-and-label-github-issues.md b/openms-wiki/write-and-label-github-issues.md new file mode 100644 index 00000000..d788ca76 --- /dev/null +++ b/openms-wiki/write-and-label-github-issues.md @@ -0,0 +1,40 @@ +Write and Label GitHub Issues +============================= + +## Create an Issue + +To create an issue: + +1. Go to the [OpenMS codebase](https://github.com/OpenMS/OpenMS). +2. Click **Issues** in the menu at the top of the screen. +3. Click **New issue**. +4. Provide a title and a description to the issue. +5. Label the issue. +6. Click **Submit new issue**. + +The issue will be listed under **Issues**. + +## Label an Issue + +To label an issue: +1. On the right of the screen, select the cog icon under **Labels**. +2. Choose a label from the list. Normally, an issue can have one or more of the following labels: + * **defect** + + A defect refers to a bug in OpenMS. This is a high priority issue. + + * **enhancement** + + An enhancement refers to a feature idea to enhance the current OpenMS code. This is a medium priority issue. + + * **task** + + A task refers to a single piece of work that a developer can undertake. This is a medium priority issue. + + * **refactoring** + + A refactoring issue refers to a suggestion to streamline the code without changing how the code function. + + * **question** + + A question could trigger to a discussion about tools, parameters and scientific tasks.