Difference between revisions of "Debugger Setup"

From Lazarus wiki
Jump to navigationJump to search
 
(35 intermediate revisions by 11 users not shown)
Line 1: Line 1:
 +
{{Debugger Setup}}
 
__TOC__  
 
__TOC__  
= Configure the IDE =
 
  
In order to be able to debug any of your projects, you need to make sure a the IDE is correctly configured.
 
  
This settings do not usually change. You need to make them only once after you installed Lazarus, or if you changed/updated your installation
+
== Configure the IDE ==
  
;Open the Lazarus option dialog:
+
=== Updating from an older IDE ===
[[image:Dbg_setup_options1.png]]
 
  
The image shows, where to find the option dialog in the Lazarus 0.9.31 and up. In previous versions the entry is in the "Environment" menu.
+
Older versions of Lazarus were only providing the GdbMI backend. It is highly recommended to update to Fp-Debugger or LLDB+FpDebug as indicated for your OS below.
  
 +
Please note that many other wiki pages may be outdated and still refer only to GDB.
  
[[image:Dbg_setup_options2.png]]
+
=== Choosing the correct debugger backend ===
  
* Make sure, the option "Gnu debugger (GDB)" is selected.
+
The Lazarus IDE provides several debuggers (backends). The page [[Debugger_Status|Status of the debugger backends]] provides an overview.
* The path to the gdb.exe may differ.
 
** On unix based systems it may be something like "/usr/bin/gdb"
 
** On windows it should be in a folder called "mingw\bin\" in the directory in which Lazarus is installed.
 
  
= Project Options =
+
The list below indicates which backend is recommended for your environment.
 +
 
 +
 
 +
{| class="wikitable"  width="100%" style="text-align:center"
 +
! class="partial" | Operating System
 +
! class="unknown" | Hardware
 +
! class="working" | Recommended<br/>debugger backend
 +
! class="working" | Recommended<br/>debug info
 +
! class="unknown" | Notes
 +
 
 +
 
 +
|----
 +
| class="partial" style="text-align:left" | Windows 32/64bit
 +
| class="unknown" | Intel/AMD <br/> i386 or x86_64
 +
| class="working" | Fp-Debugger
 +
| class="working" | DWARF-3
 +
| class="unknown" | Includes cross debugging of a 32bit app on a 64bit system
 +
 
 +
|----
 +
| class="partial" style="text-align:left" | Windows 32bit <br/><div style="font-size:0.7em">Cross 64bit</div>
 +
| class="unknown" | Intel/AMD <br/> x86_64
 +
| class="working" | GdbMi
 +
| class="working" | DWARF-2 with sets
 +
| class="unknown" | <u>'''Only'''</u>  '''cross debugging''' of a 64bit app on a 32bit system
 +
 
 +
|----
 +
| class="partial" style="text-align:left" | Windows
 +
| class="unknown" | ARM / AArch64 / other
 +
| class="working" | GdbMi
 +
| class="working" | DWARF-2 with sets
 +
| class="unknown" | You may also try "GdbMI+FpDebug"
 +
 
 +
|----
 +
| class="partial" style="text-align:left" | Linux
 +
| class="unknown" | Intel/AMD <br/> i386 or x86_64
 +
| class="working" | Fp-Debugger
 +
| class="working" | DWARF-3
 +
| class="unknown" | If RTL or packages have debug info, ensure it is the exact same type as for the project
 +
 
 +
|----
 +
| class="partial" style="text-align:left" | Linux
 +
| class="unknown" | ARM / AArch64 / other
 +
| class="working" | GdbMi
 +
| class="working" | DWARF-2 with sets
 +
| class="unknown" | You may also try "GdbMI+FpDebug"
 +
 
 +
|----
 +
| class="partial" style="text-align:left" | Mac
 +
| class="unknown" | Intel/AMD x86_64 <br/> AArch64 (e.g. M1)
 +
| class="working" | LLDB+FpDebug
 +
| class="working" | DWARF-3
 +
| class="unknown" |
 +
 
 +
|----
 +
| class="partial" style="text-align:left" | Embedded AVR
 +
| class="unknown" |
 +
| class="working" | FpDebug-avr package
 +
| class="working" | DWARF-2 or 3
 +
| class="unknown" | Requires gdb server
 +
 
 +
|----
 +
| class="partial" style="text-align:left" | Remote
 +
| class="unknown" | Any supported by GDB
 +
| class="working" | Gdb-Server
 +
| class="working" | DWARF-2 with sets
 +
| class="unknown" | Debugging on a different PC or VM
 +
 
 +
|----
 +
| class="partial" style="text-align:left" | Other
 +
| class="unknown" | Any supported by GDB
 +
| class="working" | GdbMi
 +
| class="working" | DWARF-2 with sets
 +
| class="unknown" |
 +
 
 +
|----
 +
| class="partial" style="text-align:left" | Any OS<br/>Debug with <b>STDIN/STDOUT redirect</b><br/><div style="font-size:0.7em">(via "Run Parameters" command line: >file < file)</div>
 +
| class="unknown" | Any supported by GDB
 +
| class="working" | GdbMi
 +
| class="working" | DWARF-2 with sets
 +
| class="unknown" |
 +
 
 +
|}
 +
 
 +
=== Setting up the debugger backend for the IDE ===
 +
 
 +
The following settings should be made once, after you installed Lazarus. They are often already set by default.
 +
 
 +
;The settings can be found under:
 +
<center><u>Tools > Options > Debugger > Debugger Backend</u></center>
 +
 
 +
<center>[[image:Lazarus_menu_options.png]]
 +
The image shows where to find the option dialog. On Mac the dialog is under "Preferences"
 +
</center>
 +
<br clear=all>
 +
 
 +
[[Image:lazarus_dbg_backend_fpdebug.png|right]]
 +
<div style="min-width:20%; display:table;">
 +
* Select the correct backend on top of the page
 +
* The Fp-Debugger does not require a path.
 +
* If you have an LLDB or Gdb(MI) based debugger you must set the path to the gdb or lldb exe under "Debugger type and path"
 +
** On Linux/Unix/Mac systems it may be something like "/usr/bin/gdb" or "/usr/bin/lldb"
 +
** On Windows it should be in a folder called "mingw\bin\" under the directory in which Lazarus is installed.
 +
 
 +
* On [[Debugger_Status|Status of the debugger backends]] you find a list of all backends with details on further settings.
 +
** For the GdbMI debugger under Lazarus 2.0 and up, enable the option "FixIncorrectStepOver" in the property grid.
 +
 
 +
</div>
 +
<br clear=all>
 +
 
 +
The backend can also be set on a per project config. For details see [[IDE_Window:_Project_Options_-_Debugger_Backend]]
 +
 
 +
== Project Options ==
 +
 
 +
[[image:Dbg_setup_project1.png|right]]
 +
<div style="min-width:20%; display:table;">
  
 
In order to debug your project, you need to tell the IDE to compile it in a special way, which provides additional information required by the debugger.
 
In order to debug your project, you need to tell the IDE to compile it in a special way, which provides additional information required by the debugger.
  
Please note: This will considerably increase the size of your executable ([[Lazarus_Faq#Why_are_the_generated_binaries_so_big.3F |See FAQ]]). If you want to build a release version of your software you should switch those settings off (see also [[IDE_Window:_Compiler_Options/de#Build_modes |Build Modes]])
+
The required settings are made in the "Project Options" dialog:
 +
 
 +
 
 +
* Please note: This will considerably increase the size of your executable ([[Lazarus_Faq#Why_are_the_generated_binaries_so_big.3F |See FAQ]]). If you want to build a release version of your software you should switch those settings off (see also [[IDE_Window:_Compiler_Options#Build_modes |Build Modes]])
 +
 
 +
</div>
 +
<br clear=all>
 +
 
 +
 
 +
[[image:lazarus_projectopts_dbg.png|right]]
 +
<div style="min-width:20%; display:table;">
 +
* You must enable "Generate Debug Info for GDB"
 +
* You must enable "Run uses the debugger (disable for release mode)"
 +
* You should set "Type of debug info" as recommended for your PC.
 +
** If you set this to a non supported type, the IDE will prompt you for a correct setting when you try to start the debugger.
 +
** '''Automatic''': Lets fpc choose. Can not be used with all backends.
 +
** '''Stabs''': Old and outdated. Supported by GDB only (maybe LLDB **without** FpDebug). Should not be used
 +
** '''Dwarf 2''': Minimal setting. Can not display watches for "set of". Issues with detecting PChar vs AnsiString. Should not be used
 +
** '''Dwarf 2 with sets''': GDB friendly. Issues with detecting PChar vs AnsiString
 +
** '''Dwarf 3''': Best setting for FpDebug.
 +
** None of them can currently display "property" with getter function.
 +
 
 +
----
 +
 
 +
* You should **not** enable "Use external debug symbols"<br/>(It is a recommendation not to use this)
 +
* You **must** **not** enable "Strip symbols from executable"
 +
 
 +
----
 +
 
 +
You can use the "Build modes". The "..." button brings of a dialog to create "release and debug mode". In this case you should still check the "Type of debug info".
 +
 
 +
</div>
 +
<br clear=all>
 +
 
 +
 
 +
[[image:Dbg_setup_project4.png|right]]
 +
<div style="min-width:20%; display:table;">
 +
** Use optimization "Level 0" ("Level 1" may be used, but in some cases may cause issues) <br>
 +
** Do **not** use "Link Smart"
 +
 
 +
</div>
 +
<br clear=all>
 +
 
 +
== GDB / LLDB Version ==
 +
 
 +
GDB 7.5 requires Lazarus 1.4 or higher.
  
The required settings can be made in the "Project Options" dialog:
+
GDB 7.7.1 seems to work well with Lazarus 1.2.4.
<table><tr><td> [[image:Dbg_setup_project1.png]] </td><td> [[image:Dbg_setup_project2.png]] </td></tr></table>
 
  
* You must enable the "Generate Debug Info for GDB"
+
On macOS: '''lldb''' is part of the Apple developer tools
** On Windows/Linux 32 bit it is highly recommended to use "Dwarf" <br>[[image:Dbg_setup_project3.png]]
 
* You must <b>not</b> use any of the following
 
** "Strip Symbols"
 
** "Link Smart"
 
** Any optimization other than "Level 1" (or "Level 0") <br>[[image:Dbg_setup_project4.png]]
 
  
= See also =
+
== See also ==
* [[IDE Window: Debugger Options]]
+
* IDE Options / Configuration
* [[GDB Debugger Tips]]
+
*;Lazarus 2.0.x (and before): [[IDE Window: Debugger Options]]
 +
*;Lazarus 2.2 (and up): [[IDE_Window:_DebuggerGeneralOptionsFrame|Debugger General Options]] and [[IDE_Window:_DebuggerClassOptionsFrame|Debugger Backend Options]]
 +
* Project Option / Command line args, Environment, and launcher app: [[IDE Window: Run parameters|Run -> Run Parameters]]
 +
* The FAQ for the default "GNU Debugger" in Lazarus: [[GDB Debugger Tips]]
 +
* Alternative debuggers in Lazarus: [[Debugger Status]] Includes a feature map and default-key-strokes
  
=External links=
 
* [http://www.youtube.com/watch?v=cf4G06k2YL8 Setup Video Tutorial]
 
  
 
[[Category:Debugging]]
 
[[Category:Debugging]]
 
[[Category:Lazarus]]
 
[[Category:Lazarus]]

Latest revision as of 11:19, 13 December 2023

English (en) español (es) français (fr) русский (ru)


Configure the IDE

Updating from an older IDE

Older versions of Lazarus were only providing the GdbMI backend. It is highly recommended to update to Fp-Debugger or LLDB+FpDebug as indicated for your OS below.

Please note that many other wiki pages may be outdated and still refer only to GDB.

Choosing the correct debugger backend

The Lazarus IDE provides several debuggers (backends). The page Status of the debugger backends provides an overview.

The list below indicates which backend is recommended for your environment.


Operating System Hardware Recommended
debugger backend
Recommended
debug info
Notes


Windows 32/64bit Intel/AMD
i386 or x86_64
Fp-Debugger DWARF-3 Includes cross debugging of a 32bit app on a 64bit system
Windows 32bit
Cross 64bit
Intel/AMD
x86_64
GdbMi DWARF-2 with sets Only cross debugging of a 64bit app on a 32bit system
Windows ARM / AArch64 / other GdbMi DWARF-2 with sets You may also try "GdbMI+FpDebug"
Linux Intel/AMD
i386 or x86_64
Fp-Debugger DWARF-3 If RTL or packages have debug info, ensure it is the exact same type as for the project
Linux ARM / AArch64 / other GdbMi DWARF-2 with sets You may also try "GdbMI+FpDebug"
Mac Intel/AMD x86_64
AArch64 (e.g. M1)
LLDB+FpDebug DWARF-3
Embedded AVR FpDebug-avr package DWARF-2 or 3 Requires gdb server
Remote Any supported by GDB Gdb-Server DWARF-2 with sets Debugging on a different PC or VM
Other Any supported by GDB GdbMi DWARF-2 with sets
Any OS
Debug with STDIN/STDOUT redirect
(via "Run Parameters" command line: >file < file)
Any supported by GDB GdbMi DWARF-2 with sets

Setting up the debugger backend for the IDE

The following settings should be made once, after you installed Lazarus. They are often already set by default.

The settings can be found under
Tools > Options > Debugger > Debugger Backend
Lazarus menu options.png

The image shows where to find the option dialog. On Mac the dialog is under "Preferences"


lazarus dbg backend fpdebug.png
  • Select the correct backend on top of the page
  • The Fp-Debugger does not require a path.
  • If you have an LLDB or Gdb(MI) based debugger you must set the path to the gdb or lldb exe under "Debugger type and path"
    • On Linux/Unix/Mac systems it may be something like "/usr/bin/gdb" or "/usr/bin/lldb"
    • On Windows it should be in a folder called "mingw\bin\" under the directory in which Lazarus is installed.
  • On Status of the debugger backends you find a list of all backends with details on further settings.
    • For the GdbMI debugger under Lazarus 2.0 and up, enable the option "FixIncorrectStepOver" in the property grid.


The backend can also be set on a per project config. For details see IDE_Window:_Project_Options_-_Debugger_Backend

Project Options

Dbg setup project1.png

In order to debug your project, you need to tell the IDE to compile it in a special way, which provides additional information required by the debugger.

The required settings are made in the "Project Options" dialog:


  • Please note: This will considerably increase the size of your executable (See FAQ). If you want to build a release version of your software you should switch those settings off (see also Build Modes)



lazarus projectopts dbg.png
  • You must enable "Generate Debug Info for GDB"
  • You must enable "Run uses the debugger (disable for release mode)"
  • You should set "Type of debug info" as recommended for your PC.
    • If you set this to a non supported type, the IDE will prompt you for a correct setting when you try to start the debugger.
    • Automatic: Lets fpc choose. Can not be used with all backends.
    • Stabs: Old and outdated. Supported by GDB only (maybe LLDB **without** FpDebug). Should not be used
    • Dwarf 2: Minimal setting. Can not display watches for "set of". Issues with detecting PChar vs AnsiString. Should not be used
    • Dwarf 2 with sets: GDB friendly. Issues with detecting PChar vs AnsiString
    • Dwarf 3: Best setting for FpDebug.
    • None of them can currently display "property" with getter function.

  • You should **not** enable "Use external debug symbols"
    (It is a recommendation not to use this)
  • You **must** **not** enable "Strip symbols from executable"

You can use the "Build modes". The "..." button brings of a dialog to create "release and debug mode". In this case you should still check the "Type of debug info".



Dbg setup project4.png
    • Use optimization "Level 0" ("Level 1" may be used, but in some cases may cause issues)
    • Do **not** use "Link Smart"


GDB / LLDB Version

GDB 7.5 requires Lazarus 1.4 or higher.

GDB 7.7.1 seems to work well with Lazarus 1.2.4.

On macOS: lldb is part of the Apple developer tools

See also