macOS debugging: signing and symbols
Dev entitlements, signature inspection, .dSYM and attach diagnosis.
Native LLDB and a C# debugger serve different purposes. This page covers macOS process attachment, signing permissions and native symbols. See the Xcode guide for scheme preparation.
Local editor build
From Source, alongside SConstruct, build a development variant with symbols:
scons platform=macos target=editor arch=arm64 dev_build=yes debug_symbols=yes generate_bundle=yes -j4On Intel, use arch=x86_64. This example does not enable C#: follow the separate managed stages in the macOS build guide. Package a C# .app after preparing the managed files.
The current packager selects misc/dist/macos/editor_debug.entitlements for dev_build=yes, and editor.entitlements otherwise. Only the first file contains com.apple.security.get-task-allow. debug_symbols=yes does not select debug entitlements: symbols make stacks readable but do not grant attach permission.
The packager defaults to local ad-hoc identity -. This is neither Developer ID nor notarization. Its current codesign invocation also does not automatically reject a nonzero exit code: SCons success alone does not prove a valid signature.
Inspect the actual bundle
Substitute the resulting .app path; its name depends on build options. These commands inspect signatures and symbols without re-signing the application:
codesign --display --entitlements - "/absolute/Reckfell.app"
codesign --verify --deep --strict --verbose=2 "/absolute/Reckfell.app"
dwarfdump --uuid "/absolute/Reckfell.app/Contents/MacOS/Reckfell"For a debug bundle, check com.apple.security.get-task-allow = true and signature verification results. An entitlement file in the source tree is insufficient: inspect the permissions embedded in this application's signature. Permission does not guarantee attachment under every system policy; retain the exact LLDB error, executable path and process PID if it fails.
For separate symbols, the build supports debug_symbols=yes separate_debug_symbols=yes. The macOS post-action runs dsymutil to produce <binary>.dSYM, followed by strip; both commands must succeed. Keep the matching binary, .dSYM and source from one build. Sharing version number 1.0.0 does not make different builds interchangeable; compare binary and .dSYM UUIDs using dwarfdump --uuid.
Exported game
Local debug exports have the codesign/entitlements/debugging setting, defaulting to false. When generating built-in entitlements, it adds com.apple.security.get-task-allow. If you supply a custom entitlement file, inspect that file and the resulting signature instead of relying on the preset checkbox alone.
Do not distribute a debug signature as a release signature. See Apple's notarization requirements for get-task-allow. Create a separate release build/export without the debug entitlement and verify its signature again; renaming a .app does not change permissions.
Diagnosis
| Symptom | Check |
|---|---|
| Attach denied | Final entitlements, signature, PID, process user and exact error. Do not disable system protection as a routine step. |
| Unresolved breakpoint or raw addresses | Symbols, UUIDs, architecture and matching source. get-task-allow does not generate symbols. |
| The wrong process stops | Scheme executable, editor/game PID, launch path and --editor. |
| C# source lines unavailable in LLDB | A native stop does not establish managed-debugger attachment. |
Entitlement selection and symbol-generation source were reviewed. No re-signing, macOS attachment, notarization or export was executed in this review.