zoitechat/osx/DEBUGGING.md

Debugging ZoiteChat on macOS (Xcode + CLI)

If the unsigned .app launches but does nothing (or immediately exits), use the steps below to get actionable logs and a debugger session.

1) Build with debug symbols

ZoiteChat uses Meson. Build a debug configuration first so LLDB can show useful backtraces.

meson setup build-macos-debug --buildtype=debug
meson compile -C build-macos-debug

This project default is debugoptimized, but a full debug build is better while diagnosing crashes/startup issues.

2) Bundle the app and verify deployment target

Use the existing bundle script:

cd osx
./makebundle.sh

The generated Info.plist should keep:

• LSMinimumSystemVersion = 11.0

That is the project’s explicit minimum runtime target for macOS 11+.

3) Sanity-check the Mach-O binary in the bundle

Confirm architecture(s), deployment target, and linked libraries:

file ZoiteChat.app/Contents/MacOS/ZoiteChat-bin
otool -l ZoiteChat.app/Contents/MacOS/ZoiteChat-bin | rg -n "LC_BUILD_VERSION|minos|sdk"
otool -L ZoiteChat.app/Contents/MacOS/ZoiteChat-bin

For widest compatibility, build universal (arm64 + x86_64) or build separately per arch and test each on matching hosts.

4) Ad-hoc sign for local debugging

Unsigned GUI binaries can fail in unhelpful ways because of hardened runtime/quarantine/Gatekeeper interactions. For local debugging, ad-hoc sign the app:

xattr -dr com.apple.quarantine ZoiteChat.app
codesign --force --deep --sign - ZoiteChat.app
codesign --verify --deep --strict --verbose=2 ZoiteChat.app

5) Launch from Terminal first (before Xcode)

Direct launch exposes stdout/stderr and validates the launcher environment:

./ZoiteChat.app/Contents/MacOS/ZoiteChat

The launcher script sets GTK/Pango/GDK environment variables. If direct launch fails, capture that output first.

6) Debug with LLDB (reliable baseline)

Debug the real executable inside the bundle:

lldb -- ZoiteChat.app/Contents/MacOS/ZoiteChat-bin
(lldb) run
(lldb) bt

If it exits instantly, set breakpoints on startup entry points (for example main) and re-run.

7) Debug with Xcode (if you prefer GUI)

Xcode works best when opening the executable directly instead of importing build scripts.

1. File → Open… and select ZoiteChat.app/Contents/MacOS/ZoiteChat-bin.
2. In Product → Scheme → Edit Scheme…
   • Executable: ZoiteChat-bin
   • Working directory: repo root (or osx/)
   • Add environment variables equivalent to the launcher if needed.
3. Run under debugger.

If Xcode “runs” but no UI appears, compare its environment to osx/launcher.sh and copy missing GTK-related variables into the scheme.

8) Capture macOS crash diagnostics

Even if no dialog appears, macOS usually logs termination reasons:

log stream --style compact --predicate 'process == "ZoiteChat-bin"'

Also check:

• ~/Library/Logs/DiagnosticReports/

9) Frequent root causes for “silent” startup failures

• Missing GTK runtime libraries in app bundle (otool -L shows unresolved paths).
• Incorrect @rpath/install names after bundling.
• Running under Rosetta mismatch (x86_64 binary with arm64-only deps or vice versa).
• Quarantine/signature issues on unsigned artifacts.
• Missing GDK_PIXBUF_MODULE_FILE, GTK_IM_MODULE_FILE, or schema paths.

"Bad CPU type in executable"

This means the bundled ZoiteChat-bin architecture does not match the Mac you are running on.

• Intel Mac requires x86_64
• Apple Silicon requires arm64 (or Rosetta + x86_64)

Check the binary quickly:

file ZoiteChat.app/Contents/MacOS/ZoiteChat-bin

Build for Intel explicitly when needed:

export CFLAGS="-arch x86_64"
export LDFLAGS="-arch x86_64"
meson setup build-macos-intel --buildtype=debug
meson compile -C build-macos-intel

If your dependency stack supports it, build universal (arm64 + x86_64) and verify with lipo -info.

10) Recommended compatibility settings for macOS 11+

• Keep LSMinimumSystemVersion at 11.0.
• Build on the oldest macOS SDK/toolchain that still supports your dependencies, or explicitly set:

export MACOSX_DEPLOYMENT_TARGET=11.0

• Verify with otool -l that minos is actually 11.0 in the final executable.

---

If you want, we can add an Xcode scheme file to this repo that mirrors osx/launcher.sh so “Run” in Xcode behaves exactly like launching the app bundle from Finder/Terminal.