diff Sphinx/source/faq/debugging.rst @ 244:26b0d7ece4af

debugging
author Sebastien Jodogne <s.jodogne@gmail.com>
date Mon, 13 May 2019 15:29:09 +0200
parents
children b742e44113d4
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Sphinx/source/faq/debugging.rst	Mon May 13 15:29:09 2019 +0200
@@ -0,0 +1,85 @@
+.. _debugging:
+
+Debugging Orthanc
+=================
+
+If you experience an error within Orthanc (or one of its plugins), that
+the troubleshooting sections (cf. :ref:`here <troubleshooting>` and
+:ref:`here <dicom>`) do not help, and that you can't provide a robust
+way to reproduce your issue by third-party developers, you'll have to
+analyze the backtrace of Orthanc.
+
+If you observe a **fatal crash** of Orthanc, where Orthanc stops
+abruptly (e.g. by creating a so-called "core dumped" or reporting an
+invalid memory access), which rarely occurs, please check the
+:ref:`dedicated section <crash>`). The present FAQ entry is rather
+about C++ exceptions that are thrown by Orthanc, typically as a
+consequence of invalid inputs, and that result in an error message
+reported by Orthanc (not in a crash), and for which the :ref:`log
+files in verbose mode <log>` do not provide meaningful information.
+
+**Important reminder:** Most issues with Orthanc can be solved by
+carefully looking at the :ref:`Orthanc logs <log>` in ``--verbose``
+mode!
+
+
+Any system
+----------
+
+First :ref:`compile Orthanc by yourself <compiling>`, in debug mode by
+setting ``-DCMAKE_BUILD_TYPE=Debug`` when invoking CMake.
+
+Then, learn how to use the debugger that is best suited to your
+platform (e.g. Microsoft Visual Studio, gdb or Xcode).
+
+
+GNU/Linux system using gdb
+--------------------------
+
+.. highlight:: bash
+
+The Orthanc project provides precompiled debug binaries that can be
+run on almost any recent GNU/Linux system (generated thanks to the
+`LSB - Linux Standard Base SDK
+<https://en.wikipedia.org/wiki/Linux_Standard_Base>`__). This allows
+to debug Orthanc without compiling from sources. Here is a sample
+debug session::
+
+  $ wget http://lsb.orthanc-server.com/orthanc/debug/1.5.6/Orthanc
+  $ chmod +x ./Orthanc
+  $ gdb ./Orthanc Configuration.json
+  (gdb) catch throw
+  Catchpoint 1 (throw)
+  (gdb) run
+  W0513 15:24:42.374349 main.cpp:1436] Orthanc version: 1.5.6
+  ---> Reproduce your error case <---
+  Thread 15 "Orthanc" hit Catchpoint 1 (exception thrown), 0x00007ffff6de68bd in __cxa_throw () from /usr/lib/x86_64-linux-gnu/libstdc++.so.6
+  (gdb) backtrace
+  #0  0x00007ffff6de68bd in __cxa_throw ()
+     from /usr/lib/x86_64-linux-gnu/libstdc++.so.6
+  ...
+
+If you are unable to analyze such a backtrace by yourself, feel free
+to post your ``core`` file on the `Orthanc forum
+<https://groups.google.com/forum/#!forum/orthanc-users>`__.
+
+**Important:** The Orthanc developers will only be able to analyze the
+``core`` files generated by our own precompiled binaries!
+
+**Plugins:** Besides the Orthanc core, debug binaries of the official
+plugins precompiled using the LSB are also available at the following
+locations:
+
+* `Orthanc core <http://lsb.orthanc-server.com/orthanc/debug/>`__
+* `DICOMweb plugin <http://lsb.orthanc-server.com/plugin-dicom-web/debug/>`__
+* `MySQL plugin <http://lsb.orthanc-server.com/plugin-mysql/debug/>`__
+* `Orthanc Web viewer <http://lsb.orthanc-server.com/plugin-webviewer/debug/>`__
+* `PostgreSQL plugin <http://lsb.orthanc-server.com/plugin-postgresql/debug/>`__
+* `Transfers accelerator plugin <http://lsb.orthanc-server.com/plugin-transfers/debug/>`__
+* `Whole-slide imaging <http://lsb.orthanc-server.com/whole-slide-imaging/debug/>`__
+  
+
+Docker
+------
+
+To be written.