annotate Sphinx/source/faq/debugging.rst @ 1113:a588960a72e5 default tip

spelling
author Alain Mazy <am@orthanc.team>
date Mon, 28 Oct 2024 09:23:08 +0100
parents b7835da59750
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
244
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
1 .. _debugging:
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
2
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
3 Debugging Orthanc
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
4 =================
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
5
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
6 If you experience an error within Orthanc (or one of its plugins), that
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
7 the troubleshooting sections (cf. :ref:`here <troubleshooting>` and
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
8 :ref:`here <dicom>`) do not help, and that you can't provide a robust
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
9 way to reproduce your issue by third-party developers, you'll have to
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
10 analyze the backtrace of Orthanc.
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
11
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
12 If you observe a **fatal crash** of Orthanc, where Orthanc stops
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
13 abruptly (e.g. by creating a so-called "core dumped" or reporting an
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
14 invalid memory access), which rarely occurs, please check the
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
15 :ref:`dedicated section <crash>`). The present FAQ entry is rather
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
16 about C++ exceptions that are thrown by Orthanc, typically as a
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
17 consequence of invalid inputs, and that result in an error message
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
18 reported by Orthanc (not in a crash), and for which the :ref:`log
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
19 files in verbose mode <log>` do not provide meaningful information.
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
20
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
21 **Important reminder:** Most issues with Orthanc can be solved by
541
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 528
diff changeset
22 carefully looking at the :ref:`Orthanc logs <log>` after starting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 528
diff changeset
23 Orthanc with the ``--verbose --trace-dicom`` command-line options!
244
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
24
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
25
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
26 Any system
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
27 ----------
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
28
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
29 First :ref:`compile Orthanc by yourself <compiling>`, in debug mode by
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
30 setting ``-DCMAKE_BUILD_TYPE=Debug`` when invoking CMake.
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
31
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
32 Then, learn how to use the debugger that is best suited to your
1009
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
33 platform (e.g. Microsoft Visual Studio, gdb, cgdb, or Xcode).
244
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
34
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
35
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
36 GNU/Linux system using gdb
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
37 --------------------------
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
38
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
39 .. highlight:: bash
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
40
1009
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
41 The Orthanc project provides precompiled binaries with debug symbols
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
42 for the mainline that can run on almost any recent GNU/Linux system
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
43 (generated thanks to the `LSB - Linux Standard Base SDK
244
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
44 <https://en.wikipedia.org/wiki/Linux_Standard_Base>`__). This allows
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
45 to debug Orthanc without compiling from sources. Here is a sample
1009
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
46 debug session to analyze an error that comes from an invalid
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
47 :ref:`configuration file <configuration>`::
244
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
48
1009
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
49 $ wget https://orthanc.uclouvain.be/downloads/linux-standard-base/orthanc/mainline-debug/Orthanc
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
50 $ echo 'nope' > invalid.json
244
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
51 $ chmod +x ./Orthanc
1009
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
52 $ gdb --args ./Orthanc invalid.json
244
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
53 (gdb) catch throw
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
54 Catchpoint 1 (throw)
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
55 (gdb) run
1009
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
56 Starting program: /tmp/i/Orthanc invalid.json
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
57 [Thread debugging using libthread_db enabled]
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
58 Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
59 W0103 18:25:01.540600 MAIN main.cpp:2041] Orthanc version: mainline (20240103T170440)
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
60 W0103 18:25:01.540636 MAIN main.cpp:1775] Performance warning: Non-release build, runtime debug assertions are turned on
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
61 W0103 18:25:01.540702 MAIN OrthancConfiguration.cpp:57] Reading the configuration from: "invalid.json"
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
62 E0103 18:25:01.540823 MAIN OrthancException.cpp:61] Cannot parse a JSON document: The configuration file does not follow the JSON syntax: invalid.json
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
63
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
64 Catchpoint 1 (exception thrown), 0x00007ffff7cae4a1 in __cxa_throw () from /lib/x86_64-linux-gnu/libstdc++.so.6
244
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
65 (gdb) backtrace
1009
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
66 #0 0x00007ffff7cae4a1 in __cxa_throw () from /lib/x86_64-linux-gnu/libstdc++.so.6
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
67 #1 0x0000000000473745 in Orthanc::AddFileToConfiguration (target=..., path=...)
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
68 at /home/jodogne/BuildBotWorker/Orthanc_mainline_-_LSB_Debug/build/OrthancServer/Sources/OrthancConfiguration.cpp:72
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
69 #2 0x0000000000473e98 in Orthanc::ReadConfiguration (target=..., configurationFile=0x7fffffffe302 "invalid.json")
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
70 at /home/jodogne/BuildBotWorker/Orthanc_mainline_-_LSB_Debug/build/OrthancServer/Sources/OrthancConfiguration.cpp:149
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
71 [...]
244
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
72
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
73 If you are unable to analyze such a backtrace by yourself, feel free
984
46e2941b57dd replace link to google users group by link to discourse
Alain Mazy <am@osimis.io>
parents: 963
diff changeset
74 to post your backtrace on the `Orthanc Users discussion forum
1009
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
75 <https://discourse.orthanc-server.org>`__. Do not forget to indicate
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
76 the content of
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
77 `<https://orthanc.uclouvain.be/downloads/linux-standard-base/orthanc/mainline-debug/revision.txt>`__
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
78 so that we can find the version of Orthanc that generated the core
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
79 file.
244
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
80
1009
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
81 If you want to read the source code of the backtrace, it is highly
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
82 suggested to use ``cgdb`` with its ``set substitute-path`` command.
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
83 First read the content of the `revision.txt file
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
84 <https://orthanc.uclouvain.be/downloads/linux-standard-base/orthanc/mainline-debug/revision.txt>`__
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
85 to identify the revision of Orthanc. Then, you can type::
244
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
86
1009
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
87 $ hg clone -r 723251b2b71e https://orthanc.uclouvain.be/hg/orthanc/
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
88 $ cgdb --args ./Orthanc invalid.json
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
89 (gdb) set substitute-path /home/jodogne/BuildBotWorker/Orthanc_mainline_-_LSB_Debug/build/ ./orthanc/
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
90 (gdb) catch throw
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
91 (gdb) run
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
92 (gdb) frame 2
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
93
244
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
94
1009
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
95 Plugins
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
96 .......
244
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
97
1009
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
98 Besides the Orthanc core, debug LSB binaries are also available for
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
99 most official plugins at the following location:
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
100 `<https://orthanc.uclouvain.be/downloads/linux-standard-base/index.html>`__
244
26b0d7ece4af debugging
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
101
1009
b7835da59750 updated instructions for gdb/cgdb
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1000
diff changeset
102 These binaries are identified as ``mainline-debug/``.