# HG changeset patch
# User Sebastien Jodogne <s.jodogne@gmail.com>
# Date 1557754149 -7200
# Node ID 26b0d7ece4af28cdc1ccf76d625b954e11a324a0
# Parent  57ecb27d1851382171224075d8a8d2b312c66336
debugging

diff -r 57ecb27d1851 -r 26b0d7ece4af Sphinx/source/faq.rst
--- a/Sphinx/source/faq.rst	Fri May 10 12:01:40 2019 +0200
+++ b/Sphinx/source/faq.rst	Mon May 13 15:29:09 2019 +0200
@@ -20,6 +20,7 @@
    faq/series-completion.rst
    faq/proprietary.rst
    faq/security.rst
+   faq/debugging.rst
 
 Features supported by Orthanc
 -----------------------------
diff -r 57ecb27d1851 -r 26b0d7ece4af Sphinx/source/faq/crash.rst
--- a/Sphinx/source/faq/crash.rst	Fri May 10 12:01:40 2019 +0200
+++ b/Sphinx/source/faq/crash.rst	Mon May 13 15:29:09 2019 +0200
@@ -3,11 +3,8 @@
 Crash analysis
 ==============
 
-If you experience a crash 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.
+Orthanc crashes very rarely. You are most likely looking for the FAQ
+entry about :ref:`debugging Orthanc <debugging>`.
 
 
 .. _segfault-plugin:
@@ -53,16 +50,6 @@
 specific platform.
 
 
-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
 --------------------------
 
@@ -112,18 +99,6 @@
 **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
 ------
diff -r 57ecb27d1851 -r 26b0d7ece4af Sphinx/source/faq/debugging.rst
--- /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.