Skip to content

Latest commit

 

History

History
209 lines (188 loc) · 13.4 KB

AGENTS.md

File metadata and controls

209 lines (188 loc) · 13.4 KB

OpenMS Agent Notes

This file summarizes repo-specific conventions and workflows for contributors and automated changes. It is intentionally concise; use the linked docs for full details.

Key docs in this repo/build

  • README.md, CONTRIBUTING.md, ARCHITECTURE.MD, CODE_OF_CONDUCT.md, PULL_REQUEST_TEMPLATE.md.
  • src/pyOpenMS/README.md, src/pyOpenMS/README_WRAPPING_NEW_CLASSES.
  • share/OpenMS/examples/external_code/README.md, src/tests/external/README.md.
  • dockerfiles/README.md, cmake/MacOSX/README.md, tools/jenkins/README.MD.
  • Doxygen (if built) in OpenMS-build/doc/html/ including index.html, developer_coding_conventions.html, developer_cpp_guide.html, developer_how_to_write_tests.html, howto_commit_messages.html, developer_faq.html, developer_tutorial.html, install_linux.html, install_mac.html, install_win.html, pyOpenMS.html.

Repo layout (high signal)

  • Default build directory: OpenMS-build/ (out-of-tree).
  • Core C++: src/openms/, src/openms_gui/, src/openswathalgo/, src/topp/.
  • Tests: src/tests/class_tests/openms/, src/tests/class_tests/openms_gui/, src/tests/topp/.
  • pyOpenMS: src/pyOpenMS/ with pxds/, addons/, pyopenms/, tests/.

Build and install (summary)

  • Out-of-tree build expected in OpenMS-build/; build in place for development (install prefixes are for system installs).
  • Use CMAKE_BUILD_TYPE=Debug for development to keep assertions/pre/post-conditions.
  • Dependencies via distro packages or the contrib tree; set OPENMS_CONTRIB_LIBS and CMAKE_PREFIX_PATH as needed (Qt, contrib).
  • pyOpenMS build deps: src/pyOpenMS/requirements_bld.txt; enable with -DPYOPENMS=ON and optional -DPY_NUM_THREADS/-DPY_NUM_MODULES.
  • Linux: package manager preferred; contrib is fallback; QT_QPA_PLATFORM=minimal can help for remote GUI runs.
  • macOS: Apple Clang (Xcode), Homebrew; remove older Qt versions if they interfere.
  • Windows: Visual Studio 2019+ (MSVC), CMake >= 3.24, 64-bit only, Visual Studio generator, avoid MinGW; keep build paths short.
  • Style checks: ENABLE_STYLE_TESTING=ON runs cpplint at src/tests/coding/cpplint.py.

Testing

  • Unit/class tests: src/tests/class_tests/<lib>/source/, add to executables.cmake; data in src/tests/class_tests/libs/data/ (prefix files with class name).
  • TOPP tests: add to src/tests/topp/CMakeLists.txt, data in src/tests/topp/.
  • GUI tests: src/tests/class_tests/openms_gui/source/ (Qt TestLib).
  • Build all/ALL_BUILD to include tests and FuzzyDiff (TOPP tests depend on it).
  • Use NEW_TMP_FILE for each output file in tests; avoid side effects in comparison macros.
  • Run with ctest, use -R for subset, -V/-VV for verbosity, -C for multi-config generators.
  • Use FuzzyDiff for numeric comparisons; keep test data small; use whitelist for unstable lines.
  • Test templates: tools/create_test.php (requires make xml).
  • START_SECTION macro pitfalls: wrap template methods with 2+ arguments in parentheses.
  • pyOpenMS tests: ctest -R pyopenms or pytest with PYTHONPATH=/path/to/OpenMS-build/pyOpenMS (run outside the source tree to avoid shadowing).

Coding conventions (Doxygen)

  • Indentation: 2 spaces, no tabs; Unix line endings.
  • Spacing: after keywords (if, for) and around binary operators.
  • Braces: opening/closing braces align; use braces even for single-line blocks (trivial one-liners may stay single-line).
  • File names: class name matches file name; one class per file; always pair .h with .cpp.
  • Templates: use _impl.h only when needed; .h must not include _impl.h.
  • Names: classes/types/namespaces in PascalCase; methods lowerCamel; variables snake_case; private/protected members end with _.
  • Enums and macros uppercase with underscores; avoid the preprocessor; prefer enum class.
  • Parameters: lower_case with underscores; document ranges/units.
  • File extensions: lowercase, except ML/XML and mzData.
  • Use OpenMS primitive types from OpenMS/CONCEPT/Types.h.
  • No using namespace or using std::... in headers; allowed in .cpp.
  • Follow Rule-of-0 or Rule-of-6.
  • Accessors: get/set pairs for protected/private members; no reference getters for primitive types.
  • Exceptions: derive from Exception::Base; throw with file/line/OPENMS_PRETTY_FUNCTION; catch by reference; document possible exceptions.
  • Doxygen: @brief + blank line + details; use @defgroup/@ingroup; use .doxygen files for free-standing docs; @todo includes assignee name.
  • Comments: at least ~5% of code, use // style, plain English describing the next few lines.
  • Each file preamble contains the $Maintainer:$ marker.
  • Formatting: use ./.clang-format in supporting IDEs.

C++ guide (OpenMS-specific)

  • OPENMS_DLLAPI on all non-template exported classes/structs/functions/vars; not on templates; include in friend operator declarations.
  • Use OpenMS logging macros and OpenMS::LogStream; avoid std::cout/err directly.
  • Use ProgressLogger in tools for progress reporting.
  • Avoid std::endl for performance; prefer \n.
  • Prefer OpenMS::String for numeric formatting and parsing (precision and speed).
  • Use Size/SignedSize for STL .size() values.
  • Avoid pointers; prefer references.
  • Prefer forward declarations in headers; include only base class headers, non-pointer members, and templates.

TOPP tool development

  • Add new tool source (e.g., src/topp/<Tool>.cpp) and register in src/topp/executables.cmake.
  • Register tool in src/openms/source/APPLICATIONS/ToolHandler.cpp to generate Doxygen help output.
  • Define parameters in registerOptionsAndFlags_(); read with getStringOption_ and related helpers.
  • Document the tool and add to doc/doxygen/public/TOPP.doxygen where applicable.
  • Add TOPP tests in src/tests/topp/CMakeLists.txt.

pyOpenMS wrapping

  • Autowrap reads .pxd in src/pyOpenMS/pxds/ and generates pyopenms/pyopenms.pyx -> pyopenms.cpp -> module.
  • Addons in src/pyOpenMS/addons/ inject Python-only methods (indent only; no cdef class).
  • Keep .pxd signatures in sync with C++ APIs; update or remove wrap-ignore when wrapping changes.
  • Always declare default and copy constructors in .pxd; use cimport, not Python import.
  • For non-inheriting classes use cdef cppclass ClassName: with no base.
  • Autowrap hints: wrap-ignore, wrap-as, wrap-iter-begin/end, wrap-instances, wrap-attach, wrap-upper-limit, wrap-inherits.
  • Avoid custom __init__ unless required; it overrides autowrap dispatchers.
  • Use snake_case for Python-facing names and DataFrame columns.
  • Do not add Python-only methods to .pxd; use addons or _dataframes.py wrappers.
  • DataFrame pattern: get_data_dict() in addon returns numpy arrays; get_df() in src/pyOpenMS/pyopenms/_dataframes.py wraps with pandas.
  • Type converters: implement in src/pyOpenMS/converters/special_autowrap_conversionproviders.py, register in src/pyOpenMS/converters/__init__.py.
  • Gotchas: autowrap returns Python strings; do not .decode(). Avoid cdef for autowrap string returns. Avoid cdef typed variables for autowrap return values inside def methods; use Python type checks. Keep addons minimal; avoid redundant aliases. # wrap-doc: indentation is strict.
  • Regenerate after addon changes: 
    rm OpenMS-build/pyOpenMS/.cpp_extension_generated
cmake --build OpenMS-build --target pyopenms -j4

Change-impact checklist (agent quick wins)

  • New C++ class: add .h/.cpp, Doxygen docs, class test, OPENMS_DLLAPI, register in CMake lists.
  • C++ API change: update .pxd/addons, pyOpenMS tests, and relevant docs; tag commits with API as needed.
  • New/changed TOPP tool: register in src/topp/executables.cmake and ToolHandler.cpp, add docs, add TOPP tests and data.
  • Parameter or I/O change: update tool docs/CTD, tests, and CHANGELOG; use PARAM/IO commit tags.
  • File format change: update FileHandler::NamesOfTypes[], schemas/validators, and tests.

Contribution workflow and commit messages

  • Development follows Gitflow; use forks and open PRs against develop.
  • Commit format: [TAG1,TAG2] short summary (<=120 chars, <=80 preferred), blank line, longer description, and Fixes #N/Closes #N when applicable.
  • Commit tags: NOP, DOC, COMMENT, API, INTERNAL, FEATURE, FIX, TEST, FORMAT, PARAM, IO, LOG, GUI, RESOURCE, BUILD.
  • PR checklist: update AUTHORS and CHANGELOG, run/extend tests, update pyOpenMS bindings when needed.
  • Minimize pushes on open PRs (CI is heavy).
  • Run tools/checker.php and/or ENABLE_STYLE_TESTING for local checks.

Debugging and profiling

  • Linux: use ldd to inspect shared libs; nm -C for symbols; perf/hotspot for profiling.
  • Windows: Dependency Walker or dumpbin /DEPENDENTS and dumpbin /EXPORTS.
  • Memory checks: AddressSanitizer or valgrind with tools/valgrind/openms_external.supp.

External projects and examples

  • Example external CMake project: share/OpenMS/examples/external_code/.
  • External test project: src/tests/external/.
  • Use the same compiler/generator as OpenMS; set OPENMS_CONTRIB_LIBS and OpenMS_DIR when configuring.

CI, packaging, and containers

  • CI runs in GitHub Actions; CDash collects nightly results.
  • Jenkins packaging uses tools/jenkins/os_compiler_matrix.tsv (edit only if needed).
  • PR commands/labels: /reformat, label NoJenkins, comment rebuild jenkins.
  • Container images: see dockerfiles/README.md and GHCR packages.
  • macOS code signing/notarization: see cmake/MacOSX/README.md.

Documentation links (external)

OpenMS docs

Doxygen developer pages (release/latest)

Developer workflow and contribution

Build/install guides

Coding and tooling

Testing and profiling tools

Packaging and containers