Launch Lazarus Safely with startlazarus-3.0

startlazarus-3.0 is the small starter program standing between you and the Lazarus IDE window. It also decides whether a custom-built Lazarus should run instead of the packaged one, which is where a wrong compiler can sneak in. It takes no arguments in its installed manual. Allow about ten minutes. You need a graphical Linux session with Lazarus installed; the checks themselves are ordinary, unprivileged commands.

This guide uses Debian package lazarus-ide-3.0, version 3.0+dfsg1-8build3, as installed on this machine. The manual page itself is dated 19 April 2008, so treat what follows as the contract of this package rather than a promise about every Lazarus release.

1. Confirm the launcher you will run

Check the command path and package version before starting anything. Both of these commands only read the shell path and the package database:

$ command -v startlazarus-3.0
/usr/bin/startlazarus-3.0
$ dpkg-query -W -f='${Package} ${Version}\n' lazarus-ide-3.0
lazarus-ide-3.0 3.0+dfsg1-8build3

The Debian command is a symbolic link into the package's Lazarus 3.0 installation. A different path or version is not automatically wrong, but write it down before comparing results with this guide. Do not use sudo merely to start an IDE or to inspect these values.

2. Start the IDE with no arguments

The installed manpage describes startlazarus as a starter for the Lazarus program: it checks whether you have built a custom Lazarus and starts that when appropriate, and it is also what runs when the IDE restarts itself. Run the versioned command on its own:

$ startlazarus-3.0

Do not expect much terminal output once the graphical IDE opens. The expected result is a Lazarus window, not a printed help screen. Leave the terminal alone until the IDE has appeared; a terminal staying occupied is normal for a foreground graphical process.

The manual's synopsis is printed as lazarus, while its Usage section says to invoke startlazarus without arguments. Follow the explicit Usage section and the executable the package actually installed, rather than inventing option names from another Lazarus command. This starter's documented interface really is just the no-argument invocation.

3. Verify that the launch really worked

Check the shell status after closing the IDE, or after it exits because startup failed:

$ startlazarus-3.0
$ printf 'exit status: %s\n' "$?"
exit status: 0

Status 0 only means the launcher returned successfully. It does not prove a project opened, that a custom build was selected, or that every IDE component works. Check the window and any project state separately. If the process is still running, press Ctrl-C only if you actually mean to stop the foreground launcher; closing the IDE normally is the less surprising way to finish.

Nothing persistent changes in this example, so there is no undo command. If you stop the launcher before the window appears, just run the same no-argument command again after checking the diagnostic output.

4. Diagnose a headless session

A graphical application needs an accessible display, and a server, an SSH shell without X11 or Wayland access, or a terminal with DISPLAY deliberately unset can all make the launcher fail before the IDE ever opens. Reproduce that condition without touching the machine itself:

$ env -u DISPLAY startlazarus-3.0

(startlazarus-3.0:PID): Gtk-WARNING **: cannot open display:
$ printf 'exit status: %s\n' "$?"
exit status: 1

The number shown in place of PID varies. What matters is the GTK message and the non-zero status: that is a display-session problem, not proof the Lazarus package is missing. Run the command inside a working graphical login, or set up whatever display forwarding and authorisation your environment needs. Do not try to fix a display failure by running the IDE as root.

If the command path check passes but normal startup still fails, keep the terminal warning and status, then check the session's display variables and graphical permissions with your platform's usual tools. Avoid deleting Lazarus configuration directories as a first response; that can throw away editor settings and project preferences, and the manpage does not ask for it.

5. Keep the launcher and IDE roles separate

startlazarus-3.0 is a starter, not the documented build tool. The same manual points you at lazarus-ide, lazbuild and fpc for related jobs. Reach for the starter when you want the IDE opened or restarted, and only touch those other programs after checking their own installed manual pages and package versions.

The custom-build check is also a reminder not to assume the executable behind the launcher is always the system copy. If you have built a personal Lazarus, confirm which IDE window opens and which compiler or project settings it uses before relying on the result for a reproducible build. This command offers no documented switch for choosing between those builds.