macOS: clarify Apple Silicon build and Qt deployment

Summary

The macOS build instructions do not clearly describe the current Apple Silicon workflow, and parts of the build script still refer to Qt 5.

I would like to help improve the macOS build instructions and contribute a tested Apple Silicon build update.

Environment

• Architecture: Apple Silicon (arm64)
• Xcode Clang: 21.0.0
• SDK: MacOSX26.5.sdk
• Sioyek branch: development
• Qt version that initially failed: 6.8.2
• Qt version that compiled successfully: Homebrew Qt 6.11.2

Initial Qt 6.8.2 failure

Using the Qt 6.8.2 setup described in the README, compilation failed in:

QtCore.framework/Headers/qyieldcpu.h

with:

implicitly declaring library function '__yield'
[-Werror,-Wimplicit-function-declaration]

The error appeared while compiling multiple Sioyek source files that included QtWidgets. The error came from a Qt header rather than from Sioyek source code.

Qt 6.11.2 result

After switching to Homebrew Qt 6.11.2 and regenerating the qmake build files, the application compiled and linked successfully.

The resulting executable reports:

Mach-O 64-bit executable arm64

The main executable also loads Qt from the application bundle:

@executable_path/../Frameworks/QtCore.framework/...
@executable_path/../Frameworks/QtGui.framework/...
@executable_path/../Frameworks/QtWidgets.framework/...

The main executable does not contain direct /opt/homebrew Qt paths.

Packaging messages

macdeployqt still reports:

ERROR: Cannot resolve rpath "@rpath/QtPdf.framework/Versions/A/QtPdf"
ERROR: Cannot resolve rpath "@rpath/QtVirtualKeyboardQml.framework/Versions/A/QtVirtualKeyboardQml"
ERROR: Cannot resolve rpath "@rpath/QtVirtualKeyboard.framework/Versions/A/QtVirtualKeyboard"

The build script continues and creates the DMG despite these messages.

The main executable does not list these frameworks as direct dependencies, so I am not sure whether these are harmless optional QML/plugin references or whether the generated application bundle is incomplete.

Questions

1. Should the stale qt@5 prerequisite comment be removed or updated?
2. Which Qt installation method should be considered the primary supported macOS workflow?

• aqtinstall with a pinned Qt version;
• Homebrew Qt;
• or both, with one clearly marked as preferred?

1. Should the README document a native Apple Silicon build explicitly?
2. Which output architectures should the project support and document?

• arm64;
• x86_64;
• Universal;
• or separate architecture-specific builds?

1. Could the macOS instructions include an architecture verification command using file or lipo?
2. Could the instructions explain how to regenerate qmake files after changing Qt installations or Qt versions?
3. Are the macdeployqt unresolved-framework messages expected for the current Qt/QML setup?
4. If those frameworks are required, should the build process bundle them or install the missing Qt modules?
5. If those frameworks are optional, could the build process suppress or explain the messages?
6. Could the packaging step verify that the final application is self-contained and does not depend on the developer's Homebrew installation?
7. Could the build fail explicitly when a required framework cannot be deployed, rather than continuing to create a DMG?

Would a pull request covering the documentation and existing qmake-based macOS packaging improvements be useful? I'd be willing to test all the changes on apple silicon.

Separately, would it be useful to complete and document the existing CMake macOS path as a follow-up, while keeping the current qmake build path as it is?