| /**************************************************************************** |
| ** |
| ** Copyright (C) 2019 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** Alternatively, this file may be used under the terms of the GNU Free |
| ** Documentation License version 1.3 as published by the Free Software |
| ** Foundation and appearing in the file included in the packaging of |
| ** this file. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \page macos.html |
| \title Qt for macOS |
| \brief Platform support for \macos. |
| \keyword Qt for macOS |
| \ingroup supportedplatform |
| |
| \macos (previously known as OS X or Mac OS X) is Apple's operating system |
| for the Mac line of computers. It's a UNIX platform, based on the Darwin |
| kernel, and behaves largely similar to other UNIX-like platforms. |
| The main difference is that X11 is not used as the windowing system. |
| Instead, \macos uses its own native windowing system that is accessible |
| through the Cocoa API. |
| |
| To download and install Qt for \macos, follow the instructions on the |
| \l{Getting Started with Qt} page. |
| |
| \target macos-supported-versions |
| \section1 Supported Versions |
| |
| When talking about version support on \macos, it's important to distinguish |
| between the \l {Build Environment}{build environment}; the platform you're building on |
| or with, and the \l {Target Platforms}{target platforms}; the platforms you are building |
| for. The following macOS versions are supported. |
| |
| \include supported-platforms.qdocinc macos |
| |
| \section2 Build Environment |
| |
| The build environment on \macos is defined \e entirely by the Xcode version used |
| to build your application. Xcode contains both a toolchain (compiler, linker, and other |
| tools), and a \macos platform-SDK (headers and libraries). Together these define how |
| your application is built. |
| |
| \note The version of \macos that you are \e running Xcode on does not matter. As long as |
| Apple ships a given Xcode version that runs on your operating system, the build |
| environment will be defined by that Xcode version. |
| |
| Xcode can be downloaded from Apple's \l{https://developer.apple.com/download/}{developer |
| website} (including older versions of Xcode). Once installed, choosing an Xcode installation |
| is done using the \c{xcode-select} tool. |
| |
| \code |
| $ sudo xcode-select --switch /Applications/Xcode.app |
| \endcode |
| |
| You can inspect the globally selected Xcode installation using the same tool. |
| |
| \code |
| $ xcode-select -print-path |
| /Applications/Xcode.app/Contents/Developer |
| \endcode |
| |
| The \c xcrun command can then be used to find a particular tool in the toolchain. |
| |
| \code |
| $ xcrun -sdk macosx -find clang |
| /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang |
| \endcode |
| |
| or show the platform SDK path used when building. |
| |
| \code |
| $ xcrun -sdk macosx --show-sdk-path |
| /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.14.sdk |
| \endcode |
| |
| \section2 Target Platforms |
| |
| Building for \macos utilizes a technique called \e{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 \e{deployment target} of your application. If the binary is launched on a \macos version |
| below the deployment target macOS or Qt will give an error message and the application will |
| not run. |
| |
| Qt expresses the deployment target via the \c QMAKE_MACOSX_DEPLOYMENT_TARGET qmake |
| variable, which has a default value set via the makespec for \macos. You should not |
| need to change this default, but if needed you can increase it in your project file: |
| |
| \code |
| QMAKE_MACOSX_DEPLOYMENT_TARGET = 10.13 |
| \endcode |
| |
| \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 then deployed to a |
| \macos version lower than what Qt expected to run on. |
| |
| By always building against the latest available platform SDK, you ensure that |
| Qt can take advantage of new features introduced in recent versions of \macos. |
| |
| For more information about SDK-based development on \macos, see Apple's \l |
| {https://developer.apple.com/library/mac/#documentation/DeveloperTools/Conceptual/cross_development/Introduction/Introduction.html}{developer documentation}. |
| |
| \section3 Opting out of \macos behavior changes |
| |
| One caveat to using the latest Xcode version and SDK to build your application |
| is that \macos's system frameworks will sometimes decide whether or not to |
| enable behavior changes based on the SDK you built your application with. |
| |
| 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. This technique allows Apple to ensure that binaries built long before |
| the new SDK and operating system was released will still continue to run without |
| regressions on new \macos releases. |
| |
| A consequence of this is that if Qt has problems dealing with some of these |
| \macos features (dark-mode, layer-backed views), the only way to opt out of |
| them is building with an earlier SDK (the 10.13 SDK, available through |
| Xcode 9). This is a last-resort solution, and should only be applied if your |
| application has no other ways of working around the problem. |
| |
| \section2 Architectures |
| |
| By default, Qt is built for x86_64. To build for x86_64h (Haswell). use the |
| \c QMAKE_APPLE_DEVICE_ARCHS \c qmake variable. |
| This is selectable at configure time: |
| \code |
| ./configure -platform macx-clang QMAKE_APPLE_DEVICE_ARCHS=x86_64h |
| \endcode |
| |
| \c QMAKE_APPLE_DEVICE_ARCHS can also be specified as a space-delimited list |
| in order to build for multiple architectures simultaneously: |
| \code |
| ./configure -platform macx-clang QMAKE_APPLE_DEVICE_ARCHS="x86_64 x86_64h" |
| \endcode |
| |
| \section1 Additional Command-Line Options |
| |
| On the command-line, applications can be built using \c qmake and \c make. |
| Optionally, \c qmake can generate project files for Xcode with |
| \c{-spec macx-xcode}. If you are using the binary package, \c qmake |
| generates Xcode projects by default; use \c{-spec macx-gcc} to generate |
| makefiles. For example: |
| |
| \snippet snippets/code/doc_src_qtmac-as-native.qdoc 0 |
| |
| Configuring with \c{-spec macx-xcode} generates an Xcode project file from |
| project.pro. With \l qmake you do not have to worry about rules for Qt's |
| preprocessors (\l moc and \l uic) since \l qmake automatically handles them |
| and ensures that everything necessary is linked into your application. |
| |
| Qt does not entirely interact with the development environment (for |
| example plugins to set a file to "mocable" from within the Xcode |
| user interface). |
| |
| The result of the build process is an application bundle, which is a |
| directory structure that contains the actual application executable. The |
| application can be launched by double-clicking it in Finder, or by |
| referring directly to its executable from the command line, for example, |
| \c{myApp.app/Contents/MacOS/myApp}. |
| |
| If you wish to have a command-line tool that does not use the GUI for |
| example, \c moc, \c uic or \c ls, you can tell qmake to disable bundle |
| creation from the \c{CONFIG} variable in the project file: |
| |
| \code |
| CONFIG -= app_bundle |
| \endcode |
| |
| \section1 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. |
| |
| 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. Qt 5 aims |
| to stay within the app store sandbox rules. macdeployqt (bin/macdeployqt) |
| can be used as a starting point for app store deployment. |
| |
| \list |
| \li \l{Qt for macOS - Deployment} |
| \endlist |
| |
| \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 \macos Issues |
| |
| The page below covers specific issues and recommendations for creating |
| \macos applications. |
| \list |
| \li \l{Qt for macOS - Specific Issues} |
| \endlist |
| |
| \section1 Where to Go from Here |
| |
| We invite you to explore the rest of Qt. We prepared overviews to help |
| you decide which APIs to use and our examples demonstrate how to use our |
| API. |
| |
| \list |
| \li \l{Qt Overviews} - list of topics about application development |
| \li \l{Qt Examples and Tutorials}{Examples and Tutorials} - code samples and tutorials |
| \li \l{Qt Reference Pages} - a listing of C++ and QML APIs |
| \endlist |
| |
| Qt's vibrant and active community site, \l{http://qt.io} houses |
| a wiki, a forum, and additional learning guides and presentations. |
| |
| */ |
| |
| /*! |
| \page macos-building.html |
| \title Qt for macOS - Building from Source |
| \brief How to install Qt on \macos. |
| |
| \section1 Requirements |
| |
| Qt requires a macOS platform SDK and corresponding toolchain to be installed |
| on the system. You can get this by installing the Xcode command line tools: |
| |
| \code |
| xcode-select --install |
| \endcode |
| |
| Or by downloading and installing \l{https://developer.apple.com/xcode/}{Xcode}. |
| |
| \section2 Compiler Versions |
| |
| Qt for macOS is tested and compatible with several versions of GCC (GNU |
| Compiler Collection) and Clang (as available from Xcode). For a list of |
| tested configurations, refer to the \e{Reference Configuration} section of |
| the \l{Supported Platforms#Reference Configurations}{supported platforms} |
| page. |
| |
| \section1 QDoc Dependencies |
| |
| Since version 5.11, \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 5 sources from the \l{Downloads} page. For |
| more information, visit the \l{Getting Started with Qt} page. |
| |
| \section2 Step 1: Install the License File (Commercially Licensed Qt Only) |
| |
| If you use Qt with a commercial license, the Qt tools look for a local license file. |
| If you are using a binary installer or the commercial Qt Creator, your licenses |
| are automatically fetched and stored in your local user profile |
| (\c{$HOME/Library/Application Support/Qt/qtlicenses.ini} file). |
| |
| If you do not use any binary installer or Qt Creator, you can download |
| the respective license file from your \l {Qt Account} Web portal and save |
| it to your user profile as \c{$HOME/.qt-license}. If you prefer a |
| different location or file name, you need to set the \c{QT_LICENSE_FILE} |
| environment variable to the respective file path. |
| |
| \section2 Step 2: Unpack the Archive |
| |
| Unpack the archive if you have not done so already. For example, |
| if you have the \c{qt-everywhere-opensource-src-%VERSION%.tar.gz} |
| package, type the following commands at a command line prompt: |
| |
| \snippet snippets/code/doc_src_installation.qdoc 11 |
| |
| This creates the directory \c{/tmp/qt-everywhere-opensource-src-%VERSION%} |
| containing the files from the archive. |
| |
| \section2 Step 3: Build the Qt Library |
| |
| To configure the Qt library for your machine type, run the |
| \c{./configure} script in the package directory. |
| |
| By default, Qt is configured for installation in the |
| \c{/usr/local/Qt-%VERSION%} directory, but this can be |
| changed by using the \c{-prefix} option. |
| |
| \snippet snippets/code/doc_src_installation.qdoc 12 |
| |
| 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. |
| |
| 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. |
| |
| \note There is a potential race condition when running make install with multiple |
| jobs. It is best to only run one make job (-j1) for the install. |
| |
| \section2 Step 4: 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), 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.} |
| |
| \section1 Step 5: Build the Qt Documentation |
| |
| For the Qt reference documentation to be available in \l {Qt Assistant}, you |
| must build it separately: |
| |
| \snippet snippets/code/doc_src_installation.qdoc 24 |
| |
| \section1 Limitations |
| |
| \section2 Fink |
| |
| If you have installed the Qt for X11 package from \l{http://www.finkproject.org/}{Fink}, |
| it will set the \c QMAKESPEC environment variable to \c darwin-g++. This will cause |
| problems when you build the Qt for macOS package. To fix this, simply unset your \c |
| QMAKESPEC or set it to \c macx-g++ before you run \c configure. To get a |
| fresh Qt distribution, run \c{make confclean} on the command-line. |
| */ |
| |
| /*! |
| \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 |
| \l{https://developer.apple.com/}. |
| |
| \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. |
| |
| \section2 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_MacPluginApplication |
| \li Qt::AA_DontUseNativeMenuBar |
| \li Qt::AA_MacDontSwapCtrlAndMeta |
| \li Qt::WA_MacNoClickThrough |
| \li Qt::WA_MacOpaqueSizeGrip |
| \li Qt::WA_MacShowFocusRect |
| \li Qt::WA_MacNormalSize |
| \li Qt::WA_MacSmallSize |
| \li Qt::WA_MacMiniSize |
| \li Qt::WA_MacVariableSize |
| \li Qt::WA_MacBrushedMetal |
| \li Qt::WA_MacAlwaysShowToolWindow |
| \li Qt::WA_MacFrameworkScaled |
| \li Qt::WA_MacNoShadow |
| \li Qt::Sheet |
| \li Qt::Drawer |
| \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. |
| |
| \section2 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. |
| |
| \section2 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}. |
| |
| \section2 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. |
| |
| \section2 Dock |
| |
| Interaction with the dock is possible. The icon can be set by calling |
| QWindow::setWindowIcon() from the main window in your application. The |
| setWindowIcon() call can be made as often as necessary, providing an |
| icon that can be easily updated. |
| |
| \section2 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{The Mac Deployment Tool}{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 |
| \l{http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/index.html} |
| {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 |
| \l{http://developer.apple.com/technotes/tn2004/tn2124.html#SECJUSTONELIB} |
| {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. |
| |
| If you are using older versions of GDB you must run with the full |
| path to the executable. Later versions allow you to pass the |
| bundle name on the command line. |
| |
| \section2 Combining Libraries |
| |
| If you want to build a new dynamic library combining the Qt 4 |
| 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. |
| |
| If you want to define code for specific versions of \macos, use |
| the availability macros defined in \e{/usr/include/AvailabilityMacros.h}. |
| |
| The QSysInfo 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 |
| |
| \note When \macos is set to use Japanese, a bug causes this sequence |
| to fail and return an empty string. Therefore, always test the |
| returned string. |
| |
| For more information about using the CFBundle API, visit |
| \l{http://developer.apple.com/documentation/CoreFoundation/Reference/CFBundleRef/index.html} |
| {Apple's Developer Website}. |
| |
| QCoreApplication::applicationDirPath() can be used to determine |
| the path of the binary within the bundle. |
| |
| \section2 Translating the Application Menu and Native Dialogs |
| |
| The items in the Application Menu will be merged correctly for |
| localized applications, but they will not show up translated |
| until the application bundle contains a localized resource folder. |
| to the application bundle. |
| |
| Essentially, there needs to be a file called |
| \e locversion.plist. Here is an example of an application with Norwegian |
| localization: |
| |
| \snippet snippets/code/doc_src_mac-differences.qdoc 2 |
| |
| Afterwards, when the application is run with the preferred language set to |
| Norwegian, the menu items should display \gui Avslutt instead of \gui Quit. |
| |
| The \l{http://developer.apple.com/library/mac/#documentation/CoreFoundation/Conceptual/CFBundles/BundleTypes/BundleTypes.html#//apple_ref/doc/uid/10000123i-CH101-SW13}{Bundle Programming Guide} |
| contains information about bundles and the localized resource folder. |
| |
| \section2 Mixing Qt with Native Code |
| |
| Two classes are available for adding native Cocoa views and controls |
| inside a Qt application, or for embedding Qt into a native |
| Cocoa application: QMacCocoaViewContainer, and QMacNativeWidget. |
| |
| \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. |
| |
| */ |
| |
| /*! |
| \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 installation package. |
| |
| The Qt installers for \macos include a \l |
| {macdeploy}{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 |
| |
| The bundle provides many advantages to the user: |
| \list |
| \li It is easily installable 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 {http://developer.apple.com/documentation/CoreFoundation/Conceptual/CFBundles/index.html}{Apple's Developer Website}. |
| |
| \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 have a few files to |
| deploy, you must 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 |
| makefile and rebuild the application. First, we must go into the |
| directory that contains the application: |
| |
| \snippet snippets/code/doc_src_deployment.qdoc 28 |
| |
| Now 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. If you have Xcode Tools |
| 1.5 or higher installed, 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. |
| |
| Now, provided that everything compiled and linked without any |
| errors, we 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. |
| |
| 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 \l {tools/plugandpaint/app}{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 former 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 latter option is good if you have many Qt applications and you want |
| them 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 \l |
| {tools/plugandpaint/app}{Plug & Paint} application. First, we must go |
| to 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 \l {tools/plugandpaint/app}{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 |
| \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 |
| \l {https://developer.apple.com/}{Apple Developer} website. |
| |
| Although the process of deploying an application do 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 5. 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. |
| |
| \section2 \macos Version Dependencies |
| |
| \include expressing-apple-os-versions.qdocinc expressing os versions |
| |
| \section1 The Mac Deployment Tool |
| \target macdeploy |
| The Mac deployment tool can be found in QTDIR/bin/macdeployqt. It is |
| designed to automate the process of creating a deployable |
| application bundle that contains the Qt libraries as private |
| frameworks. |
| |
| The mac 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. |
| \li The print support plugin is always deployed. |
| \li SQL driver plugins are deployed if the application uses the \l{Qt SQL} module. |
| \li Script plugins are deployed if the application uses the \l{Qt Script} module. |
| \li The SVG icon plugin is deployed if the application uses the \l{Qt SVG} module. |
| \li The accessibility plugin is always deployed. |
| \endlist |
| |
| 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 |
| \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 |
| */ |
| |