annotate Sphinx/source/faq/crash.rst @ 241:f277d18e8d71

link to debug plugins
author Sebastien Jodogne <s.jodogne@gmail.com>
date Mon, 29 Apr 2019 10:36:13 +0200
parents ea82efa0885a
children 26b0d7ece4af
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
239
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
1 .. _crash:
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
2
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
3 Crash analysis
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
4 ==============
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
5
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
6 If you experience a crash within Orthanc (or one of its plugins), that
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
7 the troubleshooting sections (cf. :ref:`here <troubleshooting>` and
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
8 :ref:`here <dicom>`) do not help, and that you can't provide a robust
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
9 way to reproduce your issue by third-party developers, you'll have to
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
10 analyze the backtrace of Orthanc.
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
11
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
12
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
13 .. _segfault-plugin:
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
14
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
15 Generating a segmentation fault for test purpose
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
16 ------------------------------------------------
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
17
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
18 .. highlight:: cpp
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
19
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
20 Here is the source code of a minimal C++ :ref:`plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
21 <creating-plugins>` that can be used to simulate a segmentation fault
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
22 within Orthanc::
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
23
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
24 #include <orthanc/OrthancCPlugin.h>
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
25
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
26 extern "C"
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
27 {
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
28 int32_t OrthancPluginInitialize(OrthancPluginContext* context)
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
29 {
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
30 // Let's trigger a segmentation fault by writing to NULL
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
31 intptr_t *p = NULL;
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
32 *p = 42;
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
33 return OrthancPluginErrorCode_Success;
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
34 }
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
35
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
36 void OrthancPluginFinalize()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
37 {
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
38 }
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
39
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
40 const char* OrthancPluginGetName()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
41 {
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
42 return "crash";
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
43 }
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
44
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
45 const char* OrthancPluginGetVersion()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
46 {
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
47 return "0.0";
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
48 }
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
49 }
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
50
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
51 As soon as Orthanc will try and load this plugin, it will crash. This
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
52 gives you the opportunity to learn how to debug Orthanc on your very
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
53 specific platform.
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
54
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
55
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
56 Any system
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
57 ----------
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
58
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
59 First :ref:`compile Orthanc by yourself <compiling>`, in debug mode by
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
60 setting ``-DCMAKE_BUILD_TYPE=Debug`` when invoking CMake.
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
61
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
62 Then, learn how to use the debugger that is best suited to your
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
63 platform (e.g. Microsoft Visual Studio, gdb or Xcode).
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
64
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
65
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
66 GNU/Linux system using gdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
67 --------------------------
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
68
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
69 .. highlight:: bash
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
70
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
71 The Orthanc project provides precompiled debug binaries that can be
241
f277d18e8d71 link to debug plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 240
diff changeset
72 run on almost any recent GNU/Linux system (generated thanks to the
f277d18e8d71 link to debug plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 240
diff changeset
73 `LSB - Linux Standard Base SDK
f277d18e8d71 link to debug plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 240
diff changeset
74 <https://en.wikipedia.org/wiki/Linux_Standard_Base>`__). This allows
f277d18e8d71 link to debug plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 240
diff changeset
75 to generate a backtrace (the famous "core dumped" message) that can be
f277d18e8d71 link to debug plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 240
diff changeset
76 analyzed by any developer of Orthanc. Assuming that the :ref:`plugin
f277d18e8d71 link to debug plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 240
diff changeset
77 above <segfault-plugin>` is available as the ``crash.cpp`` file, here
f277d18e8d71 link to debug plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 240
diff changeset
78 is a sample debug session::
239
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
79
240
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 239
diff changeset
80 $ wget http://lsb.orthanc-server.com/orthanc/debug/1.5.6/Orthanc
239
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
81 $ chmod +x ./Orthanc
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
82 $ gcc -fPIC -shared ./crash.cpp -I ~/orthanc/Plugins/Include -o crash.so
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
83 $ ulimit -c unlimited
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
84 $ echo '{ "Plugins" : ["crash.so"] }' > Configuration.json
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
85 $ rm -f core ; ./Orthanc Configuration.json
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
86 W0427 15:43:24.215783 main.cpp:1436] Orthanc version: 1.5.6
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
87 W0427 15:43:24.215910 main.cpp:1279] Performance warning: Non-release build, runtime debug assertions are turned on
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
88 W0427 15:43:24.217585 OrthancConfiguration.cpp:61] Reading the configuration from: "Configuration.json"
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
89 W0427 15:43:24.254733 main.cpp:700] Loading plugin(s) from: crash.so
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
90 W0427 15:43:24.254866 PluginsManager.cpp:269] Registering plugin 'crash' (version 0.0)
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
91 Segmentation fault (core dumped)
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
92
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
93
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
94 .. highlight:: text
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
95
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
96 This session creates a file called ``core`` in the current working
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
97 directory. You can analyze it by running ``gdb`` as follows::
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
98
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
99 $ gdb -c ./core ./Orthanc
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
100 (gdb) bt
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
101 #0 0x00007f7b1aa3d739 in OrthancPluginInitialize () from crash.so
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
102 #1 0x00000000008632f0 in Orthanc::CallInitialize (plugin=..., context=...)
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
103 at /home/jodogne/BuildBotWorker/Orthanc_1_5_6_-_LSB_Debug/build/Plugins/Engine/PluginsManager.cpp:98
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
104 #2 0x0000000000864496 in Orthanc::PluginsManager::RegisterPlugin (this=0x4314f90, path="crash.so")
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
105 at /home/jodogne/BuildBotWorker/Orthanc_1_5_6_-_LSB_Debug/build/Plugins/Engine/PluginsManager.cpp:272
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
106 ...
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
107
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
108 If you are unable to analyze such a backtrace by yourself, feel free
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
109 to post your ``core`` file on the `Orthanc forum
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
110 <https://groups.google.com/forum/#!forum/orthanc-users>`__.
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
111
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
112 **Important:** The Orthanc developers will only be able to analyze the
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
113 ``core`` files generated by our own precompiled binaries!
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
114
241
f277d18e8d71 link to debug plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 240
diff changeset
115 **Plugins:** Besides the Orthanc core, debug binaries of the official
f277d18e8d71 link to debug plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 240
diff changeset
116 plugins precompiled using the LSB are also available at the following
f277d18e8d71 link to debug plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 240
diff changeset
117 locations:
239
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
118
241
f277d18e8d71 link to debug plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 240
diff changeset
119 * `Orthanc core <http://lsb.orthanc-server.com/orthanc/debug/>`__
f277d18e8d71 link to debug plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 240
diff changeset
120 * `DICOMweb plugin <http://lsb.orthanc-server.com/plugin-dicom-web/debug/>`__
f277d18e8d71 link to debug plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 240
diff changeset
121 * `MySQL plugin <http://lsb.orthanc-server.com/plugin-mysql/debug/>`__
f277d18e8d71 link to debug plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 240
diff changeset
122 * `Orthanc Web viewer <http://lsb.orthanc-server.com/plugin-webviewer/debug/>`__
f277d18e8d71 link to debug plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 240
diff changeset
123 * `PostgreSQL plugin <http://lsb.orthanc-server.com/plugin-postgresql/debug/>`__
f277d18e8d71 link to debug plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 240
diff changeset
124 * `Transfers accelerator plugin <http://lsb.orthanc-server.com/plugin-transfers/debug/>`__
f277d18e8d71 link to debug plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 240
diff changeset
125 * `Whole-slide imaging <http://lsb.orthanc-server.com/whole-slide-imaging/debug/>`__
f277d18e8d71 link to debug plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 240
diff changeset
126
239
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
127
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
128 Docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
129 ------
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
130
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
131 To be written.