Dev feature: .pdb files for external debugging

News and discussion of the PC port of Oolite.

Moderators: another_commander, winston

Post Reply
another_commander
Quite Grand Sub-Admiral
Quite Grand Sub-Admiral
Posts: 7207
Joined: Wed Feb 28, 2007 7:54 am

Dev feature: .pdb files for external debugging

Post by another_commander »

Now that the master branch has been unblocked again, it is time to get some new features in.

For the Windows build, the first one is .pdb files. Those are extremely useful for debugging and people who have worked with Visual Studio probably know already a lot about them.

PDBs are basically files containing debug symbols of a specific executable. They can be very helpful in debugging because a dev can distribute a typical release executable (even with all debug info stripped) and keep the corresponding .pdb somewhere locally. If one wants to submit a crash report, all they have to do is find the crash dump generated by Windows (typically found as <localappdata>/CrashDumps/oolite.exe.XXXXX) and upload it somewhere. The dev holding the .pdb can take the dump file and use the .pdb to pinpoint the exact point of failure. The analysis can be done either on Visual Studio (although I haven't tested that) or in external debugging utilities, like Microsoft WinDbg, which is available at the MS Store for free.

To create a .pdb just run e.g. make debug=no pdb=yes. The pdb will be created inside obj.win.spk.

Important: A .pdb has one and only one corresponding executable that it is able to debug. If the code changes and a new exe is created then a new pdb must be created too, as the old one will no longer be good for debugging.
User avatar
hiran
Theorethicist
Posts: 2654
Joined: Fri Mar 26, 2021 1:39 pm
Location: a parallel world I created for myself. Some call it a singularity...

Re: Dev feature: .pdb files for external debugging

Post by hiran »

Sounds like such data could/should be contained in the debug version. Not sure how Linux will handle the same, but it is useful.

How about putting that in a Github issue which then can be referenced in the pull request?
Sunshine - Moonlight - Good Times - Oolite
another_commander
Quite Grand Sub-Admiral
Quite Grand Sub-Admiral
Posts: 7207
Joined: Wed Feb 28, 2007 7:54 am

Re: Dev feature: .pdb files for external debugging

Post by another_commander »

hiran wrote: Tue Mar 31, 2026 6:58 pm
How about putting that in a Github issue which then can be referenced in the pull request?
What pull request? It is already in.
User avatar
Lone_Wolf
---- E L I T E ----
---- E L I T E ----
Posts: 838
Joined: Wed Aug 08, 2007 10:59 pm
Location: Netherlands

Re: Dev feature: .pdb files for external debugging

Post by Lone_Wolf »

This is usually set by compiler flags (either by setting the flags directly or through the build system) .

GDB is the most used debugger on linux, can handle debug symbols created by clang and gcc and has a mingw based version for windows .

Maybe it would be a good idea to discuss how to improve debugging before introducing a new dependency that may only be suitable for one platform ?
OS : Arch Linux 64-bit - rolling release

From: The Netherlands, Europe

OXPs : My user page (needs updating)

Retired, occasionally active
another_commander
Quite Grand Sub-Admiral
Quite Grand Sub-Admiral
Posts: 7207
Joined: Wed Feb 28, 2007 7:54 am

Re: Dev feature: .pdb files for external debugging

Post by another_commander »

Lone_Wolf wrote: Thu Apr 02, 2026 10:07 am
This is usually set by compiler flags (either by setting the flags directly or through the build system) .
PDB generation is indeed set by compiler flag. The build system is used to set this compiler flag if the developer wants to, just like it does with any other flag. Default is to not set anything.
GDB is the most used debugger on linux, can handle debug symbols created by clang and gcc and has a mingw based version for windows .

Maybe it would be a good idea to discuss how to improve debugging before introducing a new dependency that may only be suitable for one platform ?
You seem to be missing the use case for .pdb files. It is well known that gdb is available for MinGW and has been used extensively over the years for Oolite. We have resolved hundreds of crashes by using it.

The issue is that gdb cannot be used to get backtraces from remote users running release builds, which (builds) are distributed stripped out of any debug information. A user experiencing a crash will have to use a debug build instead of the release one and re-create the crash with gdb running in order to get a backtrace that can be sent to the developer for investigation. Note, a user will have to do all that. Sometimes crashes are non-deterministic so they are difficult to recreate and in any case no Windows user will ever do all that. Therefore, we use .pdbs to be able to get the crash dump from remote users who are running release builds and be able to do the crash analysis without asking any work from them - they just send over the crash dump file and that's it, they 've done their part.

.pdbs are NOT a dependency. They are just an optional convenience for developers and any discussion about gdb and debugging improvements is very much welcome but at the same time very much irrelevant to what we are talking about here. GDB debugging can be improved while at the same time having .pdbs available and one does not exclude or affect the other.

Edit: Forgot to add that .pdbs are also used by the Microsoft Store to provide developers with crash data from applications when they fail during runtime, as long as users have opted-in for telemetry sharing. This is another huge reason to have them available whenever we make a Store release on Windows.
User avatar
mcarans
---- E L I T E ----
---- E L I T E ----
Posts: 789
Joined: Sun Jun 20, 2010 6:00 pm

Re: Dev feature: .pdb files for external debugging

Post by mcarans »

AI claims it is possible to do something similar for DWARF as well:

Separating Symbols (The "PDB-style" Workflow)

If you want to ship a small binary but keep a "PDB-equivalent" file for debugging crashes later, you use objcopy:

Extract symbols to a separate file:
objcopy --only-keep-debug my_program my_program.debug

Strip the original binary:
strip --strip-debug --strip-unneeded my_program

Link them (adds a "debug link" so GDB knows where to find the symbols):
objcopy --add-gnu-debuglink=my_program.debug my_program

Edit: it recommended another approach

The Linux standard is Split DWARF (using .dwo or .dwp files).

How to do it: Use the flag -gsplit-dwarf.

The Result: The compiler creates .o files for code and .dwo files for debug info. You can then use dwp to pack them into a single "Debug Repository" file.

Benefit: This keeps your binary small and makes linking significantly faster (just like PDBs do on Windows), as the linker doesn't have to move massive amounts of debug data around.
User avatar
hiran
Theorethicist
Posts: 2654
Joined: Fri Mar 26, 2021 1:39 pm
Location: a parallel world I created for myself. Some call it a singularity...

Re: Dev feature: .pdb files for external debugging

Post by hiran »

another_commander wrote: Tue Mar 31, 2026 7:04 pm
hiran wrote: Tue Mar 31, 2026 6:58 pm
How about putting that in a Github issue which then can be referenced in the pull request?
What pull request? It is already in.
While I understand your motivation and already indicated we should go for that feature, I second the idea to announce and discuss a change before it gets implemented.
Lone_Wolf wrote:
Maybe it would be a good idea to discuss how to improve debugging before introducing a new dependency that may only be suitable for one platform ?
This way you involve more people which will build a community, a prerequisite for finding more developers.
Sunshine - Moonlight - Good Times - Oolite
Post Reply