Qt for macOS
Qt for macOS enables building applications for Apple's Mac line of computers.
To develop with Qt for macOS, follow the getting started guide; then explore the Qt examples, and related topics.
Supported Configurations
The following versions of the build environment and runtime target platform are supported by Qt 6.8.
Build Environment | Target Platform | Architecture |
---|---|---|
Xcode 15 (macOS 14 SDK) or higher | macOS 12 or higher (including macOS 15) | x86_64 , x86_64h , arm64 |
Note: Apple's forward compatibility promise for macOS generally ensures that Qt applications continue to run well on new operating system releases. Issues that may occur are prioritized and scheduled in accordance with the Qt branching and support policies. Support for new operating system features is not typically included in stable Qt releases.
Build Environment
The build environment for macOS is provided by Apple's Xcode application, which includes both the toolchain (compiler, linker, and other tools), and the macOS platform-SDK (headers and libraries) that you build and link against. Together these define how your application is built.
Apple generally recommend (and in the case of the App Store, require) that applications are built against the latest available SDK, so you should always be using the latest available Xcode from Apple. This may require upgrading your system's macOS version, as new Xcode versions may not run on older macOS versions.
Note: The macOS build environment is always defined entirely by the Xcode version (its toolchain and SDKs) you're using – not the version of macOS you are running Xcode on.
Opting out of behavior changes
One caveat to using the latest Xcode version and SDK to build your application is that the macOS system frameworks will sometimes decide whether or not to enable behavior changes based on the SDK you built your application against.
This technique allows Apple to ensure that binaries built against older SDKs will still continue to run without regressions on newer macOS releases.
For example, when dark mode was introduced in macOS 10.14 Mojave, macOS would only treat applications built against the 10.14 SDK as supporting dark mode, and would leave applications built against earlier SDKs with the default light mode look.
Building with an older Xcode version, against an older SDK, is one way to opt out of such behavior changes, but is a last-resort solution, and should only be applied if your application has no other ways of working around the problem.
Target Platforms
Building for macOS utilizes a technique called weak linking that allows you to build your application against the headers and libraries of the latest platform SDK, while still allowing your application to be deployed to macOS versions lower than the SDK version. When the binary is run on a macOS version lower than the SDK it was built with, Qt will check at runtime whether or not a platform feature is available before utilizing it.
In theory this would allow running your application on every single macOS version released, but for practical (and technical) reasons there is a lower limit to this range, known as the deployment target of your application. If the binary is launched on a macOS version below the deployment target Qt will give an error message and the application will not run.
Qt expresses the deployment target via the CMAKE_OSX_DEPLOYMENT_TARGET
or QMAKE_MACOSX_DEPLOYMENT_TARGET
variables, which by default is set to the minimum supported deployment target for Qt.
You only need to raise the deployment target if your own code uses APIs that were added in a macOS version higher than what Qt defaults to, and you are not using @available
checks to guard their use at runtime.
To raise the deployment target with CMake:
set(CMAKE_OSX_DEPLOYMENT_TARGET "42.0")
or with qmake:
QMAKE_MACOSX_DEPLOYMENT_TARGET = 42.0
Note: You should not lower the deployment target beyond the default value set by Qt. Doing so will likely lead to crashes at runtime if the binary is deployed to a macOS version lower than what Qt expected to run on.
For more information about SDK-based development on Apple platforms, see Apple's developer documentation.
Architectures
By default, Qt will build for the architecture of your development machine - either x86_64
if you're on an Intel Mac, or arm64
if you are on an Apple Silicon Mac.
To build for other architectures you can use the CMAKE_OSX_ARCHITECTURES
and QMAKE_APPLE_DEVICE_ARCHS
variables in your project files or on the command line. This allows you to both cross-compile to a different architecture, and to build universal (multi-architecture) binaries. For example, to build your application for both x86_64
and arm64
with CMake:
cmake ~/src/myapp -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64"
or with qmake:
qmake ~/src/myapp QMAKE_APPLE_DEVICE_ARCHS="x86_64 arm64"
When specifying the architectures in a project file they should not be quoted, e.g.:
TEMPLATE = app SOURCES = main.cpp QMAKE_APPLE_DEVICE_ARCHS = x86_64 arm64
Sub-architecture support on Intel Macs
In addition to the baseline x86_64
architecture, Qt also supports the x86_64h
("Haswell") sub-architecture, which improves performance on Intel Macs.
Getting Started
Installing Xcode
Xcode is a requirement for developing with Qt for macOS. It can be installed from the App Store, or downloaded from Apple's developer website.
Once installed, please run Xcode once to let it install any required dependencies.
Then verify that the system is using the correct Xcode installation using the xcode-select
tool.
$ xcode-select -print-path /Applications/Xcode.app/Contents/Developer
If the output does not match the expectation, choose the Xcode installation explicitly.
$ sudo xcode-select --switch /Applications/Xcode.app
Installing or building Qt
To install or build Qt, follow the general getting started with Qt guide.
Generating Xcode Project Files
By default, CMake and qmake generates project files in Makefile format. If you prefer to build and debug your application from within Xcode, you can request that an Xcode project is generated instead:
cmake ~/src/myapp -GXcode
or with qmake:
qmake ~/src/myapp -spec macx-xcode
Deploying Applications on macOS
macOS applications are typically deployed as self-contained application bundles. The application bundle contains the application executable as well as dependencies such as the Qt libraries, plugins, translations and other resources you may need. Third party libraries like Qt are normally not installed system-wide; each application provides its own copy.
To build your application as an application bundle with CMake, set the MACOSX_BUNDLE
property on your executable target, as follows:
qt_add_executable(app) if(APPLE) set_target_properties(tst_manual_ios_assets PROPERTIES MACOSX_BUNDLE TRUE) endif()
With qmake, bundles are the default. Set CONFIG -= app_bundle
in your project file (.pro
) to disable it.
A common way to distribute applications is to provide a compressed disk image (.dmg file) that the user can mount in Finder. The deployment tool, macdeployqt
(available from the macOS installers), can be used to create the self-contained bundles, and optionally also create a .dmg archive.
Applications can also be distributed through the Mac App Store. macdeployqt (bin/macdeployqt) can be used as a starting point for app store deployment. To ensure that Qt complies with the app store sandbox rules, Qt must be configured with the -feature-appstore-compliant
argument.
For details about deployment on macOS, see Qt for macOS - Deployment.
Note: For selling applications in the macOS App Store, special rules apply. In order to pass validation, the application must verify the existence of a valid receipt before executing any code. Since this is a copy protection mechanism, steps should be taken to avoid common patterns and obfuscate the code that validates the receipt as much as possible. Thus, this cannot be automated by Qt, but requires some platform-specific code written specifically for the application itself. More information can be found in Apple's documentation.
Related Topics
The following topics provide more details about Qt for macOS:
Using Objective-C Code in Qt Applications
Clang, the compiler used for applications on Apple Platforms, allows mixing C++ and Objective-C code. To enable this mode use the .mm
extension for the relevant source files and add them to your project as usual.
With CMake:
target_sources(myapp PRIVATE objc_code.mm)
With qmake:
SOURCES += objc_code.mm
You can then use Objective-C frameworks from Apple's Developer Library in your Qt applications.
To expose functionality to the rest of your application, without having to rename all your source files, declare helper functions in a header, and implement the functionality in an Objective-C++ source file:
© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.