# HG changeset patch
# User Sebastien Jodogne <s.jodogne@gmail.com>
# Date 1704303772 -3600
# Node ID b7835da597505a7d327b0aaec15eb430b8f52764
# Parent  23a54088d604cbb245b25ad223ec7c6fcba6f8b2
updated instructions for gdb/cgdb

diff -r 23a54088d604 -r b7835da59750 Sphinx/source/faq/crash.rst
--- a/Sphinx/source/faq/crash.rst	Wed Jan 03 17:56:00 2024 +0100
+++ b/Sphinx/source/faq/crash.rst	Wed Jan 03 18:42:52 2024 +0100
@@ -55,52 +55,58 @@
 
 .. 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
+The Orthanc project provides precompiled binaries with debug symbols
+for the mainline that can 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 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 https://lsb.orthanc-server.com/orthanc/debug/1.12.2/Orthanc
+  $ wget https://orthanc.uclouvain.be/downloads/linux-standard-base/orthanc/mainline-debug/Orthanc
   $ chmod +x ./Orthanc
-  $ gcc -fPIC -shared ./crash.cpp -I ~/orthanc/Plugins/Include -o crash.so
+  $ g++ -fPIC -shared ./crash.cpp -I ~/orthanc/OrthancServer/Plugins/Include -o crash.so
   $ ulimit -c unlimited
-  $ echo '{ "Plugins" : ["crash.so"] }' > Configuration.json
+  $ echo '{ "Plugins" : ["./crash.so"] }' > Configuration.json
   $ rm -f core ; ./Orthanc Configuration.json
-  W0427 15:43:24.215783 main.cpp:1436] Orthanc version: 1.12.2
-  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)
+  W0103 18:05:01.661466             MAIN main.cpp:2041] Orthanc version: mainline (20240103T170440)
+  W0103 18:05:01.661583             MAIN main.cpp:1775] Performance warning: Non-release build, runtime debug assertions are turned on
+  W0103 18:05:01.661800             MAIN OrthancConfiguration.cpp:57] Reading the configuration from: "Configuration.json"
+  W0103 18:05:01.864783             MAIN main.cpp:912] Loading plugin(s) from: ./crash.so
+  W0103 18:05:01.864883             MAIN PluginsManager.cpp:261] 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::
+directory. If you don't see this file, it probably means that your
+GNU/Linux distribution customizes the name of core files (this is for
+instance the case of Ubuntu 22.04 that sends core files to
+``apport``). You can temporarily disable this behavior by typing::
 
-  $ gdb -c ./core ./Orthanc
+  $ echo core | sudo tee /proc/sys/kernel/core_pattern
+
+
+You can then analyze the ``core`` file by running ``gdb`` as follows::
+
+  $ gdb -c ./core.424217 ./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
-  ...
+  #0  0x00007f5943308111 in OrthancPluginInitialize () from ./crash.so
+  #1  0x00000000005e1cbc in Orthanc::CallInitialize (plugin=..., context=...)
+      at /home/jodogne/BuildBotWorker/Orthanc_mainline_-_LSB_Debug/build/OrthancServer/Plugins/Engine/PluginsManager.cpp:87
+  #2  0x00000000005e2f14 in Orthanc::PluginsManager::RegisterPlugin (this=0x2edc220, path="./crash.so")
+      at /home/jodogne/BuildBotWorker/Orthanc_mainline_-_LSB_Debug/build/OrthancServer/Plugins/Engine/PluginsManager.cpp:264
 
 If you are unable to analyze such a backtrace by yourself, feel free
 to post your ``core`` file on the `Orthanc Users discussion forum
-<https://discourse.orthanc-server.org>`__.
+<https://discourse.orthanc-server.org>`__. Do not forget to indicate
+the content of
+`<https://orthanc.uclouvain.be/downloads/linux-standard-base/orthanc/mainline-debug/revision.txt>`__
+so that we can find the version of Orthanc that generated the core
+file.
+
 
 **Important:** The Orthanc developers will only be able to analyze the
 ``core`` files generated by our own precompiled binaries!
-
-
-Docker
-------
-
-To be written.
diff -r 23a54088d604 -r b7835da59750 Sphinx/source/faq/debugging.rst
--- a/Sphinx/source/faq/debugging.rst	Wed Jan 03 17:56:00 2024 +0100
+++ b/Sphinx/source/faq/debugging.rst	Wed Jan 03 18:42:52 2024 +0100
@@ -30,7 +30,7 @@
 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).
+platform (e.g. Microsoft Visual Studio, gdb, cgdb, or Xcode).
 
 
 GNU/Linux system using gdb
@@ -38,45 +38,65 @@
 
 .. 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
+The Orthanc project provides precompiled binaries with debug symbols
+for the mainline that can 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::
+debug session to analyze an error that comes from an invalid
+:ref:`configuration file <configuration>`::
 
-  $ wget https://lsb.orthanc-server.com/orthanc/debug/1.12.2/Orthanc
+  $ wget https://orthanc.uclouvain.be/downloads/linux-standard-base/orthanc/mainline-debug/Orthanc
+  $ echo 'nope' > invalid.json
   $ chmod +x ./Orthanc
-  $ gdb ./Orthanc Configuration.json
+  $ gdb --args ./Orthanc invalid.json
   (gdb) catch throw
   Catchpoint 1 (throw)
   (gdb) run
-  W0513 15:24:42.374349 main.cpp:1436] Orthanc version: 1.12.2
-  ---> 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
+  Starting program: /tmp/i/Orthanc invalid.json
+  [Thread debugging using libthread_db enabled]
+  Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".
+  W0103 18:25:01.540600             MAIN main.cpp:2041] Orthanc version: mainline (20240103T170440)
+  W0103 18:25:01.540636             MAIN main.cpp:1775] Performance warning: Non-release build, runtime debug assertions are turned on
+  W0103 18:25:01.540702             MAIN OrthancConfiguration.cpp:57] Reading the configuration from: "invalid.json"
+  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
+
+  Catchpoint 1 (exception thrown), 0x00007ffff7cae4a1 in __cxa_throw () from /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
-  ...
+  #0  0x00007ffff7cae4a1 in __cxa_throw () from /lib/x86_64-linux-gnu/libstdc++.so.6
+  #1  0x0000000000473745 in Orthanc::AddFileToConfiguration (target=..., path=...)
+      at /home/jodogne/BuildBotWorker/Orthanc_mainline_-_LSB_Debug/build/OrthancServer/Sources/OrthancConfiguration.cpp:72
+  #2  0x0000000000473e98 in Orthanc::ReadConfiguration (target=..., configurationFile=0x7fffffffe302 "invalid.json")
+      at /home/jodogne/BuildBotWorker/Orthanc_mainline_-_LSB_Debug/build/OrthancServer/Sources/OrthancConfiguration.cpp:149
+  [...]
 
 If you are unable to analyze such a backtrace by yourself, feel free
 to post your backtrace on the `Orthanc Users discussion forum
-<https://discourse.orthanc-server.org>`__.
+<https://discourse.orthanc-server.org>`__. Do not forget to indicate
+the content of
+`<https://orthanc.uclouvain.be/downloads/linux-standard-base/orthanc/mainline-debug/revision.txt>`__
+so that we can find the version of Orthanc that generated the core
+file.
 
-**Plugins:** Besides the Orthanc core, debug binaries of the official
-plugins precompiled using the LSB are also available at the following
-locations:
+If you want to read the source code of the backtrace, it is highly
+suggested to use ``cgdb`` with its ``set substitute-path`` command.
+First read the content of the `revision.txt file
+<https://orthanc.uclouvain.be/downloads/linux-standard-base/orthanc/mainline-debug/revision.txt>`__
+to identify the revision of Orthanc. Then, you can type::
 
-* `Orthanc core <https://lsb.orthanc-server.com/orthanc/debug/>`__
-* `DICOMweb plugin <https://lsb.orthanc-server.com/plugin-dicom-web/debug/>`__
-* `MySQL plugin <https://lsb.orthanc-server.com/plugin-mysql/debug/>`__
-* `Orthanc Web viewer <https://lsb.orthanc-server.com/plugin-webviewer/debug/>`__
-* `PostgreSQL plugin <https://lsb.orthanc-server.com/plugin-postgresql/debug/>`__
-* `Transfers accelerator plugin <https://lsb.orthanc-server.com/plugin-transfers/debug/>`__
-* `Whole-slide imaging <https://lsb.orthanc-server.com/whole-slide-imaging/debug/>`__
+  $ hg clone -r 723251b2b71e https://orthanc.uclouvain.be/hg/orthanc/
+  $ cgdb --args ./Orthanc invalid.json
+  (gdb) set substitute-path /home/jodogne/BuildBotWorker/Orthanc_mainline_-_LSB_Debug/build/ ./orthanc/
+  (gdb) catch throw
+  (gdb) run
+  (gdb) frame 2
+
   
+Plugins
+.......
 
-Docker
-------
+Besides the Orthanc core, debug LSB binaries are also available for
+most official plugins at the following location:
+`<https://orthanc.uclouvain.be/downloads/linux-standard-base/index.html>`__
 
-To be written.
+These binaries are identified as ``mainline-debug/``.