Debugger Setup

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

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

• 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

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)

• 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".

• 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

• IDE Options / Configuration Lazarus 2.0.x (and before)
  IDE Window: Debugger Options

  Lazarus 2.2 (and up)
  Debugger General Options and Debugger Backend Options

• Project Option / Command line args, Environment, and launcher app: 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

---

From the Free Pascal wiki, page "Debugger Setup", as it stood on 2023-12-13 after a change by Martin, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's Licensing page. If you have concerns about this material, message the admin.