Mercurial > hg > orthanc-book
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 |
| rev | line source |
|---|---|
| 244 | 1 .. _debugging: |
| 2 | |
| 3 Debugging Orthanc | |
| 4 ================= | |
| 5 | |
| 6 If you experience an error within Orthanc (or one of its plugins), that | |
| 7 the troubleshooting sections (cf. :ref:`here <troubleshooting>` and | |
| 8 :ref:`here <dicom>`) do not help, and that you can't provide a robust | |
| 9 way to reproduce your issue by third-party developers, you'll have to | |
| 10 analyze the backtrace of Orthanc. | |
| 11 | |
| 12 If you observe a **fatal crash** of Orthanc, where Orthanc stops | |
| 13 abruptly (e.g. by creating a so-called "core dumped" or reporting an | |
| 14 invalid memory access), which rarely occurs, please check the | |
| 15 :ref:`dedicated section <crash>`). The present FAQ entry is rather | |
| 16 about C++ exceptions that are thrown by Orthanc, typically as a | |
| 17 consequence of invalid inputs, and that result in an error message | |
| 18 reported by Orthanc (not in a crash), and for which the :ref:`log | |
| 19 files in verbose mode <log>` do not provide meaningful information. | |
| 20 | |
| 21 **Important reminder:** Most issues with Orthanc can be solved by | |
| 541 | 22 carefully looking at the :ref:`Orthanc logs <log>` after starting |
| 23 Orthanc with the ``--verbose --trace-dicom`` command-line options! | |
| 244 | 24 |
| 25 | |
| 26 Any system | |
| 27 ---------- | |
| 28 | |
| 29 First :ref:`compile Orthanc by yourself <compiling>`, in debug mode by | |
| 30 setting ``-DCMAKE_BUILD_TYPE=Debug`` when invoking CMake. | |
| 31 | |
| 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 | 34 |
| 35 | |
| 36 GNU/Linux system using gdb | |
| 37 -------------------------- | |
| 38 | |
| 39 .. highlight:: bash | |
| 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 | 44 <https://en.wikipedia.org/wiki/Linux_Standard_Base>`__). This allows |
| 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 | 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 | 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 | 53 (gdb) catch throw |
| 54 Catchpoint 1 (throw) | |
| 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 | 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 | 72 |
| 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 | 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 | 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 | 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 | 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 | 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/``. |