--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Sphinx/source/faq/crash.rst	Sat Apr 27 15:52:49 2019 +0200
@@ -0,0 +1,120 @@
+.. _crash:
+
+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.
+
+
+.. _segfault-plugin:
+
+Generating a segmentation fault for test purpose
+------------------------------------------------
+
+.. highlight:: cpp
+
+Here is the source code of a minimal C++ :ref:`plugin
+<creating-plugins>` that can be used to simulate a segmentation fault
+within Orthanc::
+
+  #include <orthanc/OrthancCPlugin.h>
+  
+  extern "C"
+  {
+    int32_t OrthancPluginInitialize(OrthancPluginContext* context)
+    {
+      // Let's trigger a segmentation fault by writing to NULL
+      intptr_t *p = NULL;
+      *p = 42;
+      return OrthancPluginErrorCode_Success;
+    }
+
+    void OrthancPluginFinalize()
+    {
+    }
+
+    const char* OrthancPluginGetName()
+    {
+      return "crash";
+    }
+
+    const char* OrthancPluginGetVersion()
+    {
+      return "0.0";
+    }
+  }
+
+As soon as Orthanc will try and load this plugin, it will crash. This
+gives you the opportunity to learn how to debug Orthanc on your very
+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
+--------------------------
+
+.. highlight:: bash
+
+The Orthanc project provides precompiled debug binaries that can be
+run on almost any recent GNU/Linux system. This allows to generate a
+backtrace (the famous "core dumped" message) that can be analyzed by
+any developer of Orthanc. Assuming that the :ref:`plugin above
+<segfault-plugin>` is available as the ``crash.cpp`` file, here is a
+sample debug session::
+
+  $ wget http://orthanc.osimis.io/lsb/orthanc-debug/releases/1.5.6/Orthanc
+  $ chmod +x ./Orthanc
+  $ gcc -fPIC -shared ./crash.cpp -I ~/orthanc/Plugins/Include -o crash.so
+  $ ulimit -c unlimited
+  $ echo '{ "Plugins" : ["crash.so"] }' > Configuration.json
+  $ rm -f core ; ./Orthanc Configuration.json
+  W0427 15:43:24.215783 main.cpp:1436] Orthanc version: 1.5.6
+  W0427 15:43:24.215910 main.cpp:1279] Performance warning: Non-release build, runtime debug assertions are turned on
+  W0427 15:43:24.217585 OrthancConfiguration.cpp:61] Reading the configuration from: "Configuration.json"
+  W0427 15:43:24.254733 main.cpp:700] Loading plugin(s) from: crash.so
+  W0427 15:43:24.254866 PluginsManager.cpp:269] Registering plugin 'crash' (version 0.0)
+  Segmentation fault (core dumped)
+
+
+.. highlight:: text
+
+This session creates a file called ``core`` in the current working
+directory.  You can analyze it by running ``gdb`` as follows::
+
+  $ gdb -c ./core ./Orthanc
+  (gdb) bt
+  #0  0x00007f7b1aa3d739 in OrthancPluginInitialize () from crash.so
+  #1  0x00000000008632f0 in Orthanc::CallInitialize (plugin=..., context=...)
+  at /home/jodogne/BuildBotWorker/Orthanc_1_5_6_-_LSB_Debug/build/Plugins/Engine/PluginsManager.cpp:98
+  #2  0x0000000000864496 in Orthanc::PluginsManager::RegisterPlugin (this=0x4314f90, path="crash.so")
+  at /home/jodogne/BuildBotWorker/Orthanc_1_5_6_-_LSB_Debug/build/Plugins/Engine/PluginsManager.cpp:272
+  ...
+
+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!
+
+NB: In the future, debug binaries will be provided for the official
+plugins (work in progress).
+
+
+Docker
+------
+
+To be written.