Skip to content

error_reporting_howto.md

Latest commit

 

History

History
103 lines (80 loc) · 3.38 KB

error_reporting_howto.md

File metadata and controls

103 lines (80 loc) · 3.38 KB

Error reporting

In order to get the most context for fatal errors we need to have Debug information correcty installed either alongside the vkQuake executable, or in a place where it can be found for post-mortem analysis:

  • Windows MSVC : Debug information is in the vkQuake.pdb file:

    • Using vkQuake-Installer-windows_x64-N.NN.N.exe : Automatically installs the .pdb file at the right place.
    • Using vkQuake-N.NN.N_windows_x64.zip : put the vkQuake.pdb file at the same place as the vkQuake.exe file.

  • Windows MSYS2 for either x64 or arm64 : Debug information is already built-in the vkQuake.exe file.

  • Linux :

    • Using the Appimage build: the archive contains vkquake.debuginfo that will be used for post-mortem analysis.
    • Using either Meson or Makefile builds : Debug information is already built-in the vkquake executable.

  • MacOS :

    • vkquake.dSYM directory contains the Debug information that will be used for post-mortem analysis, and should be put at the same place where the vkquake exeutable is.

Extracting file+line information from in-game vkQuake fatal errors :

Examples:

Windows MSVC

Error reporting is directly built-in in the game : Users can report screenshots of either Host_Error console errors or Quake Error dialogs.

Linux, MacOS, or Windows MSYS2 (x64 or ARM64)

Host_Error and Quake Error dialogs only report raw stack traces with minimal context, often limited to function names in the best of cases. In order to get file+line information Users will need to run some external tools.

  • MSYS2:

STACK TRACE
0x100003f4d 0x100003f01 0x100003ed0 0x100003ea0 0x7fff2035a3d5

Run:

addr2line -e vkquake 0x16a8a8 0x93267 0x165735 0x165839 0x1669dd 0x166ea0 0x936ed

  • Linux:

STACK TRACE
0 : ./vkquake(+0x16a8a8) [0x588582e618a8]
1 : ./vkquake(+0x93267) [0x588582d8a267]
2 : ./vkquake(+0x165735) [0x588582e5c735]
3 : ./vkquake(+0x165839) [0x588582e5c839]
4 : ./vkquake(+0x1669dd) [0x588582e5d9dd]
5 : ./vkquake(+0x166ea0) [0x588582e5dea0]
6 : ./vkquake(+0x936ed) [0x588582d8a6ed]

Run:

# Using relative addresses: 
addr2line -f -e [VKQUAKEBEBUG] 0x16a8a8 0x93267 0x165735 0x165839 0x1669dd 0x166ea0 0x936ed

or Run:

# Using absolute addresses: 
addr2line -f -e [VKQUAKEBEBUG] 0x588582e618a8 0x588582d8a267 0x588582e5c735 0x588582e5c839 0x588582e5d9dd 0x588582e5dea0 0x588582d8a6ed

Use whatever works best, where [VKQUAKEBEBUG] is the vkQuake executable if built with either Meson or Makefile, or vkquake.debuginfo for Appimage.

  • MacOS:
STACK TRACE
0x100003f4d 0x100003f01 0x100003ed0 0x100003ea0 0x7fff2035a3d5
0 : 0   vkquake                 0x0000000100003f4d Sys_StackTrace + 77
1 : 1   vkquake                 0x0000000100003f01 level3 + 17
2 : 2   vkquake                 0x0000000100003ed0 level2 + 16
3 : 3   vkquake                 0x0000000100003ea0 level1 + 16
4 : 4   libdyld.dylib           0x00007fff2035a3d5 start + 1

Run:

# Pass the first line :
atos -o vkquake 0x100003f4d 0x100003f01 0x100003ed0 0x100003ea0 0x7fff2035a3d5

As a result of running either addr2line or atos we get file+line trace information looking like this :

sys_sdl_win.c:461
sys_sdl_win.c:278
wad.c:82
host.c:1115
main_sdl.c:112
SDL_windows_main.c:?

That can be reported to vkQuake maintainers.