适用于 macOS 的 Qt

适用于 macOS 的 Qt 支持为苹果公司的Mac系列计算机构建应用程序。

若要使用 Qt for macOS 进行开发，请按照入门指南操作；随后可探索 Qt 示例及相关主题。

支持的配置

Qt 6.12 支持以下版本的构建环境和运行时目标平台。

构建环境

macOS 的构建环境由 Apple 的Xcode应用程序提供，其中既包含工具链（编译器、链接器及其他工具），也包含用于构建和链接的 macOS 平台 SDK（头文件和库）。这些组件共同定义了应用程序的构建方式。

Apple 通常建议（对于 App Store 应用则要求）应用程序必须基于最新的 SDK 进行构建，因此您应始终使用 Apple 提供的最新版 Xcode。这可能需要升级系统的 macOS 版本，因为新版 Xcode 可能无法在旧版 macOS 上运行。

选择不采用行为变更

使用最新版本的 Xcode 和 SDK 构建应用程序时需要注意的一点是，macOS 系统框架有时会根据您构建应用程序时所使用的 SDK 来决定是否启用行为变更。

这种做法使 Apple 能够确保基于旧版 SDK 构建的二进制文件，在新版 macOS 系统上仍能正常运行，且不会出现功能退化。

例如，当 macOS 10.14 Mojave 引入深色模式时，macOS 只会将基于 10.14 SDK 构建的应用程序视为支持深色模式，而基于较早 SDK 构建的应用程序则会保留默认的浅色模式外观。

使用较旧版本的 Xcode 并基于较旧的 SDK 进行构建，是规避此类行为变化的方法之一，但这仅是最后的手段，仅当您的应用程序没有其他方法可以解决此问题时才应采用。

目标平台

针对 macOS 进行构建时会采用一种称为“弱链接”的技术，该技术允许您使用最新平台 SDK 的头文件和库来构建应用程序，同时仍允许将应用程序部署到低于该 SDK 版本的 macOS 系统上。 当二进制文件在低于其构建所用 SDK 版本的 macOS 上运行时，Qt 会在运行时检查平台功能是否可用，然后才使用该功能。

理论上，这使得您的应用程序能够在已发布的每一款 macOS 版本上运行，但出于实际（和技术）原因，该范围存在一个下限，即应用程序的“部署目标”。如果二进制文件在低于部署目标的 macOS 版本上启动，Qt 将显示错误信息，且应用程序无法运行。

Qt 通过 CMAKE_OSX_DEPLOYMENT_TARGET 或QMAKE_MACOSX_DEPLOYMENT_TARGET 变量表示，其默认值设置为Qt支持的最低部署目标。

只有当您的代码使用了在高于 Qt 默认版本的 macOS 版本中才添加的 API，且您未使用 `@available ` 检查来在运行时保护这些 API 的使用时，才需要提高部署目标。

若要使用 CMake 提高部署目标：

set(CMAKE_OSX_DEPLOYMENT_TARGET "42.0")

或使用 qmake：

QMAKE_MACOSX_DEPLOYMENT_TARGET = 42.0

有关在 Apple 平台上基于 SDK 进行开发的更多信息，请参阅 Apple 的开发者文档。

架构

默认情况下，Qt 将针对您的开发机器的架构进行构建——如果您使用的是 Intel Mac，则为x86_64 ；如果您使用的是 Apple Silicon Mac，则为arm64 。

若要针对其他架构进行构建，您可以在项目文件或命令行中使用 CMAKE_OSX_ARCHITECTURES 和QMAKE_APPLE_DEVICE_ARCHS 变量。这既允许你对不同架构进行交叉编译，也支持构建通用（多架构）二进制文件。例如，若要使用 CMake 同时为x86_64 和arm64 构建应用程序：

cmake ~/src/myapp -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64"

或者使用 qmake：

qmake ~/src/myapp QMAKE_APPLE_DEVICE_ARCHS="x86_64 arm64"

在项目文件中指定架构时，不应使用引号，例如：

TEMPLATE = app
SOURCES = main.cpp
QMAKE_APPLE_DEVICE_ARCHS = x86_64 arm64

Intel Mac 上的子架构支持

除了基准的x86_64 架构外，Qt还支持x86_64h （“Haswell”）子架构，该架构可提升Intel Mac上的性能。

入门指南

安装 Xcode

Xcode 是使用 Qt 开发 macOS 应用程序的必备工具。您可以从App Store 安装，或从 Apple开发者网站下载。

安装完成后，请运行一次 Xcode，以便其安装所需的依赖项。

然后，请使用xcode-select 工具验证系统是否正在使用正确的 Xcode 安装版本。

$ xcode-select -print-path
/Applications/Xcode.app/Contents/Developer

如果输出结果与预期不符，请手动选择正确的Xcode安装版本。

$ sudo xcode-select --switch /Applications/Xcode.app

安装或构建 Qt

要安装或构建 Qt，请按照Qt 入门指南中的通用步骤操作。

您还可以参考《macOS 上安装 Qt 的其他方法》，了解如何通过 Homebrew 安装 Qt。

生成 Xcode 项目文件

默认情况下，CMake 和 qmake 会生成 Makefile 格式的项目文件。如果您更希望在 Xcode 中构建和调试应用程序，可以要求生成 Xcode 项目文件：

cmake ~/src/myapp -GXcode

或者使用 qmake：

qmake ~/src/myapp -spec macx-xcode

在 macOS 上部署应用程序

macOS 应用程序通常以自包含的应用程序包形式部署。应用程序包中包含应用程序的可执行文件，以及 Qt 库、插件、翻译文件和其他可能需要的资源等依赖项。像 Qt 这样的第三方库通常不会在系统范围内安装；每个应用程序都会提供自己的副本。

若要使用 CMake 将应用程序构建为应用程序包，请为您的可执行目标设置 MACOSX_BUNDLE 属性，如下所示：

qt_add_executable(MyApp)
if(APPLE)
    set_target_properties(MyApp PROPERTIES MACOSX_BUNDLE TRUE)
endif()

使用 qmake 时，默认会生成应用程序包。若要禁用此功能，请在项目文件（.pro ）中设置CONFIG -= app_bundle 。

一种常见的应用程序分发方式是提供一个压缩的磁盘映像（.dmg 文件），用户可以在 Finder 中将其挂载。部署工具macdeployqt （可通过 macOS 安装程序获取）可用于创建自包含的软件包，并可选地创建 .dmg 归档文件。

应用程序还可以通过 Mac App Store 进行分发。macdeployqt（bin/macdeployqt）可作为 App Store 部署的起点。为确保 Qt 符合 App Store 的沙盒规则，必须使用-feature-appstore-compliant 参数对 Qt 进行配置。

有关在 macOS 上部署的详细信息，请参阅《Qt for macOS - 部署》。

相关主题

以下主题提供了有关 Qt for macOS 的更多详细信息：

• macOS 版 Qt - 从源代码构建
• macOS 版 Qt - 部署
• macOS 版 Qt - 特定问题

在 Qt 应用程序中使用 Objective-C 代码

Clang（Apple 平台应用程序所使用的编译器）支持混合使用 C++ 和 Objective-C 代码。要启用此模式，请为相关源文件使用.mm 扩展名，并按常规方式将其添加到项目中。

使用 CMake 时：

target_sources(myapp PRIVATE objc_code.mm)

使用 qmake：

SOURCES += objc_code.mm

这样，您就可以在 Qt 应用程序中使用 Apple 开发者库中的 Objective-C 框架了。

若要将功能提供给应用程序的其他部分，同时无需重命名所有源文件，请在头文件中声明辅助函数，并在 Objective-C++ 源文件中实现该功能：

// objc_code.h
QString localizedHostName();

// objc_code.mm
#include <Foundation/NSHost.h>
QString localizedHostName()
{
    return QString::fromNSString(NSHost.currentHost.localizedName);
}