mirror of
https://github.com/ZoiteChat/zoitechat.git
synced 2026-03-10 16:00:18 +00:00
deepend
cf2d5e5778
suppressed noisy defaults read failures for missing preference keys,
fixed unsafe/empty test expressions that caused test: argument expected,
corrected the gettext app domain from APP=name to APP=zoitechat.
Improved launcher behavior for architecture mismatches (Bad CPU type in executable) by detecting exit 126 and printing a clear hint plus file output for ZoiteChat-bin.
Updated osx/makebundle.sh so bundling is more Intel/Apple Silicon friendly:
dynamically resolves/writes prefix and prefix:enchant (Homebrew Intel vs Apple Silicon layouts),
still adapts enchant data path (share/enchant vs share/enchant-2),
prints bundled binary architecture after bundling so mismatches are immediately visible.
Extended macOS debugging docs with a dedicated “Bad CPU type in executable” section and explicit Intel (x86_64) build commands.
147 lines
4.4 KiB
Markdown
147 lines
4.4 KiB
Markdown
# 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.
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
./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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
file ZoiteChat.app/Contents/MacOS/ZoiteChat-bin
|
||
```
|
||
|
||
Build for Intel explicitly when needed:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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.
|