macOS: clarify Apple Silicon build and Qt deployment

[christian-auguste]

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?

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

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

5. Could the macOS instructions include an architecture verification command
   using file or lipo?
6. Could the instructions explain how to regenerate qmake files after
   changing Qt installations or Qt versions?
7. Are the macdeployqt unresolved-framework messages expected for the
   current Qt/QML setup?
8. If those frameworks are required, should the build process bundle them or
   install the missing Qt modules?
9. If those frameworks are optional, could the build process suppress or
   explain the messages?
10. Could the packaging step verify that the final application is
    self-contained and does not depend on the developer's Homebrew
    installation?
11. 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?

[KorigamiK]

This is addressed in #1606 perhaps you could take a look and move to the cmake build instructions from the workflow as well until it's merged