Difference between revisions of "Documentation/Nightly/Developers/Tutorials/Debug Instructions"

From Slicer Wiki
Jump to: navigation, search
Tag: 2017 source edit
(25 intermediate revisions by 5 users not shown)
Line 4: Line 4:
  
 
==Linux==
 
==Linux==
 +
 
===Analyze a segmentation fault===
 
===Analyze a segmentation fault===
 
  $ ulimit -c unlimited
 
  $ ulimit -c unlimited
Line 13: Line 14:
 
  ...
 
  ...
  
===GDB debug with launch arguments===
+
====With systemd====
The Slicer app launcher provides options to start other programs with the Slicer environment settings.  
+
In linux distros with systemd, coredumps are managed by the systemd daemon.
 +
And stored, in a compressed format (.lz4), in
 +
  /var/lib/systemd/coredump/core.SlicerApp-real.xxxx.lz4
  
*<code>--launch <executable> [<parameters>]</code>: executes an arbitrary program. For example, <code>Slicer --launch /usr/bin/gnome-terminal</code> starts gnome-terminal (then run GDB directly on SlicerQT-real)
+
It can happen that even with ulimit -c unlimited, the coredump files are still truncated.
*<code>--gdb</code>: runs GDB then executes SlicerQT-real from within the debugger environment.
+
You can check latest coredumps, and the correspoding PID with:
 +
  coredumpctl list
 +
  Thu 2018-05-24 16:37:46 EDT  22544  1000  1000  11 missing  /usr/lib/firefox/firefox
 +
  Fri 2018-05-25 15:50:52 EDT  14721  1000  1000  6 truncated /path/Slicer-build/bin/SlicerApp-real
 +
  Mon 2018-05-28 11:35:43 EDT  17249  1000  1000  6 present  /path/Slicer-build/bin/SlicerApp-real
  
===GDB debug by attaching to running process [RECOMMENDED] ===
+
You can modify systemd coredump to increase the default max file size in:
 +
  /etc/systemd/coredump.conf
 +
  [Coredump]
 +
  #Storage=external
 +
  #Compress=yes
 +
  ProcessSizeMax=8G
 +
  ExternalSizeMax=8G
 +
  JournalSizeMax=6G
 +
  #MaxUse=
 +
  #KeepFree=
  
1) Running Slicer with the following command line argument will allow you to easily obtain the associated PID:
+
After that change, make Slicer crash again, and the core file will be present, instead of truncated.
  
$ ./Slicer --attach-process
+
You can launch gdb with a coredump file with the command:
 +
  coredumpctl gdb $PID
 +
If no $PID is provided, the latest coredump is used. PID can be retrieved using `coredumpctl list`.
  
This will bring up a window with the <code>PID</code> before loading any modules, which is also helpful for debugging the loading process.
+
To decompress the coredump file to use with other IDE or ddd, change the coredump.conf Compress option, or use:
 +
  coredumpctl dump $PID > /tmp/corefile
  
2) Then, you can attach the process to <code>gdb</code> using the following command:
+
===GDB debug by attaching to running process [RECOMMENDED]===
  
$ gdb --pid $PIDABOVE
+
<ol start="1" style="list-style-type: decimal;">
  
3) Finally type the following gdb command
+
<li>Starting with Ubuntu 10.10, ptracing of non-child processes by non-root users as been disabled -ie. only a process which is a parent of another process can ptrace it for normal users.
 +
  <ol style="list-style-type:none; border-left:thick solid red; padding-left:1em;"> 
 +
    <li>
 +
      <p>You can temporarily disable this restriction by:</p>
 +
      <pre>$ echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope</pre>
 +
    </li>
 +
    <li>
 +
      <p>To permanently allow it to edit <code>/etc/sysctl.d/10-ptrace.conf</code> and change the line:</p>
 +
      <pre>kernel.yama.ptrace_scope = 1</pre>
 +
      <p>to read:</p>
 +
      <pre>kernel.yama.ptrace_scope = 0</pre>
 +
    </li>
 +
    <li>For more details: http://askubuntu.com/questions/41629/after-upgrade-gdb-wont-attach-to-process</li>
 +
  </ol>
 +
</li>
  
(gdb) continue
+
<li>
 +
  <p>Running Slicer with the following command line argument will allow you to easily obtain the associated PID:</p>
 +
  <pre>$ ./Slicer --attach-process</pre>
 +
  <p>This will bring up a window with the <code>PID</code> before loading any modules, which is also helpful for debugging the loading process.</p>
 +
</li>
  
If not using the <code>--attach-process</code>, the <code>PID</code> could be obtain using the following command:
+
<li>
 +
  <p>Then, you can attach the process to <code>gdb</code> using the following command:</p>
 +
  <pre>$ gdb --pid $PIDABOVE</pre>
 +
</li>
  
$ ps -Afww | grep SlicerApp-real
+
<li>
 +
  <p>Finally type the following gdb command</p>
 +
  <pre>(gdb) continue</pre>
 +
  <p>If not using the <code>--attach-process</code>, the <code>PID</code> could be obtain using the following command:</p>
 +
  <pre>$ ps -Afww | grep SlicerApp-real</pre>
 +
</li>
  
 +
</ol>
  
==== Ubuntu 10.10 and above  - How to enable ptracing ====
+
===GDB debug with launch arguments===
In Ubuntu 10.10, Ubuntu introduced a patch to disallow ptracing of non-child processes by non-root users -ie. only a process which is a parent of another process can ptrace it for normal users.
+
The Slicer app launcher provides options to start other programs with the Slicer environment settings.  
You can temporarily disable this restriction by:
 
$ echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
 
To permanently allow it to edit /etc/sysctl.d/10-ptrace.conf and change the line:
 
*<code>kernel.yama.ptrace_scope = 1</code>
 
to read:
 
*<code>kernel.yama.ptrace_scope = 0</code>
 
  
See http://askubuntu.com/questions/41629/after-upgrade-gdb-wont-attach-to-process
+
*<code>--launch <executable> [<parameters>]</code>: executes an arbitrary program. For example, <code>Slicer --launch /usr/bin/gnome-terminal</code> starts gnome-terminal (then run GDB directly on SlicerQT-real)
 +
*<code>--gdb</code>: runs GDB then executes SlicerQT-real from within the debugger environment.
  
 
===GDB debug by using exec-wrapper===
 
===GDB debug by using exec-wrapper===
Line 55: Line 96:
  
 
The general idea of the wrapper is to set all of the appropriate environment variables as they would be set by the app launcher. From SlicerLauncherSettings:
 
The general idea of the wrapper is to set all of the appropriate environment variables as they would be set by the app launcher. From SlicerLauncherSettings:
 +
 
*[LibraryPath] contents should be in LD_LIBRARY_PATH
 
*[LibraryPath] contents should be in LD_LIBRARY_PATH
 
*[Paths] contents should be in PATH
 
*[Paths] contents should be in PATH
Line 79: Line 121:
 
[[{{FULLPAGENAME}}/CodeLite|Linux debugging with CodeLite IDE]]
 
[[{{FULLPAGENAME}}/CodeLite|Linux debugging with CodeLite IDE]]
  
== Windows ==
+
===Using QtCreator===
 +
 
 +
See [[Documentation/{{documentation/version}}/Developers/Tutorials/QtCreator|QtCreator page]] for instructions.
 +
 
 +
==Windows==
 +
 
 +
===Using Visual Studio===
  
For VisualStudio it's also possible to run the IDE with the correct environment to debug slicer.
+
For VisualStudio it's also possible to run the IDE with the correct environment to debug Slicer.
  
* Start VisualStudio by using the launcher. Run: Slicer.exe --VisualStudio  
+
*Start VisualStudio by using the launcher. Run: <code>Slicer.exe --VisualStudioProject</code>
* When Visual Studio is started, open the ...\Slicer-build\Slicer.sln solution
+
**If you use non-supported VisualStudio version (e.g., VS2010, VS2012, ...) then you may have to start the executable of the VisualStudio IDE manually with the --launch option, for example: <code>Slicer.exe --launch "c:\Program Files (x86)\Microsoft Visual Studio 11.0\Common7\IDE\devenv.exe"</code>
* Set the SlicerApp-real as current project
+
**If you just want to start VisualStudio with the launcher (and then load project file manually), run: <code>Slicer.exe --VisualStudio</code>
* Run Slicer in debug mode by the Start Debugging command (F5).
+
**To debug an extension that builds third-party DLLs, also specify <code>--launcher-additional-settings</code> option. Also, while you can launch debugger using Slicer's solution file, it is usually more convenient to load your extension's solution file (because your extension solution is smaller and most likely you want to have that solution open anyway for making changes in your code). For example, you can launch Visual Studio to debug your extension like this:  <code>.\S4D\Slicer-build\Slicer.exe --VisualStudio --launcher-no-splash --launcher-additional-settings ./SlicerRT_D/inner-build/AdditionalLauncherSettings.ini c:\d\_Extensions\SlicerRT_D\inner-build\SlicerRT.sln</code>
 +
<!--
 +
* When Visual Studio is started, open the <code>...\Slicer-build\Slicer.sln</code> solution (note that this is not the first level <code>...\Slicer_sln</code> )
 +
-->
 +
*Expand App-Slicer and set the <b>SlicerApp</b> as StartUp project (right-click on SlicerApp project and select "Set as StartUp Project", make sure to select <b>SlicerApp</b> and <b>NOT qSlicerApp</b>)
 +
**To debug in an extension's solution: set ALL_BUILD project as StartUp project and in project settings, set Debugging / Command field to the full path of SlicerApp-real.exe - something like <code>...\Slicer-build\bin\Debug\SlicerApp-real.exe</code>
 +
*Run Slicer in debug mode by Start Debugging command (in Debug menu).
  
 
Note that because CMake re-creates the solution file from within the build process, Visual Studio will sometimes need to stop and reload the project, requiring manual button pressing on your part (just press Yes or OK whenever you are asked).  To avoid this, you can use a script to complete the build process and then re-start the Visual Studio.
 
Note that because CMake re-creates the solution file from within the build process, Visual Studio will sometimes need to stop and reload the project, requiring manual button pressing on your part (just press Yes or OK whenever you are asked).  To avoid this, you can use a script to complete the build process and then re-start the Visual Studio.
  
=== Experimental: Using Cygwin to re-build ===
+
===Using QtCreator===
 +
See [[Documentation/{{documentation/version}}/Developers/Tutorials/QtCreator|QtCreator page]] for instructions.
 +
 
 +
===Using shell scripts for building/re-building Slicer===
 +
 
 +
====Using batch (.bat) files====
 +
 
 +
Copy-paste the content below into a file called ''BuildSlicer.bat'' and run it to build or re-build Slicer. Check and if necessary update the first few lines with the actual location of source code and tools on your computer.
 +
 
 +
<pre>
 +
set SLICER_SOURCE_DIR="c:\D\S4"
 +
set SLICER_BIN_DIR="c:\D\S4R"
 +
set SLICER_QMAKE_EXE="c:\D\Support\qt-4.8.7-64-vs2013-rel\bin\qmake.exe"
 +
set CMAKE_EXE="C:\Program Files (x86)\CMake\bin\cmake.exe"
 +
set CTEST_EXE="C:\Program Files (x86)\CMake\bin\ctest.exe"
 +
 
 +
mkdir %SLICER_BIN_DIR%
 +
cd /d %SLICER_BIN_DIR%
 +
%CMAKE_EXE% %SLICER_SOURCE_DIR% -G "Visual Studio 12 2013 Win64" -DQT_QMAKE_EXECUTABLE:PATH=%SLICER_QMAKE_EXE% -DSlicer_USE_PYTHONQT_WITH_OPENSSL:BOOL=OFF -DSlicer_USE_SimpleITK:BOOL=OFF
 +
%CTEST_EXE% -D Experimental
 +
</pre>
 +
 
 +
====Experimental: Using Cygwin====
 
If you use cygwin, you can create simple shell scripts, for example in /usr/local/bin, which these several steps at once when run from the Slicer4-superbuild directory:
 
If you use cygwin, you can create simple shell scripts, for example in /usr/local/bin, which these several steps at once when run from the Slicer4-superbuild directory:
  
* ''s4build'' (slicer4 build)
+
*''s4build'' (slicer4 build)
 +
 
 
  (cd Slicer-build; cmake.exe -VV --debug-output . && ./Slicer.exe --VisualStudio Slicer.sln /out buildlog.txt /build)
 
  (cd Slicer-build; cmake.exe -VV --debug-output . && ./Slicer.exe --VisualStudio Slicer.sln /out buildlog.txt /build)
 
  (cd Slicer-build; ./Slicer.exe --VisualStudio Slicer.sln)
 
  (cd Slicer-build; ./Slicer.exe --VisualStudio Slicer.sln)
* ''s4sbuild'' (slicer4 super build)
+
 
 +
*''s4sbuild'' (slicer4 super build)
 +
 
 
  (cmake.exe -VV --debug-output . && ./Slicer-build/Slicer.exe --VisualStudio Slicer.sln /out buildlog.txt /build)
 
  (cmake.exe -VV --debug-output . && ./Slicer-build/Slicer.exe --VisualStudio Slicer.sln /out buildlog.txt /build)
 
  (cd Slicer-build; ./Slicer.exe --VisualStudio Slicer.sln)
 
  (cd Slicer-build; ./Slicer.exe --VisualStudio Slicer.sln)
Line 106: Line 185:
 
Note the buildlog.txt files for checking if anything went wrong.
 
Note the buildlog.txt files for checking if anything went wrong.
  
== Mac (Xcode) ==
+
==Mac (Xcode)==
 +
 
 +
===Using Xcode===
  
 
[[image:Xcode-scheme-Screen Shot 2012-10-05 at 10.13.30 AM.png|thumb|right|200px]]
 
[[image:Xcode-scheme-Screen Shot 2012-10-05 at 10.13.30 AM.png|thumb|right|200px]]
Line 114: Line 195:
 
''Note: You need to set up a dummy project in Xcode just to enable some of the options.''  This means that Xcode will create a MacOS code template, but you won't use it directly (instead you will point to the code you build with cmake/make).
 
''Note: You need to set up a dummy project in Xcode just to enable some of the options.''  This means that Xcode will create a MacOS code template, but you won't use it directly (instead you will point to the code you build with cmake/make).
  
=== Attaching to a running process ===
+
====Attaching to a running process====
  
 
You can use the Attach to Process option in the Xcode Product menu for debugging.  This will allow you to get browsable stack traces for crashes.
 
You can use the Attach to Process option in the Xcode Product menu for debugging.  This will allow you to get browsable stack traces for crashes.
  
 
Steps:
 
Steps:
# Start Slicer
 
# Start Xcode
 
# Use the Product->Attach to Process... menu
 
  
===Setting Breakpoints===
+
#Start Slicer
 +
#Start Xcode
 +
#Use the Product->Attach to Process... menu
 +
 
 +
====Setting Breakpoints====
 
To set a breakpoint in code that is not crashing, you can set it via the command line interface.  For the lldb debugger, first attach to the process and break the program.  Then at the (lldb) prompt, stop at a method as follows:
 
To set a breakpoint in code that is not crashing, you can set it via the command line interface.  For the lldb debugger, first attach to the process and break the program.  Then at the (lldb) prompt, stop at a method as follows:
  
Line 132: Line 214:
 
Alternatively, you can use the Product->Debug->Create a Symbolic Breakpoint... option.  This is generally preferable to the lldb level debugging, since it shows up in the Breakpoints pane and can be toggled/deleted with the GUI.
 
Alternatively, you can use the Product->Debug->Create a Symbolic Breakpoint... option.  This is generally preferable to the lldb level debugging, since it shows up in the Breakpoints pane and can be toggled/deleted with the GUI.
  
===Debugging the Startup Process===
+
====Debugging the Startup Process====
  
 
To debug startup issues you can set up a 'Scheme' and select the Slicer.app in your Slicer-build directory (see screen shot).  You can set up multiple schemes with different command line arguments and executables (for example to debug tests).
 
To debug startup issues you can set up a 'Scheme' and select the Slicer.app in your Slicer-build directory (see screen shot).  You can set up multiple schemes with different command line arguments and executables (for example to debug tests).
  
 
Since you are using a dummy project but want to debug the slicer application, you need to do the following:
 
Since you are using a dummy project but want to debug the slicer application, you need to do the following:
# Start Xcode and open dummy project
+
 
# Pick Product->Edit Scheme...
+
#Start Xcode and open dummy project
# Select the Run section
+
#Pick Product->Edit Scheme...
# Select the Info tab
+
#Select the Run section
# Pick Slicer.app as the Executable
+
#Select the Info tab
# Click OK
+
#Pick Slicer.app as the Executable
# Now the Run button will start Slicer for debugging
+
#Click OK
 +
#Now the Run button will start Slicer for debugging
  
 
Note that you can create multiple schemes, each various command line options to pass to slicer so you can easily get back to a debugging environment.
 
Note that you can create multiple schemes, each various command line options to pass to slicer so you can easily get back to a debugging environment.
  
Also on the mac, the [http://en.wikipedia.org/wiki/Instruments_%28application%29 Instruments] tool is very useful for profiling.
+
===Using QtCreator===
 +
See [[Documentation/{{documentation/version}}/Developers/Tutorials/QtCreator|QtCreator page]] for instructions.
 +
 
 +
===Profiling===
 +
The [http://en.wikipedia.org/wiki/Instruments_%28application%29 Instruments] tool is very useful for profiling.
  
 
==Debugging a Test==
 
==Debugging a Test==
 
Once VisualStudio is open with the Slicer environment loaded, it is possible to run and debug tests.
 
Once VisualStudio is open with the Slicer environment loaded, it is possible to run and debug tests.
 
To run all tests, build the ''RUN_TESTS'' project.
 
To run all tests, build the ''RUN_TESTS'' project.
 +
 
#To debug a test, find its project:
 
#To debug a test, find its project:
 
##Libs/MRML/Core tests are in the ''MRMLCoreCxxTests'' project
 
##Libs/MRML/Core tests are in the ''MRMLCoreCxxTests'' project
##CLI tests are in ''CLI_NAMETest'' project (e.g. ThresholdScalarVolumeTest)  
+
##CLI tests are in ''CLI_NAMETest'' project (e.g. ThresholdScalarVolumeTest)
##Loadable module tests are in ''qSlicerLOADABLE_NAMECxxTests'' project (e.g. qSlicerVolumeRenderingCxxTests)  
+
##Loadable module tests are in ''qSlicerLOADABLE_NAMECxxTests'' project (e.g. qSlicerVolumeRenderingCxxTests)
##Module logic tests are in ''MODULE_NAMELogicCxxTests'' project (e.g. VolumeRenderingLogicCxxTests)  
+
##Module logic tests are in ''MODULE_NAMELogicCxxTests'' project (e.g. VolumeRenderingLogicCxxTests)
 
##Module widgets tests are in ''MODULE_NAMEWidgetsCxxTests'' project (e.g. VolumesWidgetsCxxTests)
 
##Module widgets tests are in ''MODULE_NAMEWidgetsCxxTests'' project (e.g. VolumesWidgetsCxxTests)
 
#Go to the project debugging properties (right click -> Properties, then Configuration Properties/Debugging)
 
#Go to the project debugging properties (right click -> Properties, then Configuration Properties/Debugging)
 
#In ''Command Arguments'', type the name of the test (e.g. <code>vtkMRMLSceneImportTest</code> for project MRMLCoreCxxTests)
 
#In ''Command Arguments'', type the name of the test (e.g. <code>vtkMRMLSceneImportTest</code> for project MRMLCoreCxxTests)
# If the test takes argument(s), enter the argument(s) after the test name in ''Command Arguments'' (e.g. <code>vtkMRMLSceneImportTest C:\Path\To\Slicer4\Libs\MRML\Core\Testing\vol_and_cube.mrml</code>)
+
#If the test takes argument(s), enter the argument(s) after the test name in ''Command Arguments'' (e.g. <code>vtkMRMLSceneImportTest C:\Path\To\Slicer4\Libs\MRML\Core\Testing\vol_and_cube.mrml</code>)
## You can see what arguments are passed by the dashboards by looking at the test details in [http://slicer.cdash.org/index.php?project=Slicer4 CDash].
+
##You can see what arguments are passed by the dashboards by looking at the test details in [http://slicer.cdash.org/index.php?project=Slicer4 CDash].
## Most VTK and Qt tests support the <code>-I</code> argument, it allows the test to be run in "interactive" mode. It doesn't exit at the end of the test.
+
##Most VTK and Qt tests support the <code>-I</code> argument, it allows the test to be run in "interactive" mode. It doesn't exit at the end of the test.
# Make the project ''Set As StartUp Project''
+
#Make the project ''Set As StartUp Project''
# ''Start Debugging (F5)''
+
#''Start Debugging (F5)''
 +
 
 +
==Debugging Python scripts==
 +
 
 +
See [[Documentation/{{documentation/version}}/Developers/Python_scripting#How_can_I_use_a_visual_debugger_for_step-by-step_debugging|Python scripting page]].
 +
 
 +
{{:Documentation/{{documentation/version}}/Developers/FAQ/Debugging|Debugging}}

Revision as of 03:36, 18 March 2020

Home < Documentation < Nightly < Developers < Tutorials < Debug Instructions


For the latest Slicer documentation, visit the read-the-docs.


Background

The executable Slicer application Slicer-Superbuild/Slicer-build/Slicer (or Slicer.exe) is the launcher of the real application binary Slicer-Superbuild/Slicer-build/bin/SlicerApp-real.

Linux

Analyze a segmentation fault

$ ulimit -c unlimited
$ ./Slicer
... make it crash
$ ./Slicer --gdb ./bin/SlicerApp-real
(gdb) core core
(gdb) backtrace
...

With systemd

In linux distros with systemd, coredumps are managed by the systemd daemon. And stored, in a compressed format (.lz4), in

 /var/lib/systemd/coredump/core.SlicerApp-real.xxxx.lz4

It can happen that even with ulimit -c unlimited, the coredump files are still truncated. You can check latest coredumps, and the correspoding PID with:

 coredumpctl list
 Thu 2018-05-24 16:37:46 EDT   22544  1000  1000  11 missing   /usr/lib/firefox/firefox
 Fri 2018-05-25 15:50:52 EDT   14721  1000  1000   6 truncated /path/Slicer-build/bin/SlicerApp-real
 Mon 2018-05-28 11:35:43 EDT   17249  1000  1000   6 present   /path/Slicer-build/bin/SlicerApp-real

You can modify systemd coredump to increase the default max file size in:

 /etc/systemd/coredump.conf
 [Coredump]
 #Storage=external
 #Compress=yes
 ProcessSizeMax=8G
 ExternalSizeMax=8G
 JournalSizeMax=6G
 #MaxUse=
 #KeepFree=

After that change, make Slicer crash again, and the core file will be present, instead of truncated.

You can launch gdb with a coredump file with the command:

 coredumpctl gdb $PID

If no $PID is provided, the latest coredump is used. PID can be retrieved using `coredumpctl list`.

To decompress the coredump file to use with other IDE or ddd, change the coredump.conf Compress option, or use:

 coredumpctl dump $PID > /tmp/corefile

GDB debug by attaching to running process [RECOMMENDED]

  1. Starting with Ubuntu 10.10, ptracing of non-child processes by non-root users as been disabled -ie. only a process which is a parent of another process can ptrace it for normal users.
    1. You can temporarily disable this restriction by:

      $ echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
    2. To permanently allow it to edit /etc/sysctl.d/10-ptrace.conf and change the line:

      kernel.yama.ptrace_scope = 1

      to read:

      kernel.yama.ptrace_scope = 0
    3. For more details: http://askubuntu.com/questions/41629/after-upgrade-gdb-wont-attach-to-process
  2. Running Slicer with the following command line argument will allow you to easily obtain the associated PID:

    $ ./Slicer --attach-process

    This will bring up a window with the PID before loading any modules, which is also helpful for debugging the loading process.

  3. Then, you can attach the process to gdb using the following command:

    $ gdb --pid $PIDABOVE
  4. Finally type the following gdb command

    (gdb) continue

    If not using the --attach-process, the PID could be obtain using the following command:

    $ ps -Afww | grep SlicerApp-real

GDB debug with launch arguments

The Slicer app launcher provides options to start other programs with the Slicer environment settings.

  • --launch <executable> [<parameters>]: executes an arbitrary program. For example, Slicer --launch /usr/bin/gnome-terminal starts gnome-terminal (then run GDB directly on SlicerQT-real)
  • --gdb: runs GDB then executes SlicerQT-real from within the debugger environment.

GDB debug by using exec-wrapper

An alternative approach is to use a wrapper script to emulate the functionality of the app launcher. This will allow you to use gdb or a gdb-controlling program such as an IDE, in order to interactively debug directly from GDB without attaching.

The general idea of the wrapper is to set all of the appropriate environment variables as they would be set by the app launcher. From SlicerLauncherSettings:

  • [LibraryPath] contents should be in LD_LIBRARY_PATH
  • [Paths] contents should be in PATH
  • [EnvironmentVariables] should each be set

See this example script

Now, start gdb and do the following:

(gdb) set exec-wrapper ./WrapSlicer4 
(gdb) exec-file ./bin/SlicerQT-real
(gdb) run

Since VTK and ITK include many multithreaded filters, by default you will see lots of messages like the following from gdb during rendering and processing:

[New Thread 0x7fff8378f700 (LWP 20510)]
[Thread 0x7fff8b0aa700 (LWP 20506) exited]

These can be turned off with this command:

set print thread-events off

GDB debug in CodeLite IDE

Linux debugging with CodeLite IDE

Using QtCreator

See QtCreator page for instructions.

Windows

Using Visual Studio

For VisualStudio it's also possible to run the IDE with the correct environment to debug Slicer.

  • Start VisualStudio by using the launcher. Run: Slicer.exe --VisualStudioProject
    • If you use non-supported VisualStudio version (e.g., VS2010, VS2012, ...) then you may have to start the executable of the VisualStudio IDE manually with the --launch option, for example: Slicer.exe --launch "c:\Program Files (x86)\Microsoft Visual Studio 11.0\Common7\IDE\devenv.exe"
    • If you just want to start VisualStudio with the launcher (and then load project file manually), run: Slicer.exe --VisualStudio
    • To debug an extension that builds third-party DLLs, also specify --launcher-additional-settings option. Also, while you can launch debugger using Slicer's solution file, it is usually more convenient to load your extension's solution file (because your extension solution is smaller and most likely you want to have that solution open anyway for making changes in your code). For example, you can launch Visual Studio to debug your extension like this: .\S4D\Slicer-build\Slicer.exe --VisualStudio --launcher-no-splash --launcher-additional-settings ./SlicerRT_D/inner-build/AdditionalLauncherSettings.ini c:\d\_Extensions\SlicerRT_D\inner-build\SlicerRT.sln
  • Expand App-Slicer and set the SlicerApp as StartUp project (right-click on SlicerApp project and select "Set as StartUp Project", make sure to select SlicerApp and NOT qSlicerApp)
    • To debug in an extension's solution: set ALL_BUILD project as StartUp project and in project settings, set Debugging / Command field to the full path of SlicerApp-real.exe - something like ...\Slicer-build\bin\Debug\SlicerApp-real.exe
  • Run Slicer in debug mode by Start Debugging command (in Debug menu).

Note that because CMake re-creates the solution file from within the build process, Visual Studio will sometimes need to stop and reload the project, requiring manual button pressing on your part (just press Yes or OK whenever you are asked). To avoid this, you can use a script to complete the build process and then re-start the Visual Studio.

Using QtCreator

See QtCreator page for instructions.

Using shell scripts for building/re-building Slicer

Using batch (.bat) files

Copy-paste the content below into a file called BuildSlicer.bat and run it to build or re-build Slicer. Check and if necessary update the first few lines with the actual location of source code and tools on your computer.

set SLICER_SOURCE_DIR="c:\D\S4"
set SLICER_BIN_DIR="c:\D\S4R"
set SLICER_QMAKE_EXE="c:\D\Support\qt-4.8.7-64-vs2013-rel\bin\qmake.exe"
set CMAKE_EXE="C:\Program Files (x86)\CMake\bin\cmake.exe"
set CTEST_EXE="C:\Program Files (x86)\CMake\bin\ctest.exe"

mkdir %SLICER_BIN_DIR%
cd /d %SLICER_BIN_DIR%
%CMAKE_EXE% %SLICER_SOURCE_DIR% -G "Visual Studio 12 2013 Win64" -DQT_QMAKE_EXECUTABLE:PATH=%SLICER_QMAKE_EXE% -DSlicer_USE_PYTHONQT_WITH_OPENSSL:BOOL=OFF -DSlicer_USE_SimpleITK:BOOL=OFF
%CTEST_EXE% -D Experimental

Experimental: Using Cygwin

If you use cygwin, you can create simple shell scripts, for example in /usr/local/bin, which these several steps at once when run from the Slicer4-superbuild directory:

  • s4build (slicer4 build)
(cd Slicer-build; cmake.exe -VV --debug-output . && ./Slicer.exe --VisualStudio Slicer.sln /out buildlog.txt /build)
(cd Slicer-build; ./Slicer.exe --VisualStudio Slicer.sln)
  • s4sbuild (slicer4 super build)
(cmake.exe -VV --debug-output . && ./Slicer-build/Slicer.exe --VisualStudio Slicer.sln /out buildlog.txt /build)
(cd Slicer-build; ./Slicer.exe --VisualStudio Slicer.sln)

The s4build command re-runs cmake and then runs the build of Slicer only. When this completes, it launches visual studio with slicer loaded for debugging.

s4sbuild is similar, but it runs the superbuild process so that all the dependency libraries are updated. This takes longer, but is sometimes needed when there has been a change to CTK or other tools.

Note the buildlog.txt files for checking if anything went wrong.

Mac (Xcode)

Using Xcode

Xcode-scheme-Screen Shot 2012-10-05 at 10.13.30 AM.png

As of slicer 4.2, we do not support building using Xcode, however if you build slicer using traditional unix Makefiles you can still debug using the powerful source debugging features of Xcode.

Note: You need to set up a dummy project in Xcode just to enable some of the options. This means that Xcode will create a MacOS code template, but you won't use it directly (instead you will point to the code you build with cmake/make).

Attaching to a running process

You can use the Attach to Process option in the Xcode Product menu for debugging. This will allow you to get browsable stack traces for crashes.

Steps:

  1. Start Slicer
  2. Start Xcode
  3. Use the Product->Attach to Process... menu

Setting Breakpoints

To set a breakpoint in code that is not crashing, you can set it via the command line interface. For the lldb debugger, first attach to the process and break the program. Then at the (lldb) prompt, stop at a method as follows:

breakpoint set -M vtkMRMLScene::Clear

then you can single step and/or set other breakpoints in that file.

Alternatively, you can use the Product->Debug->Create a Symbolic Breakpoint... option. This is generally preferable to the lldb level debugging, since it shows up in the Breakpoints pane and can be toggled/deleted with the GUI.

Debugging the Startup Process

To debug startup issues you can set up a 'Scheme' and select the Slicer.app in your Slicer-build directory (see screen shot). You can set up multiple schemes with different command line arguments and executables (for example to debug tests).

Since you are using a dummy project but want to debug the slicer application, you need to do the following:

  1. Start Xcode and open dummy project
  2. Pick Product->Edit Scheme...
  3. Select the Run section
  4. Select the Info tab
  5. Pick Slicer.app as the Executable
  6. Click OK
  7. Now the Run button will start Slicer for debugging

Note that you can create multiple schemes, each various command line options to pass to slicer so you can easily get back to a debugging environment.

Using QtCreator

See QtCreator page for instructions.

Profiling

The Instruments tool is very useful for profiling.

Debugging a Test

Once VisualStudio is open with the Slicer environment loaded, it is possible to run and debug tests. To run all tests, build the RUN_TESTS project.

  1. To debug a test, find its project:
    1. Libs/MRML/Core tests are in the MRMLCoreCxxTests project
    2. CLI tests are in CLI_NAMETest project (e.g. ThresholdScalarVolumeTest)
    3. Loadable module tests are in qSlicerLOADABLE_NAMECxxTests project (e.g. qSlicerVolumeRenderingCxxTests)
    4. Module logic tests are in MODULE_NAMELogicCxxTests project (e.g. VolumeRenderingLogicCxxTests)
    5. Module widgets tests are in MODULE_NAMEWidgetsCxxTests project (e.g. VolumesWidgetsCxxTests)
  2. Go to the project debugging properties (right click -> Properties, then Configuration Properties/Debugging)
  3. In Command Arguments, type the name of the test (e.g. vtkMRMLSceneImportTest for project MRMLCoreCxxTests)
  4. If the test takes argument(s), enter the argument(s) after the test name in Command Arguments (e.g. vtkMRMLSceneImportTest C:\Path\To\Slicer4\Libs\MRML\Core\Testing\vol_and_cube.mrml)
    1. You can see what arguments are passed by the dashboards by looking at the test details in CDash.
    2. Most VTK and Qt tests support the -I argument, it allows the test to be run in "interactive" mode. It doesn't exit at the end of the test.
  5. Make the project Set As StartUp Project
  6. Start Debugging (F5)

Debugging Python scripts

See Python scripting page.


Developer FAQ: Debugging

How to print QString using GDB ?

See http://silmor.de/qtstuff.printqstring.php

More troubleshooting questions ?

See Troubleshooting