This document describes how to create a bundle and make sure that the application finds the resources it needs at run-time. We demonstrate the procedures in terms of deploying the example application that comes with the Qt installation package.The Qt installers for macOS include a that automates the procedures described here. The BundleOn 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:The bundle provides many advantages to the user:. It is easily installable as it is identified as a single entity. Information about a bundle is accessible from code.This is specific to macOS and beyond the scope of this document.
![]()
I am having problems packaging my Qt app for Mac OS X using macdeployqt. On my Mac, I have Qt5 installed on /Qt5.1.0/5.1.0/clang64 (this is where the bin/ and lib/ folder resides) I have a Qt. The Qt release target for the fixes is the 5.12 branch, which has a couple of implications for Qt users: We encourage upgrading to Qt 5.12 to get fixes for macOS 10.14; The maximum supported Xcode version for Qt 5.11 and lower is Xcode 9 (SDK 10.13) The latter point may require further explanation.
For more information about bundles, see.qmake automatically generates a bundle for your application. To disable this, add the following statement to your application's project file (.pro). Make cleanqmake -config releasemakeYou probably want to link against the release libraries, and you can specify this when invoking 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 LIBS+= -deadstrip to qmake in addition to the -config release parameter.Now, provided that everything compiled and linked without any errors, we should have a 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 otool. Plugandpaint.app /Contents /MacOS /plugandpaint:/System /Library /Frameworks /Carbon.framework /Versions /A /Carbon(compatibility version 2.0.0, current version 128.0.0)/System /Library /Frameworks /QuickTime.framework /Versions /A /QuickTime(compatibility version 1.0.0, current version 10.0.0)/usr /lib /libz. 1.dylib(compatibility version 1.0.0, current version 1.2.3)/System /Library /Frameworks /ApplicationServices.framework /Versions /A /ApplicationServices(compatibility version 1.0.0, current version 22.0.0)/usr /lib /libstdc + +. 6.dylib(compatibility version 7.0.0, current version 7.3.0)/usr /lib /libgccs. 1.dylib(compatibility version 1.0.0, current version 1.0.0)/usr /lib /libmx.A.dylib(compatibility version 1.0.0, current version 92.0.0)/usr /lib /libSystem.B.dylib(compatibility version 1.0.0, current version 88.0.0)If you see 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:. move your Qt dynamic libraries (.dylibs) away to another directory while you link the application and then move them back,. or edit the Makefile and replace link lines for the Qt libraries with the absolute path to the static libraries.For example, replace the following. /where / static /qt /lib /is /libQtGui.aThe example consists of several components: The core application , and the and 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. FrameworksIn 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:.
Private framework within your application bundle. Standard framework (alternatively use the Qt frameworks in the installed binary).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. Building Qt as FrameworksWe 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 documentation.When installing, the identification name of the frameworks is set. This name is used by the dynamic linker ( dyld) to find the libraries for your application. Linking the Application to Qt as FrameworksAfter building Qt as frameworks, we can build the application.
First, we must go to the directory that contains the application.framework /:/path /to / /lib /.framework /Versions / 4.0 /(compatibility version 4.0.0, current version 4.0.1)/System /Library /Frameworks /Carbon.framework /Versions /A /Carbon(compatibility version 2.0.0, current version 128.0.0)/System /Library /Frameworks /QuickTime.framework /Versions /A /QuickTime(compatibility version 1.0.0, current version 10.0.0)/path /to / /.framework /Versions / 4.0 /(compatibility version 4.0.0, current version 4.0.1)/usr /lib /libz. 1.dylib(compatibility version 1.0.0, current version 1.2.3)/System /Library /Frameworks /ApplicationServices.framework /Versions /A /ApplicationServices(compatibility version 1.0.0, current version 22.0.0)/usr /lib /libstdc + +. 6.dylib(compatibility version 7.0.0, current version 7.3.0)/usr /lib /libgccs.
1.dylib(compatibility version 1.0.0, current version 1.0.0)/usr /lib /libmx.A.dylib(compatibility version 1.0.0, current version 92.0.0)/usr /lib /libSystem.B.dylib(compatibility version 1.0.0, current version 88.0.0)For the Qt frameworks, the first line (i.e. 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 ( 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 installnametool command-line tool.The installnametool works in two modes, -id and -change. The -id mode is for libraries and frameworks, and allows us to specify a new identification name. We use the -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 otool's output for the bundle, we can see that we must copy both the and frameworks into the bundle. We will assume that we are in the directory where we built the bundle. Installnametool -id @executablepath /. /Frameworks /.framework /Versions / 4.0 /plugandpaint.app /Contents /Frameworks /.framework /Versions / 4.0 /installnametool -id @executablepath /.
/Frameworks /.framework /Versions / 4.0 /plugandpaint.app /Contents /Frameworks /.framework /Versions / 4.0 /Then we run installnametool to set the identification names for the frameworks. The first argument after -id is the new name, and the second argument is the framework that we want to rename.
The text @executablepath is a special dyld variable telling dyld to start looking where the executable is located. The new names specifies that these frameworks are located in the directory directly under the Frameworks directory. Installnametool -change path /to / /lib /.framework /Versions / 4.0 /@executablepath /. /Frameworks /.framework /Versions / 4.0 /plugandpaint.app /Contents /MacOs /plugandpaintinstallnametool -change path /to /qt /lib /.framework /Versions / 4.0 /@executablepath /.
/Frameworks /.framework /Versions / 4.0 /plugandpaint.app /Contents /MacOs /plugandpaintNow, the dynamic linker knows where to look for. We must ensure that the application also knows where to find the library, using installnametool's -change mode. This basically comes down to string replacement, to match the identification names that we set earlier to the frameworks.Finally, the framework depends on, so we must remember to change the reference for. Installnametool -change path /to / /lib /.framework /Versions / 4.0 /@executablepath /. /Frameworks /.framework /Versions / 4.0 /plugandpaint.app /Contents /Frameworks /.framework /Versions / 4.0 /After this, we run otool again and see that the application can find the libraries.The plugins for the example makes it interesting. The basic steps we need to follow with plugins are:.
put the plugins inside the bundle,. run the installnametool to check whether the plugins are using the correct library,. and ensure that the application knows where to look for the plugins.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 DESTDIR variable in their.pro file, the plugins'.dylib files are in the plugins subdirectory under the plugandpaint directory. We just have to move this directory to the correct location. Libpnpbasictools.dylib:libpnpbasictools.dylib(compatibility version 0.0.0, current version 0.0.0)/path /to / /lib /.framework /Versions / 4.0 /(compatibility version 4.0.0, current version 4.0.1)/System /Library /Frameworks /Carbon.framework /Versions /A /Carbon(compatibility version 2.0.0, current version 128.0.0)/System /Library /Frameworks /QuickTime.framework /Versions /A /QuickTime(compatibility version 1.0.0, current version 10.0.0)/path /to / /lib /.framework /Versions / 4.0 /(compatibility version 4.0.0, current version 4.0.1)/usr /lib /libz.
1.dylib(compatibility version 1.0.0, current version 1.2.3)/System /Library /Frameworks /ApplicationServices.framework /Versions /A /ApplicationServices(compatibility version 1.0.0, current version 22.0.0)/usr /lib /libstdc + +. 6.dylib(compatibility version 7.0.0, current version 7.3.0)/usr /lib /libgccs. 1.dylib(compatibility version 1.0.0, current version 1.0.0)/usr /lib /libmx.A.dylib(compatibility version 1.0.0, current version 92.0.0)/usr /lib /libSystem.B.dylib(compatibility version 1.0.0, current version 88.0.0)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. Installnametool -change /path /to / /lib /.framework /Versions / 4.0 /@executablepath /. /Frameworks /.framework /Versions / 4.0 /plugandpaint.app /Contents /plugins /libpnpbasictools.dylibinstallnametool -change /path /to / /lib /.framework /Versions / 4.0 /@executablepath /. /Frameworks /.framework /Versions / 4.0 /plugandpaint.app /Contents /plugins /libpnpbasictools.dylibWe must also modify the code in tools/plugandpaint/mainwindow.cpp to to ensure that the application finds the plugins. Add the following code to the mainwindow.cpp file.
The additional code in 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. Let's quickly do this with the image formats, following the procedure outlined earlier.Copy Qt's image format plugins into the bundle: cp -R /path /to / /plugins /imageformatspluginandpaint.app /Contents /pluginsUse installnametool to link the plugins to the frameworks in the bundle: installnametool -change /path /to / /lib /.framework /Versions / 4.0 /@executablepath /. /Frameworks /.framework /Versions / 4.0 /plugandpaint.app /Contents /plugins /imageformats /libqjpeg.dylibinstallnametool -change /path /to / /lib /.framework /Versions / 4.0 /@executablepath /. /Frameworks /.framework /Versions / 4.0 /plugandpaint.app /Contents /plugins /imageformats /libqjpeg.dylibUpdate the source code in tools/plugandpaint/main.cpp to look for the new plugins. After constructing the, we add the following code: dir(::applicationDirPath);dir.cdUp;dir.cd( 'plugins');::setLibraryPaths( (dir.absolutePath));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 instead.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 installnametool.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. Creating the Application PackageWhen 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 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. Application Dependencies Qt PluginsAll Qt GUI applications require a plugin that implements the (QPA) layer in Qt 5. For macOS, the name of the platform plugin is libqcocoa.dylib. This file must be located within a specific subdirectory (by default, 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 imageformats or sqldrivers) in your distribution directory.The search path for Qt plugins (as well as a few other paths) is hard-coded into the library. By default, the first plugin search path will be hard-coded as /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:.
This is the recommended approach as it provides the most flexibility. Using or. Using a third party installation utility to change the hard-coded paths in the library.The document outlines the issues you need to pay attention to when building and deploying plugins for Qt applications. Additional LibrariesYou can check which libraries your application is linking against by using otool. Run this with the application path as an argument.
Otool -L MyApp.app /Contents /MacOS /MyAppCompiler-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.
![]() Comments are closed.
|
AuthorWrite something about yourself. No need to be fancy, just an overview. Archives
January 2023
Categories |