diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 9c192a88..ff30302a 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -41,7 +41,7 @@ For any questions, drop us a ping in [OpenMS Gitter](https://gitter.im/OpenMS/Op - See Also Example of these are present in documentation, please follow them. 11. Always specify lexers for code blocks. -12. Format keyboard strokes using `qwerty-keyboard-button`. +12. Format keyboard strokes using `qwerty-keyboard-button`, as an example, please see [this](../docs/tutorials/TOPP/hotkeys-table.md) file. 13. Be nice, polite, and respectful. ### Naming files diff --git a/conf.py b/conf.py index 9fe98ca3..0524eee0 100644 --- a/conf.py +++ b/conf.py @@ -21,10 +21,6 @@ copyright = '2022, OpenMS Team' author = 'OpenMS Team' -# The full version, including alpha/beta/rc tags -release = '2.8.0' - - # -- General configuration --------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be diff --git a/docs/additional-resources/external-code-using-openms.md b/docs/additional-resources/external-code-using-openms.md index 5371faf8..253e1c46 100644 --- a/docs/additional-resources/external-code-using-openms.md +++ b/docs/additional-resources/external-code-using-openms.md @@ -105,14 +105,14 @@ well, and manually copy the new executable to the `TOPP/UTILS` binary directory If you do NOT use the installer, copy all required files manually, plus a few extra steps, see below. What needs to be done is a little platform dependent, thus very cumbersome to explain. Look at the cmake installer scripts, to see whats -required (for Mac and Linux see `OpenMS/cmake/package*.cmake`). +required (for macOS and Linux see `OpenMS/cmake/package*.cmake`). In short: - copy the `OpenMS/share/OpenMS` directory to the client machine (e.g `/share`) and set the environment variable `OPENMS_DATA_PATH` to this directory -- copy the OpenMS library (`OpenMS.dll` for Windows or `OpenMS.so/.dylib` for Linux/Mac) to `/bin`. -- copy all Qt4 libraries to the client `/bin` or on Linux/Mac make sure you have installed the Qt4 package +- copy the OpenMS library (`OpenMS.dll` for Windows or `OpenMS.so/.dylib` for Linux/macOS) to `/bin`. +- copy all Qt4 libraries to the client `/bin` or on Linux/macOS make sure you have installed the Qt4 package - [Windows only] copy Xerces dll (see `contrib/lib`) to `/bin` - [Windows only] install the VS redistributable package (see Microsoft Homepage) on the client machine which corresponds to the VS version that was used to compile your code (use the correct redistributable package!, i.e., architecture diff --git a/docs/advanced-resources/build-custom-openms-knime-package.md b/docs/advanced-resources/build-custom-openms-knime-package.md deleted file mode 100644 index 24d45584..00000000 --- a/docs/advanced-resources/build-custom-openms-knime-package.md +++ /dev/null @@ -1,115 +0,0 @@ -Build Custom OpenMS KNIME package -================================ - -The following guidelines should help in preparing your own KNIME package. If you still encounter any errors, please -[contact us](../contact-us.md). - -## Prerequisites - -- **KNIME SDK**: Download it from the [KNIME Download Site](https://www.knime.com/downloads) (at the end of the page). - We will use Version 2.9.2 (We assume that you have installed it to ~/Development/knime/eclipse_knime_2.9.2 but it could - be anywhere). -- **Apache Ant**: The Generic KNIME Plugins project uses Apache Ant as the build system. On Linux and Mac, install it - using your package manager. For Windows, see the [Apache Ant Downloads](https://ant.apache.org/bindownload.cgi). For - macOS, `brew install ant`. -- A clone of OpenMS and a compiled contrib should be available on your system. Please check the OpenMS documentation for - instructions how to compile OpenMS. For simplicity we will assume that the OpenMS build tree is located in - `~/Development/OpenMS/build`. - -## Prepare your build environment and create the plugin directory - -To generate the source code of the OpenMS KNIME plugin, prepare the build environment. For this, download a recent version -of the search engines distributed with OpenMS. Checkout the tested versions of the binaries matching your system from the -OpenMS subversion repository at sourceforge. Let's assume that the search engines are located in -`~/Development/knime/SEARCHENGINES/`. - -```bash -svn export --force https://github.com/OpenMS/THIRDPARTY/trunk/All ~/Development/knime/SEARCHENGINES_ALL -svn export --force https://github.com/OpenMS/THIRDPARTY/trunk/Linux/64bit ~/Development/knime/SEARCHENGINES -mv "~/Development/knime/SEARCHENGINES_ALL/LuciPHOr2" "~/Development/knime/SEARCHENGINES_ALL/MSGFPlus" "~/Development/knime/SEARCHENGINES/" -``` - -to get the search engines for 64 bit linux build. Supported builds can be found in the [thirdparty tool repository](https://github.com/OpenMS/THIRDPARTY). Ensure that in `~/Development/knime/SEARCHENGINES` ou now have multiple folders (one per searchengine) that -each immediately contain the respective binaries (and metafiles) for all searchengines. - -After downloading the search engines we can activate the knime preparation in the OpenMS build system by calling cmake -with some specific arguments in the build directory. - -``` -$ cd ~/Development/OpenMS/build -$ cmake -D SEARCH_ENGINES_DIRECTORY=$HOME/Development/knime/SEARCHENGINES/ -D ENABLE_PREPARE_KNIME_PACKAGE=On . -``` - -now, if you used the Makefile generator, execute the `prepare_knime_package` target, e.g., - -``` -$ make prepare_knime_package -``` - -This should recompile OpenMS and construct all the necessary input files for the KNIME plugin generation in the directory -`~/Development/OpenMS/build/ctds`. - -## Generate the plugin source code - -Based on the files generated in the previous step, now, generate the source code of the KNIME plugin using the -GenericKNIMENodes NodeGenerator tool. Start by cloning the latest version of the GenericKNIMENodes into the directory -`~/Development/knime/GenericKnimeNodes`: - -```bash -$ cd ~/Development/knime -$ git clone git://github.com/genericworkflownodes/GenericKnimeNodes.git -``` - -The node generator can easily be called using `ant`: - -```bash -$ cd ~/Development/knime/GenericKnimeNodes -$ ant -Dplugin.dir=$HOME/Development/OpenMS/build/ctds -Dcustom.plugin.generator.target=$HOME/Development/knime/openms_plugin/ -``` - -This will generate the source code of the OpenMS plugin in the directory `~/Development/knime/openms_plugin/`. - - -## Compiling and running the OpenMS plugin - -Before compiling and testing the OpenMS KNIME plugin we have to install some additional plugins necessary for building -the OpenMS nodes. For this we start the previously downloaded KNIME SDK and click on **Help** > **Install New Software...**. - - In the now open dialog we select the **KNIME Desktop Update Site**. - - ![](../images/advanced-resources/KNIME-Desktop-Update-Site.png) - - From the list below we select the `KNIME File Handling Nodes`, the `KNIME Build System`, and the `KNIME Testing Framework`. - - ```{tip} -KNIME Build System and KNIME Testing Framework (ships with KNIME SDK) are probably not necessary to install. - ``` - -![](../images/advanced-resources/KNIME-File-Handling-Nodes.png) - -![](../images/advanced-resources/KNIME-Build-System.png) - -Now follow the installation procedure by clicking on **Next**. - -Now that the KNIME SDK is properly setup import the GenericKNIMENodes plugin and the generated OpenMS plugin by clicking -on **File** > **Import...**. First select `Existing Projects into Workspace` and select the GenericKNIMENodes directory -(`~/Development/knime/GenericKnimeNodes`). Repeat those steps with the OpenMS plugin directory -(`~/Development/knime/openms_plugin/`). - -![](../images/advanced-resources/Existing-Projects-into-Workspace.png) - -![](../images/advanced-resources/select-root-directory.png) - -This should add the base plugin and the OpenMS plugin to your build environment. Note that it is necessary to copy both -`de.openms.*` and `com.genericworkflownodes.*` into the same subfolder. - -Now, start a KNIME instance from within the SDK by clicking on **Run** > **Run Configurations...**. Double click on -**Eclipse Application** to create a new run configuration. - -![](../images/advanced-resources/eclipse-application.png) - -Rename the run configuration (e.g., KNIME Testing) and select `org.knime.product.KNIME_PRODUCT` in `Run a product`. - -![](../images/advanced-resources/new-configuration.png) - -After clicking **Run** a new KNIME instance should start containing the OpenMS KNIME nodes. diff --git a/docs/faqs/contributor-faq.md b/docs/faqs/contributor-faq.md index 71e930ce..aaf96ebe 100644 --- a/docs/faqs/contributor-faq.md +++ b/docs/faqs/contributor-faq.md @@ -68,13 +68,6 @@ the `CMakeCache.txt` file directly. 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 @@ -132,15 +125,6 @@ Dump a core if an uncaught exception occurs, by setting the environment variable 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. @@ -169,40 +153,6 @@ Debug the TOPPView application to stop at line 341 of SpectrumMDIWindow.C. 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? diff --git a/docs/guides/contributors-quickstart-guide.md b/docs/guides/contributors-quickstart-guide.md index 81dd3732..dbfb0e12 100644 --- a/docs/guides/contributors-quickstart-guide.md +++ b/docs/guides/contributors-quickstart-guide.md @@ -7,7 +7,7 @@ To contribute to OpenMS: - 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. +For any questions, please [contact us](../contact-us.md). ## Technical documentation @@ -47,8 +47,7 @@ See the manual for coding style recommended by OpenMS: [Coding conventions](http ``` 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`). +Style testing can be enabled using `cmake` options. [clang-format](https://github.com/OpenMS/OpenMS/blob/develop/.clang-format) is used for formatting the cpp code. ### Commit messages @@ -68,7 +67,7 @@ Nightly tests: [CDASH](http://cdash.openms.de/index.php?project=OpenMS). Consider the following resources for further information: -- **Guidelines for adding new dependency libraries**: View the guidelines for [adding new dependency libraries](). +- **Guidelines for adding new dependency libraries**: View the guidelines for [adding new dependency libraries](../additional-resources/developer-guidelines-for-addding-new-dependent-libraries.md). - **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/). diff --git a/docs/installations/build-openms-from-source.md b/docs/installations/build-openms-from-source.md index 52298e1c..eba43512 100644 --- a/docs/installations/build-openms-from-source.md +++ b/docs/installations/build-openms-from-source.md @@ -1,4 +1,4 @@ -Build OpenMS From Source +Build OpenMS from Source ======================== To build OpenMS, please follow the build instructions for: diff --git a/docs/installations/installation-on-gnu-linux.md b/docs/installations/installation-on-gnu-linux.md index f81dbfd3..14f3b943 100644 --- a/docs/installations/installation-on-gnu-linux.md +++ b/docs/installations/installation-on-gnu-linux.md @@ -5,7 +5,7 @@ Installation on GNU/Linux Use conda or bioconda to install OpenMS. -1. Follow the instructions to [install conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/macos.html). +1. Follow the instructions to [install conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/linux.html). 2. Install OpenMS using conda: `conda install -c openms openms` 3. Other OpenMS packages can be installed using: @@ -15,12 +15,27 @@ Use conda or bioconda to install OpenMS. conda install -c openms libopenms ``` +```{tab} openms +openms contains OpenMS C++ Tools. +``` + +```{tab} libopenms +libopenms is the C++ library required for the OpenMS C++ Tools to work. +``` + +```{tab} pyopenms +pyopenms is the python package that allows to use algorithms from libopenms in Python. +``` + +```{tab} openms-thirdparty +openms-thirdparty are external tools that are wrapped in OpenMS with adapters. This is required to use the adapters in +the openms package. +``` + To install using bioconda: ``` conda install -c bioconda openms -conda install -c bioconda/label/cf201901 openms -conda install -c bioconda openms-tools conda install -c bioconda libopenms conda install -c bioconda openms-thirdparty ``` @@ -85,8 +100,12 @@ Some thirdparty software used via adapter tools in OpenMS might also require an Make sure you have [Docker installed](https://docs.docker.com/engine/install/). -Our Docker support is constantly updated. Images can be obtained via [OpenMS Dockerhub](https://hub.docker.com/u/openms) -and [BioContainers Registeries](https://biocontainers.pro/registry). +Our Docker support is constantly updated. Images can be obtained via [ghcr.io](https://ghcr.io). + +1. [openms-executables](https://ghcr.io/openms/openms-executables:latest) +2. [openms-library](https://ghcr.io/openms/openms-library:latest) + +Or via [BioContainers Registeries](https://biocontainers.pro/registry). 1. [BioContainers libopenms](https://biocontainers.pro/tools/libopenms) 2. [BioContainers openms](https://biocontainers.pro/tools/openms) diff --git a/docs/tutorials/TOPP/hotkeys-table.md b/docs/tutorials/TOPP/hotkeys-table.md index 600e7f51..bb322e63 100644 --- a/docs/tutorials/TOPP/hotkeys-table.md +++ b/docs/tutorials/TOPP/hotkeys-table.md @@ -43,7 +43,7 @@ TOPPView Hotkeys | CTRL + ALT + - | 2D draw mode: decrease maximum point size (for raw peak scaling) | ```{tip} -kbd>Home on macOS keyboards is also Fn + ArrowLeft. End on macOSX keyboards is also Fn + ArrowRight. +Home on macOS keyboards is also Fn + ArrowLeft. End on macOSX keyboards is also Fn + ArrowRight. ``` ## Annotations in 1D view