Keep matching Release symbols
A failure that appears only in the optimized game needs the executable that actually failed, its matching PDB (program database) and the source files used to build it. Rebuilding the same commit can produce a different pair. Keep the original files before trying to reproduce the failure.
This is an optional recipe for the starter’s native Windows MSVC x64-release build.
It keeps Release optimization, precise floating-point rules and the selected runtime and IPO
policy. It does not substitute RelWithDebInfo or make the game behave like an unoptimized
Debug build. For ordinary source defects, begin with
Edit and debug in Visual Studio.
Opt in for one build
Section titled “Opt in for one build”From your game’s folder, make release-symbols.cmake and paste this file into it:
notepad release-symbols.cmake# Optional game-owned recipe. Include after project() and before the engine# and game subdirectories, then opt in with -DMYGAME_RELEASE_SYMBOLS=ON.include_guard(DIRECTORY)
option(MYGAME_RELEASE_SYMBOLS "Keep full symbols for native MSVC Release" OFF)
if(MYGAME_RELEASE_SYMBOLS) if(NOT WIN32 OR EMSCRIPTEN OR NOT CMAKE_CXX_COMPILER_ID STREQUAL "MSVC" OR NOT CMAKE_BUILD_TYPE STREQUAL "Release") message(FATAL_ERROR "MYGAME_RELEASE_SYMBOLS requires a native Windows MSVC Release build. " "Use the x64-release preset, or configure this option OFF.") endif() add_compile_options(/Zi /ZH:SHA_256) # /DEBUG changes the linker's optimisation defaults; restate Release's # elimination/folding and non-incremental link choices after it. add_link_options(/DEBUG:FULL /OPT:REF /OPT:ICF /INCREMENTAL:NO)endif()In the project’s top-level CMakeLists.txt, add the include before the engine and game
subdirectories, so that it applies to their compiled sources:
include(release-symbols.cmake)add_subdirectory(external/labrador)add_subdirectory(game)Then, in the x64 Native Tools Command Prompt:
cmake --preset x64-release -DMYGAME_RELEASE_SYMBOLS=ONcmake --build --preset x64-releasectest --preset x64-releaseThe option defaults to OFF. Opting in recompiles with source information and asks the linker
for a full out/build/x64-release/game/MyGame.pdb beside MyGame.exe. The full PDB can be
used without the original intermediate objects. The recipe adds these settings:
| Setting | Purpose |
|---|---|
/Zi |
Emit compiler debugging information while retaining optimization. |
/ZH:SHA_256 |
Record SHA-256 source checksums, so an edited file can be distinguished from the built source. |
/DEBUG:FULL |
Produce the final executable’s complete PDB. |
/OPT:REF /OPT:ICF /INCREMENTAL:NO |
Retain Release elimination, folding and non-incremental linking after enabling debug information. |
MSVC’s /DEBUG changes the default elimination and folding choices and implies incremental
linking, which is why the recipe states those choices after it.
Microsoft’s linker reference
explains that interaction; its source-checksum reference
describes /ZH.
The recipe leaves /O2, /fp:precise, the runtime and IPO selection alone. In particular,
engine-only IPO and a caller’s whole-project IPO remain different choices; the
qualified IPO policy
explains them. Turning this symbol option on does not turn IPO on. Custom compiler/linker
policies need their own checks; this recipe qualifies the starter’s ordinary MSVC Release choices.
Check the actual pair
Section titled “Check the actual pair”The following commands assume that tooling checkout is C:\dev\Labrador. Build the small
standalone probe from your game’s Native Tools prompt:
cmake -S C:\dev\Labrador\tools\consumer_check\symbol_probe -B out\symbol-probe -G Ninja -DCMAKE_BUILD_TYPE=Releasecmake --build out\symbol-probeout\symbol-probe\LabradorSymbolProbe.exe --exe out\build\x64-release\game\MyGame.exe --pdb out\build\x64-release\game\MyGame.pdb --source game\main.cpp --timeout 60 > out\symbol-check.txtThe probe uses the installed Windows SDK’s x64 dbghelp.dll, prints the actual loaded path
and uses only the selected local PDB path. If the DLL is elsewhere, pass its absolute path
with --dbghelp. This installs no debugger and changes no host debugger settings.
Success requires matching executable/PDB GUID and age, full line information, an exact source
checksum, a real one-shot breakpoint in wWinMain, and smoke-test exit zero. The probe starts
only the selected executable with --smoke-test, restores its breakpoint and closes that child
on failure or timeout. If your game changes its entry point or smoke route, adapt --symbol
to a reachable function or use your normal debugger. The
probe’s usage
states its scope.
Keep the evidence privately
Section titled “Keep the evidence privately”After a completed build and successful check, before editing its sources, run this from the game’s folder with Python:
python C:\dev\Labrador\tools\consumer_check\retain_symbols.py --exe out\build\x64-release\game\MyGame.exe --pdb out\build\x64-release\game\MyGame.pdb --source-root . --out out\private-symbols\release-one --receipt out\symbol-check.txtChoose a new destination for each retained build. The helper refuses an existing capture,
copies the selected EXE/PDB and receipt, and writes identity.json with their SHA-256 hashes
and a source.zip containing the source tree’s actual bytes. It excludes .git, .vs,
out, node_modules, vcpkg_installed and __pycache__ folders and refuses links rather than
following them into other trees. A destination inside the project must be under its excluded
out/ folder. An interrupted capture stays .partial and does not replace an older receipt.
Keeping actual bytes matters: a Git archive can have different line endings from the compiled working copy, which changes its source checksum. Retain the build commands, compiler version, selected options and any relevant generated source too. The capture records files and hashes; the separate probe verifies the matching PDB and selected source line. Neither establishes reproducible rebuilding of every dependency.
Store that folder where you keep private build evidence. PDBs and source archives can reveal
private names, paths and source. The normal cmake --install rules copy the game and its
runtime files, and do not copy these PDBs or this private folder. Keep sending players the
ordinary installed release.
Use it for a reported failure
Section titled “Use it for a reported failure”Keep the failing installed game or ZIP and identify its executable by hash. Select the retained
pair whose executable hash matches it; the filename or source commit alone is insufficient.
Extract source.zip privately and keep the PDB’s basename when moving it. The probe can use
that PDB and a relocated preserved main.cpp, provided its bytes match.
For a failure elsewhere, load the original executable and its matched PDB in your debugger and use the preserved sources when it asks for a file. Optimization can inline or remove code and variables, and fold identical functions: one verified breakpoint does not promise that every line or local is inspectable. Symbols for third-party DLLs require their own matching files. This recipe adds no dump writer, upload, signing or automatic publication.
What was checked
Section titled “What was checked”On 17 November 2026 an assembled consumer built and passed its two native tests with symbols
enabled, both under its ordinary IPO policy and with engine plus caller IPO explicitly on.
Both real debug-process probes loaded their exact PDB, checked main.cpp’s SHA-256, hit line
102 and resumed to smoke exit zero. The IPO install contained exactly the normal twenty files,
no PDB, and its installed smoke test passed. Relocated symbols/source passed; mismatched PDB
or source and a timeout failed with no surviving child. The
dated qualification
records source, compiler, options, hashes and limits. Browser, other compilers and a general
Visual Studio stepping session are outside that check.
Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.