Revision control
Copy as Markdown
// Copyright (C) 2019 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page macos.html
\title Qt for \macos
\brief Platform support for \macos.
\keyword Qt for macOS
\ingroup supportedplatform
Qt for \macos enables building applications for Apple's
To develop with Qt for \macos, follow the \l{Getting Started}
{getting started guide}; then explore the Qt examples, and
\l{#Related Topics}{related topics}.
\target macos-supported-versions
\section1 Supported Configurations
The following versions of the \l{Build Environment}{build environment}
and runtime \l {Target Platforms}{target platform} are supported by Qt \qtver.
\include supported-platforms.qdocinc macos
\include apple-common.qdocinc {build-environment} {\macos}
\include apple-common.qdocinc {target-platforms} {\macos}
\section2 Architectures
By default, Qt will build for the architecture of your development machine -
either \c x86_64 if you're on an Intel Mac, or \c arm64 if you are on an
Apple Silicon Mac.
To build for other architectures you can use the \l
{\c CMAKE_OSX_ARCHITECTURES} and \c 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 \c x86_64 and \c arm64 with CMake:
\code
cmake ~/src/myapp -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64"
\endcode
or with qmake:
\code
qmake ~/src/myapp QMAKE_APPLE_DEVICE_ARCHS="x86_64 arm64"
\endcode
When specifying the architectures in a project file they should not be quoted, e.g.:
\code
TEMPLATE = app
SOURCES = main.cpp
QMAKE_APPLE_DEVICE_ARCHS = x86_64 arm64
\endcode
\section3 Sub-architecture support on Intel Macs
In addition to the baseline \c x86_64 architecture, Qt also supports the
\c x86_64h ("Haswell") sub-architecture, which improves performance on Intel
Macs.
\section1 Getting Started
\include apple-common.qdocinc {installing-xcode} {macOS}
\section2 Installing or building Qt
To install or build Qt, follow the general \l{Getting Started with Qt}
{getting started with Qt} guide.
You can also follow \l{Qt for \macos - Alternative ways of installing Qt}
{Alternative ways of installing Qt for macOS} for information on how to
install Qt from Homebrew.
\section2 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:
\code
cmake ~/src/myapp -GXcode
\endcode
or with qmake:
\code
qmake ~/src/myapp -spec macx-xcode
\endcode
\section2 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.
\include {apple-app-bundle.qdocinc} {building an app bundle}
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, \c
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 \c {-feature-appstore-compliant} argument.
For details about deployment on \macos, see \l{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
\l{https://developer.apple.com/library/archive/releasenotes/General/ValidateAppStoreReceipt/Chapters/ValidateLocally.html}{Apple's documentation}.
\section1 Related Topics
The following topics provide more details about Qt for \macos:
\list
\li \l{Qt for \macos - Building from Source}
\li \l{Qt for \macos - Deployment}
\li \l{Qt for \macos - Specific Issues}
\endlist
\include objective-c.qdocinc
*/
/*!
\page macos-building.html
\title Qt for \macos - Building from Source
\brief How to install Qt on \macos.
\section1 Requirements
Building Qt requires a \macos platform SDK and corresponding toolchain to be
installed on the system. You can get this by installing the Xcode, as described
in \l {Qt for \macos#Build Environment}{Build Environment}.
You should always use the exact same Xcode and SDK version as listed in the
\l {Qt for \macos#Supported Configurations}{Supported Configurations}, to
ensure that Qt has been tested in the configuration you're building.
In addition to Xcode, you will need to make sure you have the following
dependencies in your path \c PATH.
\list
\include system-requirements-building-from-source.qdocinc minimal
\endlist
If you want to build \l {Qt WebEngine} or \l {Qt PDF}, you will need the
following additional dependencies:
\list
\include system-requirements-building-from-source.qdocinc
{qt webengine and qt pdf}
\endlist
\section2 QDoc Dependencies
\l {QDoc Manual}{QDoc} uses Clang to parse C++ code.
If you wish to build QDoc manually, refer to \l {Installing Clang for QDoc}
for specific build requirements.
\section1 Steps for Building
The following instructions describe how to build Qt from the source package.
You can download the Qt sources from the \l{Downloads} page. For
more information, visit the \l{Getting Started with Qt} page.
\section2 Step 1: Unpack the Archive
Unpack the archive if you have not done so already. For example,
if you have the \tt{qt-everywhere-src-\QtVersion.tar.xz} package, type
the following commands at a command line prompt:
\include snippets/code/doc_src_installation.qdoc 11
This creates the directory \tt{/tmp/qt-everywhere-src-\QtVersion}
containing the files from the archive.
\section2 Step 2: Build the Qt Library
To configure the Qt library for your machine type, create a build
directory and change to it. Run the
\c{./configure} script in this directory.
\include snippets/code/doc_src_installation.qdoc 12
\include use-ninja-note.qdocinc ninja-note
By default, Qt is configured for installation in the
\tt{/usr/local/\QtVersion} directory, but this can be
changed by using the \c{-prefix} option.
By default, Qt is built as a framework, but you can built
it as a set of dynamic libraries (dylibs) by specifying the
\c{-no-framework} option.
As described in \l {Qt for \macos#Architectures}{Architectures}, Qt will
build for the architecture of your development machine by
default. To configure a universal build of Qt with support
for both Intel and Apple Silicon Macs, add the following argument:
\code
./configure -- -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64"
\endcode
\note A universal build always needs to include the architecture of
your development machine, as the process relies on tools that are built
and run on your machine as part of the overall build.
Be careful to specify the Intel architecture ("x86_64") first,
otherwise Qt may not enable all the x86 functionality.
Qt can also be configured to be built with debugging symbols. This
process is described in detail in the \l{Debugging Techniques}
document.
The \l{Qt Configure Options}{Configure Options} page contains more
information about the configure options.
To create the library and compile all the examples and tools, type:
\snippet snippets/code/doc_src_installation.qdoc 13
If \c{-prefix} is outside the build directory, you need to install
the library, examples, and tools in the appropriate place. To do this,
type:
\snippet snippets/code/doc_src_installation.qdoc 14
This command requires that you have administrator access
on your machine.
\section2 Step 3: Set the Environment Variables
In order to use Qt, some environment variables need to be
extended.
\snippet snippets/code/doc_src_installation.qdoc 15
This is done like this:
In \c{.profile} (if your shell is bash), or \c{.zshenv} (for zsh)
add the following lines:
\snippet snippets/code/doc_src_installation.qdoc 16
In \c{.login} (in case your shell is csh or tcsh), add the following line:
\snippet snippets/code/doc_src_installation.qdoc 17
If you use a different shell, please modify your environment
variables accordingly.
\b {Qt is now installed.}
*/
/*!
\page macos-issues.html
\title Qt for \macos - Specific Issues
\brief A description of issues with Qt that are specific to \macos.
This page outlines the main issues regarding \macos support in Qt.
\macos terminologies and specific processes are found at
\section1 Aqua
The Aqua style is an essential part of the \macos platform. As with Cocoa, Qt provides widgets that
look like those described in the \l{https://developer.apple.com/design/human-interface-guidelines/macos/overview/themes/}
{\macos Human Interface Guidelines}. Note that although Qt's widgets use AppKit under the hood for
look and feel, it does not represent each individual Qt Widget as a wrapped native control.
The \l{Qt Widget Gallery} page contains sample images of applications using
the \macos platform theme.
\section1 Qt Attributes for \macos
The following lists a set of useful attributes that can be used to tweak
applications on \macos:
\list
\li Qt::AA_PluginApplication
\li Qt::AA_DontUseNativeMenuBar
\li Qt::AA_MacDontSwapCtrlAndMeta
\li Qt::WA_MacOpaqueSizeGrip
\li Qt::WA_MacShowFocusRect
\li Qt::WA_MacNormalSize
\li Qt::WA_MacSmallSize
\li Qt::WA_MacMiniSize
\li Qt::WA_MacAlwaysShowToolWindow
\li Qt::Sheet
\li Qt::MacWindowToolBarButtonHint,
\li QMainWindow::unifiedTitleAndToolBarOnMac
\endlist
\macos always double buffers the screen, therefore, the
Qt::WA_PaintOnScreen attribute has no effect. Also it is impossible to paint
outside of a paint event so Qt::WA_PaintOutsidePaintEvent has no effect
either.
\section1 Right Mouse Clicks
The QContextMenuEvent class provides right mouse click support for \macos
applications. This will map to a context menu event, for example, a menu
that will display a pop-up selection. This is the most common use of right
mouse clicks, and maps to a control-click with the \macos one-button mouse
support.
\section1 Internationalization
Applications on \macos declare their supported languages as part of the
\c Info.plist of the application. The system will then match the application's
supported languages with the user's language preferences to determine the locale
the application is launched in. This in turn determines the ordered languages
reflected through QLocale::uiLanguages(), and how system frameworks such as
AppKit pick up their localized resources, such as menu titles and strings.
As Qt apps are not translated out of the box, the default generated \c Info.plist
for \c CMake and \c qmake projects sets
{\c CFBundleAllowMixedLocalizations} to \c YES, to allow system frameworks to pick
the localization that best matches the user's language preferences, even if that
localization is not available for the application itself. Once you add translations
to your application via \l qt_add_translations, the
{\c CFBundleAllowMixedLocalizations}
key will be automatically removed, and replace with \l{https://developer.apple.com/documentation/bundleresources/information_property_list/cfbundlelocalizations?language=objc}
{\c CFBundleLocalizations}, listing all the languages you support.
For \c qmake this process must be done manually.
\section1 Menu Bar
Qt detects menu bars and turns them into Mac native menu bars. Fitting this
into existing Qt applications is normally automatic. However, if you
have special needs, the Qt implementation currently selects a menu bar by
starting at the active window (for example, QGuiApplication::focusWindow())
and applying the following tests:
\list 1
\li If the window has a QMenuBar, then it is used.
\li If the window is modal, then its menu bar is used. If no menu
bar is specified, then a default menu bar is used (as
documented below).
\li If the window has no parent, then the default menu bar is used
(as documented below).
\endlist
These tests are followed all the way up the parent window chain
until one of the above rules is satisfied. If all else fails, a
default menu bar will be created. The default menu bar on
Qt is an empty menu bar. However, you can create a different
default menu bar by creating a parentless QMenuBar. The first one
created will be designated the default menu bar and will be used
whenever a default menu bar is needed.
Using native menu bars introduces certain limitations on Qt classes. The
section with the \l{#Limitations}{list of limitations} below has more
information.
Qt provides support for the Global Menu Bar with QMenuBar. \macos users
expect to have a menu bar at the top of the screen and Qt honors this.
Additionally, users expect certain conventions to be respected, for example
the application menu should contain \gui About, \gui Preferences, \gui Quit,
and so on. Qt handles these conventions, although it does not provide a
means of interacting directly with the application menu.
Each \l QAction has a \l{QAction::menuRole}{menuRole} property which
controls the special placement of application menu items; however by
default the \c menuRole is \l{QAction::TextHeuristicRole}{TextHeuristicRole}
which mean the menu items will be auto-detected by their \l{QAction::text}{text}.
Other standard menu items such as \gui Cut, \gui Copy, \gui Paste and
\gui{Select All} are applicable both in your application and in some
native dialogs such as \l QFileDialog. It's important that you create these
menu items with the standard shortcuts so that the corresponding editing
features will be enabled in the dialogs. At this time there are no
\c MenuRole identifiers for them, but they will be auto-detected
just like the application menu items when the \c QAction has the default
\l{QAction::TextHeuristicRole}{TextHeuristicRole}.
\section1 Special Keys
To provide the expected behavior for Qt applications on \macos,
the Qt::Key_Meta, Qt::MetaModifier, and Qt::META enum values
correspond to the Control keys on the standard Apple keyboard,
and the Qt::Key_Control, Qt::ControlModifier, and Qt::CTRL enum values
correspond to the Command keys.
\section1 Dock
Interaction with the dock is possible. The icon can be set by calling
\l QWindow::setIcon() from the main window in your application. The
setIcon() call can be made as often as necessary, providing an
icon that can be easily updated.
\section1 Accessiblity
Many users interact with \macos with assistive devices. With Qt the aim is
to make this automatic in your application so that it conforms to accepted
practice on its platform. Qt uses Apple's accessibility framework to provide
access to users with disabilities.
\section1 Library and Deployment Support
Qt provides support for \macos structures such as Frameworks and bundles.
It is important to be aware of these structure as they directly affect the
deployment of applications.
Qt provides a deploy tool, \l macdeployqt, to
simplify the deployment process. The \l{Qt for \macos - Deployment}
article covers the deployment process in more detail.
\section2 Qt Libraries as Frameworks
By default, Qt is built as a set of frameworks. Frameworks are the
\macos preferred way of distributing libraries. The
{Apple's Framework Programming Guide} site has far more information about
Frameworks.
It is important to remember that Frameworks always link with \e release
versions of libraries. If the \e{debug} version of a Qt framework is
desired, use the \c DYLD_IMAGE_SUFFIX environment variables to ensure that
the debug version is loaded:
\code
export DYLD_IMAGE_SUFFIX=_debug
\endcode
Alternatively, you can temporarily swap your debug and release versions,
which is documented in
{Apple's "Debugging Magic" technical note}.
If you don't want to use frameworks, simply configure Qt with
\c{-no-framework}.
\code
./configure -no-framework
\endcode
\section2 Bundle-Based Libraries
If you want to use some dynamic libraries in the \macos
application bundle (the application directory), create a
subdirectory named \e Frameworks in the application bundle
directory and place your dynamic libraries there. The application
will find a dynamic library if it has the install name
\e{@executable_path/../Frameworks/libname.dylib}.
If you use \c qmake and Makefiles, use the \c QMAKE_LFLAGS_SONAME setting:
\snippet snippets/code/doc_src_mac-differences.pro 0
Alternatively, you can modify the install name using the
\c{install_name_tool(1)} on the command line.
The \c DYLD_LIBRARY_PATH environment variable will override these settings,
and any other default paths, such as a lookup of dynamic libraries inside
\e /usr/lib and similar default locations.
\section2 Combining Libraries
If you want to build a new dynamic library combining the Qt
dynamic libraries, you need to introduce the \c{ld -r} flag. Then
relocation information is stored in the output file, so that
this file could be the subject of another \c ld run. This is done
by setting the \c -r flag in the \c .pro file, and the \c LFLAGS
settings.
\section2 Initialization Order
\c dyld(1) calls global static initializers in the order they are
linked into the application. If a library links against Qt and
references the globals in Qt (from global initializers in your own
library), link the application against Qt before
linking it against the library. Otherwise the result will be
undefined because Qt's global initializers have not been called
yet.
\section1 Compile-Time Flags
The following flags are helpful when you want to define \macos specific
code:
\list
\li \c Q_OS_DARWIN is defined when Qt detects you are on a
Darwin-based system such as \macos or iOS.
\li \c Q_OS_MACOS is defined when you are on an \macos system.
\endlist
\note \c Q_WS_MAC is no longer defined in Qt 5 and later.
If you want to define code for specific versions of \macos, use
the availability macros defined in \e{/usr/include/AvailabilityMacros.h}.
The QSysInfo and QOperatingSystemVerison documentation has information about runtime version checking.
\section1 \macos Native API Access
\section2 Accessing the Bundle Path
\macos applications are structured as a directory (ending with \e .app).
This directory contains sub-directories and files. It may be useful to place
items, such as plugins and online documentation, inside this bundle. The
following code returns the path of the application bundle:
\snippet snippets/code/doc_src_mac-differences.cpp 1
For more information about using the NSBundle API, visit
{Apple's Developer Website}.
QCoreApplication::applicationDirPath() can be used to determine
the path of the binary within the bundle.
\section2 Using Native Cocoa Panels
Qt's event dispatcher is more flexible than what Cocoa offers, and lets the
user spin the event dispatcher (and running QEventLoop::exec) without having
to think about whether or not modal dialogs are showing on screen (which is
a difference compared to Cocoa). Therefore, we need to do extra management
in Qt to handle this correctly, which unfortunately makes mixing native
panels hard. The best way at the moment to do this, is to follow the pattern
below, where we post the call to the function with native code rather than
calling it directly. Then we know that Qt has cleanly updated any pending
event loop recursions before the native panel is shown:
\code
#include <QtGui>
class NativeProxyObject : public QObject
{
Q_OBJECT
public slots:
void execNativeDialogLater()
{
QMetaObject::invokeMethod(this, "execNativeDialogNow", Qt::QueuedConnection);
}
void execNativeDialogNow()
{
NSRunAlertPanel(@"A Native dialog", @"", @"OK", @"", @"");
}
};
#include "main.moc"
int main(int argc, char **argv){
QApplication app(argc, argv);
NativeProxyObject proxy;
QPushButton button("Show native dialog");
QObject::connect(&button, SIGNAL(clicked()), &proxy, SLOT(execNativeDialogLater()));
button.show();
return app.exec();
}
\endcode
\section1 Limitations
\section2 MySQL and \macos
There seems to be a issue when both \c -prebind and \c -multi_module are
defined when linking static C libraries into dynamic libraries. If you
get the following error message when linking Qt:
\snippet snippets/code/doc_src_platform-notes.qdoc 6
re-link Qt using -single_module. This is only a problem when building the
MySQL driver into Qt. It does not affect plugins or static builds.
\section2 D-Bus and \macos
The QtDBus module defaults to dynamically loading the libdbus-1 library on
\macos. That means applications linking against the QtDBus module will
load even on \macos systems that do not have the libraries, but they
will fail to connect to any D-Bus server and they will fail to open a
server using QDBusServer.
To use D-Bus functionality, you need to install the libdbus-1 library, for
example through Homebrew, Fink or MacPorts. You may want to include those
libraries in your application's bundle if you're deploying to other
systems. Additionally, note that there is no system bus on \macos and
that the session bus will only be started after launchd is configured to
manage it.
\section2 Menu Actions
\list
\li Actions in a QMenu with accelerators that have more than one
keystroke (QKeySequence) will not display correctly, when the
QMenu is translated into a Mac native menu bar. The first key
will be displayed. However, the shortcut will still be
activated as on all other platforms.
\li QMenu objects used in the native menu bar are not able to
handle Qt events via the normal event handlers.
Install a delegate on the menu itself to be notified of these
changes. Alternatively, consider using the QMenu::aboutToShow()
and QMenu::aboutToHide() signals to keep track of menu visibility;
these provide a solution that should work on all platforms
supported by Qt.
\li By default, Qt creates a native \b Quit menu item that will react
to the \c {CMD+Q} shortcut. Creating a QAction for the QAction::QuitRole
role will replace that menu item. Therefore, the replacement action
should be connected to either the QCoreApplication::quit slot, or a
custom slot that stops the application.
\endlist
\section2 Native Widgets
Qt has support for sheets, represented by the window flag, Qt::Sheet.
Usually, when referring to a native \macos application, \e native means an
application that interfaces directly to the underlying window system, rather
than one that uses some intermediary layer. Qt applications run as first
class citizens, just like Cocoa applications. We use Cocoa
internally to communicate with the operating system.
\section2 Symbol visibility warnings
\include apple-hidden-symbols.qdocinc
\section2 dSYM bundle missing in xcarchive created by a CMake Xcode project
\include apple-xcode-dsym-archiving.qdocinc
*/
/*!
\page macos-deployment.html
\title Qt for \macos - Deployment
\brief Describes the deployment process for \macos.
This document describes how to create a \l{Qt for \macos}{\macos} bundle
and make sure that the application finds the resources it needs at run-time.
We demonstrate the procedures in terms of deploying the
\l{tools/plugandpaint/app}{Plug & Paint} example application that comes with
the Qt source package.
The Qt installers for \macos include a \l{macdeployqt}{deployment tool} that
automates the procedures described here.
\section1 The Bundle
On \macos, a GUI application must be built and run from a bundle, which is a
directory structure that appears as a single entity when viewed in the
Finder. A bundle for an application typically contains the executable and
all the resources it needs. Here is the snapshot of an application bundle
structure:
\image deployment-mac-bundlestructure.png
{macOS app bundle structure showing Contents folder with Frameworks,
MacOs, Resources, PlugIns, and configuration files}
The bundle provides many advantages to the user:
\list
\li It is easy to install as it is identified as a single entity.
\li Information about a bundle is accessible from code.
\endlist
This is specific to \macos and beyond the scope of this document. For
more information about bundles, see
\l {https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFBundles/Introduction/Introduction.html#//apple_ref/doc/uid/10000123i-CH1-SW1}{Apple's Developer Website}.
To build your application as a bundle with CMake, set the
{\c {MACOSX_BUNDLE}} property on your executable target:
\code
set_target_properties(plugandpaint PROPERTIES
MACOSX_BUNDLE TRUE
)
\endcode
\c{qmake} automatically generates a bundle for your application. To disable
this, add the following statement to your application's project file
(\c{.pro}):
\snippet snippets/code/doc_src_deployment.pro 26
\section1 Static Linking
If you want to keep things simple and only have a few files to
deploy, you can build your application with statically linked libraries.
\section2 Building Qt Statically
Start by installing a static version of the Qt library. Remember that you
cannot use plugins and that you must build the dependent libraries such
as image formats, SQL drivers, and so on with static linking.
\snippet snippets/code/doc_src_deployment.qdoc 27
You can check the various options that are available by running
\c{configure -help}.
\section2 Linking the Application to the Static Version of Qt
Once Qt is built statically, the next step is to regenerate the build files
and rebuild the application.
\section3 Using CMake
Make sure to use the \c qt_add_executable wrapper command, which provides
additional logic such as linking Qt plugins in static Qt builds.
\include {macos-deploy-cmake.qdocinc} {building with cmake}
\section3 Using qmake
First, go into the directory that contains the application:
\snippet snippets/code/doc_src_deployment.qdoc 28
Then, run \c qmake to create a new makefile for the application, and do
a clean build to create the statically linked executable:
\snippet snippets/code/doc_src_deployment.qdoc 29
You probably want to link against the release libraries, and you can specify
this when invoking \c qmake. You may want to take advantage of "dead code
stripping" to reduce the size of your binary even more. You can do this by
passing \c {LIBS+= -dead_strip} to \c qmake in addition to the
\c {-config release} parameter.
Again, provided that everything compiled and linked without any errors, you
should have a \c plugandpaint.app bundle ready for deployment. Try
installing the bundle on a machine running \macos that does not have Qt or
any Qt applications installed.
\section3 Checking linked libraries
You can check what other libraries your application links to using
the \c otool:
\snippet snippets/code/doc_src_deployment.qdoc 30
Here is what the output looks like for the statically linked
\l {tools/plugandpaint/app}{Plug & Paint}:
\snippet snippets/code/doc_src_deployment.qdoc 31
If you see \e Qt libraries in the output, it probably
means that you have both dynamic and static Qt libraries installed
on your machine. The linker always chooses dynamic linking over
static. If you want to use only static libraries, you can either:
\list
\li move your Qt dynamic libraries (\c .dylibs) away to another directory
while you link the application and then move them back,
\li or edit the \c Makefile and replace link lines for the Qt libraries
with the absolute path to the static libraries.
\endlist
For example, replace the following:
\snippet snippets/code/doc_src_deployment.qdoc 32
with this:
\snippet snippets/code/doc_src_deployment.qdoc 33
The \e {Plug & Paint} example consists of
several components: The core application (\l
{tools/plugandpaint/app}{Plug & Paint}), and the \l
{tools/plugandpaint/plugins/basictools}{Basic Tools} and \l
{tools/plugandpaint/plugins/extrafilters}{Extra Filters}
plugins. As we cannot deploy plugins using the static linking
approach, the bundle we have prepared so far is incomplete. The
application will run, but the functionality will be disabled due
to the missing plugins. To deploy plugin-based applications we
should use the framework approach, which is specific to \macos.
\section1 Frameworks
In this approach, ensure that the Qt runtime is redistributed correctly with
the application bundle, and that the plugins are installed in the correct
location so that the application finds them.
There are two ways to distribute Qt with your application in the frameworks
approach:
\list
\li Private framework within your application bundle.
\li Standard framework (alternatively use the Qt frameworks in
the installed binary).
\endlist
The first option is good if you have Qt built in a special way, or want to
make sure the framework is there. It just comes down to where you place the
Qt frameworks.
The second option is good if you have many Qt applications and you want
them to use a single Qt framework rather than multiple versions of it.
\section2 Building Qt as Frameworks
We assume that you already have installed Qt as frameworks, which
is the default when installing Qt, in the /path/to/Qt
directory. For more information on how to build Qt without Frameworks,
visit the \l{Qt for \macos - Specific Issues} documentation.
When installing, the identification name of the frameworks is set. This
name is used by the dynamic linker (\c dyld) to find the libraries for your
application.
\section2 Linking the Application to Qt as Frameworks
After building Qt as frameworks, we can build the \e {Plug & Paint}
application.
\section3 Using CMake
\include {macos-deploy-cmake.qdocinc} {building with cmake}
\section3 Using qmake
First, go into the directory that contains the application:
\snippet snippets/code/doc_src_deployment.qdoc 34
Run \c qmake to create a new makefile for the application, and do
a clean build to create the dynamically linked executable:
\snippet snippets/code/doc_src_deployment.qdoc 35
This builds the core application. Use the following to build the plugins:
\snippet snippets/code/doc_src_deployment.qdoc 36
Now run the \c otool for the Qt frameworks, for example Qt Gui:
\snippet snippets/code/doc_src_deployment.qdoc 37
You would get the following output:
\snippet snippets/code/doc_src_deployment.qdoc 38
For the Qt frameworks, the first line (i.e. \c
{path/to/Qt/lib/QtGui.framework/Versions/4/QtGui (compatibility
version 4.0.0, current version 4.0.1)}) becomes the framework's
identification name which is used by the dynamic linker (\c dyld).
But when you are deploying the application, your users may not
have the Qt frameworks installed in the specified location. For
that reason, you must either provide the frameworks in an agreed
location, or store the frameworks in the bundle.
Regardless of which solution you choose, you must make sure that
the frameworks return the proper identification name for
themselves, and that the application looks for these names.
Luckily we can control this with the \c install_name_tool
command-line tool.
The \c install_name_tool works in two modes, \c -id and \c
-change. The \c -id mode is for libraries and frameworks, and
allows us to specify a new identification name. We use the \c
-change mode to change the paths in the application.
Let's test this out by copying the Qt frameworks into the Plug &
Paint bundle. Looking at \c otool's output for the bundle, we can
see that we must copy both the QtCore and QtGui frameworks into
the bundle. We will assume that we are in the directory where we
built the bundle.
\snippet snippets/code/doc_src_deployment.qdoc 39
First we create a \c Frameworks directory inside the bundle. This
follows the \macos application convention. We then copy the
frameworks into the new directory. As frameworks contain
symbolic links, we use the \c -R option.
\snippet snippets/code/doc_src_deployment.qdoc 40
Then we run \c install_name_tool to set the identification names
for the frameworks. The first argument after \c -id is the new
name, and the second argument is the framework that we want to
rename. The text \c @executable_path is a special \c dyld variable
telling \c dyld to start looking where the executable is located. The new
names specifies that these frameworks are located in the directory directly
under the \c Frameworks directory.
\snippet snippets/code/doc_src_deployment.qdoc 41
Now, the dynamic linker knows where to look for QtCore and
QtGui. We must ensure that the application also knows where to find the
library, using \c install_name_tool's \c -change mode.
This basically comes down to string replacement, to match the
identification names that we set earlier to the frameworks.
Finally, the QtGui framework depends on QtCore, so we must
remember to change the reference for QtGui:
\snippet snippets/code/doc_src_deployment.qdoc 42
After this, we run \c otool again and see that the
application can find the libraries.
The plugins for the \e {Plug & Paint} example makes it interesting. The
basic steps we need to follow with plugins are:
\list
\li put the plugins inside the bundle,
\li run the \c install_name_tool to check whether the plugins are using
the correct library,
\li and ensure that the application knows where to look for the plugins.
\endlist
We can put the plugins anywhere we want in the bundle, but the
best location is to put them under Contents/Plugins. When we built
the Plug & Paint plugins, based on the \c DESTDIR variable in their \c .pro
file, the plugins' \c .dylib files are in the \c plugins subdirectory
under the \c plugandpaint directory. We just have to move this directory
to the correct location.
\snippet snippets/code/doc_src_deployment.qdoc 43
For example, If we run \c otool on the \l
{tools/plugandpaint/plugins/basictools}{Basic Tools} plugin's \c
.dylib file, we get the following information.
\snippet snippets/code/doc_src_deployment.qdoc 44
Then we can see that the plugin links to the Qt frameworks it was
built against. As we want the plugins to use the framework in
the application bundle, we change them the same way as we did for
the application. For example for the Basic Tools plugin:
\snippet snippets/code/doc_src_deployment.qdoc 45
We must also modify the code in \c
tools/plugandpaint/mainwindow.cpp to \l {QDir::cdUp()}{cdUp()} to ensure
that the application finds the plugins. Add the following
code to the \c mainwindow.cpp file:
\snippet snippets/code/doc_src_deployment.qdoc 46
\table
\row
\li \inlineimage deployment-mac-application.png
{macOS Finder showing the deployed app bundle with plugin folders}
\li
The additional code in \c tools/plugandpaint/mainwindow.cpp also
enables us to view the plugins in the Finder, as shown in the image.
We can also add plugins extending Qt, for example adding SQL
drivers or image formats. We just need to follow the directory
structure outlined in plugin documentation, and make sure they are
included in the QCoreApplication::libraryPaths(). Let's quickly do
this with the image formats, following the procedure outlined earlier.
Copy Qt's image format plugins into the bundle:
\snippet snippets/code/doc_src_deployment.qdoc 47
Use \c install_name_tool to link the plugins to the frameworks in
the bundle:
\snippet snippets/code/doc_src_deployment.qdoc 48
Update the source code in \c tools/plugandpaint/main.cpp
to look for the new plugins. After constructing the
QApplication, we add the following code:
\snippet snippets/code/doc_src_deployment.cpp 49
First, we tell the application to only look for plugins in this
directory. In our case, we want the application to look for only those
plugins that we distribute with the bundle. If we
were part of a bigger Qt installation we could have used
QCoreApplication::addLibraryPath() instead.
\endtable
\warning While deploying plugins, we make changes to the
source code and that resets the default identification names when
the application is rebuilt. So you must repeat the process of
making your application link to the correct Qt frameworks in the bundle
using \c install_name_tool.
Now you should be able to move the application to another \macos
machine and run it without Qt installed. Alternatively, you can
move your frameworks that live outside of the bundle to another
directory and see if the application still runs.
If you store the frameworks in another location outside the
bundle, the technique of linking your application is similar; you
must make sure that the application and the frameworks agree where
to be looking for the Qt libraries as well as the plugins.
\section2 Creating the Application Package
When you are done linking your application to Qt, either
statically or as frameworks, the application is ready to be
distributed. For more information, refer to the
Although the process of deploying an application does have some
pitfalls, once you know the various issues you can easily create
packages that all your \macos users will enjoy.
\section1 Application Dependencies
\section2 Qt Plugins
All Qt GUI applications require a plugin that implements the \l {Qt
Platform Abstraction} (QPA) layer in Qt. For \macos, the name of the
platform plugin is \c {libqcocoa.dylib}. This file must be located within a
specific subdirectory (by default, \c platforms) under your distribution
directory. Alternatively, it is possible to adjust the search path Qt
uses to find its plugins, as described below.
Your application may also depend on one or more Qt plugins, such as the JPEG
image format plugin or a SQL driver plugin. Be sure to distribute any Qt
plugins that you need with your application. Similar to the platform plugin,
each type of plugin must be located within a specific subdirectory (such as
\c imageformats or \c sqldrivers) in your distribution directory.
The search path for Qt plugins (as well as a few other paths) is
hard-coded into the QtCore library. By default, the first plugin
search path will be hard-coded as \c /path/to/Qt/plugins. But
using pre-determined paths has certain disadvantages. For example,
they may not exist on the target machine. So you must check
various alternatives to ensure that the Qt plugins are found:
\list
\li \l{qt-conf.html}{Using \c qt.conf}. This is the recommended
approach as it provides the most flexibility.
\li Using QApplication::addLibraryPath() or
QApplication::setLibraryPaths().
\li Using a third party installation utility to change the
hard-coded paths in the QtCore library.
\endlist
The \l{How to Create Qt Plugins} document outlines the issues you
need to pay attention to when building and deploying plugins for
Qt applications.
\section2 Additional Libraries
You can check which libraries your application is linking against
by using \c otool. Run this with the application path as an argument:
\snippet snippets/code/doc_src_deployment.qdoc 50
Compiler-specific libraries rarely have to be redistributed with your
application. But there are several ways to deploy applications, as Qt can be
configured, built, and installed in several ways on \macos. Typically your
goals help determine how you are going to deploy the application. The last
sections describe a few things that you must be aware of while deploying
your application.
\section1 The macOS Deployment Tool
\target macdeployqt
The macOS deployment tool can be found at \c{QTDIR/bin/macdeployqt}. It is
designed to automate the process of creating a deployable
application bundle that contains Qt libraries as private frameworks.
The macOS deployment tool also deploys the Qt plugins, according
to the following rules (unless \c {-no-plugins} option is used):
\list
\li The platform plugin is always deployed.
\li Debug versions of the plugins are not deployed.
\li The designer plugins are not deployed.
\li The image format plugins are always deployed, except the SVG image
format plugin which is only deployed if the application uses the \l{Qt SVG} module.
\li The icon engine plugins are always deployed.
\li The print support plugin is always deployed.
\li SQL driver plugins are deployed if the application uses the \l{Qt SQL} module.
\li The accessibility plugin is always deployed.
\li The style plugin is always deployed.
\endlist
\important If you choose to not use the Mac Deployment Tool, you must
ensure that your deployment package includes these plugins.
To include a 3rd party library in the application bundle, copy the library
into the bundle manually, after the bundle is created.
\c macdeployqt supports the following options:
\table
\header
\li Option
\li Description
\row
\li \c{-verbose=<0-3>}
\li 0 = no output, 1 = error/warning (default), 2 = normal, 3 = debug
\row
\li \c{-no-plugins}
\li Skip plugin deployment
\row
\li \c{-dmg}
\li Create a .dmg disk image
\row
\li \c{-no-strip}
\li Don't run 'strip' on the binaries
\row
\li \c{-use-debug-libs}
\li Deploy with debug versions of frameworks and plugins (implies
\c{-no-strip})
\row
\li \c{-executable=<path>}
\li Let the given executable also use the deployed frameworks
\row
\li \c{-qmldir=<path>}
\li Deploy imports used by .qml files in the given path
\row
\li \c{-qmlimport=<path>}
\li Add the given path to the QML imports search locations
\row
\li \c{-always-overwrite}
\li Copy files even if the target file exists
\row
\li \c{-codesign=<ident>}
\li Run \c codesign with the given identity on all executables.
By default, ad-hoc signing (\c{-codesign=-}) is used.
\row
\li \c{-no-codesign}
\li Disable code signing
\row
\li \c{-hardened-runtime}
\li Enable Hardened Runtime when code signing
\row
\li \c{-timestamp}
\li Include a secure timestamp when code signing (requires internet connection)
\row
\li \c{-sign-for-notarization=<ident>}
\li Activate the necessary options for notarization (requires internet connection). The activated options are \c{-hardened-runtime}, \c{-timestamp} and \c{-codesign=<ident>}
\row
\li \c{-appstore-compliant}
\li Skip deployment of components that use private API
\row
\li \c{-libpath=<path>}
\li Add the given path to the library search path
\row
\li \c{-fs=<filesystem>}
\li Set the filesystem used for the .dmg disk image (defaults to HFS+)
\endtable
\note macOS High Sierra introduced the new Apple File System (APFS). Older
versions of macOS cannot read .dmg files that are formatted with APFS. By
default, \c macdeployqt uses the older HFS+ file system for compatibility
with all versions of macOS currently supported by Qt. Use the \c{-fs} option
to specify a different file system.
\section1 Volume Name
The volume name of a disk image (the text displayed in the window title of
an opened \c .dmg file) created with \c -dmg is based on the path to the
application when \c macdeployqt is run. For example, consider the following
command that creates a disk image for a Qt Quick application:
\badcode
macdeployqt /Users/foo/myapp-build/MyApp.app -qmldir=/Users/foo/myapp/qml -dmg
\endcode
The resulting volume name will be:
\badcode
/Users/foo/myapp-build/MyApp.app
\endcode
To ensure that the volume name only contains the application name and not
the path on the deployment machine, run \c macdeployqt in the same
directory:
\badcode
cd /Users/foo/myapp-build
macdeployqt MyApp.app -qmldir=/Users/foo/myapp/qml -dmg
\endcode
The resulting volume name will then be:
\badcode
MyApp.app
\endcode
\section1 Entitlements
When signing, \c macdeployqt will automatically use the first .entitlements file it finds
in the Contents/Resources/ subdirectory in the application bundle if present. To prevent errors,
ensure that there is at maximum one .entitlements file in this folder.
*/
/*!
\page macos-installation.html
\title Qt for \macos - Alternative ways of installing Qt
\brief This article explains how to install Qt on macOS using \QOI and Homebrew.
\section1 Overview
You can install the Qt Framework, design, and development tools on \macos from
these sources:
\list
\li Using the \l{Get and Install Qt with \QOI}{\QOI} (Recommended).
\list
\li Gives you access to latest versions of Qt, on the day of their release.
\li Allows you to install older versions of Qt, in parallel to newer ones.
\li Features all Qt modules, including commercial-only ones.
\li Preconfigures Qt versions in \QC and \QDS.
\li Allows you to browse the Qt documentation and examples locally.
\endlist
\QOI is full-featured, flexible, and fully supports commercial use cases. It
is also the one supported best by The Qt Company and The Qt Project. We
recommend it if you plan to develop with Qt, or bundle Qt as part of
application.
\li Using the Homebrew package manager.
\list
\li Does not require a Qt Account.
\li Installs a recent version of Qt 6 (though not always the latest one).
\li Allows you to install most (but not all) Qt modules.
\li Does not provide a local version of the Qt documentation or examples.
\li Allows you to share third-party modules with other libraries and
applications.
\endlist
Homebrew is lightweight and good for automation. Homebrew works great if you
need to install Qt as a dependency for a \macos application, but do not plan
to do development work with Qt yourself, nor need special or commercial-only
Qt modules.
\endlist
\section1 Installing Qt Using the \QOI
See \l{Get and Install Qt with \QOI} for information about how to use \QOI.
\section1 Installing Qt using Homebrew
To install Qt, \QC, and \QDS with Homebrew, install Homebrew first using the
a terminal:
\code
brew install qt
brew install --cask qt-creator
brew install --cask qt-design-studio
\endcode
When you start \QC, \QVSC, or \QDS, you need to set the path to the Qt version
installed by Homebrew. By default, Homebrew installs Qt in
\c {/opt/homebrew/Cellar/qt/<version>/}.
For more information on setting up a Qt Kit:
\list
\li For \QC, see \l{\QC: Add Qt versions}.
\li For \QVSC, see \l{\QVSC: Register Qt installations}.
\endlist
\image link-qt-kit.webp {Choose a linked Qt Kit in Qt Creator}
*/