1 /****************************************************************************
3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the documentation of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:LGPL$
10 ** No Commercial Usage
11 ** This file contains pre-release code and may not be distributed.
12 ** You may use this file in accordance with the terms and conditions
13 ** contained in the Technology Preview License Agreement accompanying
16 ** GNU Lesser General Public License Usage
17 ** Alternatively, this file may be used under the terms of the GNU Lesser
18 ** General Public License version 2.1 as published by the Free Software
19 ** Foundation and appearing in the file LICENSE.LGPL included in the
20 ** packaging of this file. Please review the following information to
21 ** ensure the GNU Lesser General Public License version 2.1 requirements
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
24 ** In addition, as a special exception, Nokia gives you certain additional
25 ** rights. These rights are described in the Nokia Qt LGPL Exception
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
28 ** If you have questions regarding the use of this file, please contact
29 ** Nokia at qt-info@nokia.com.
40 ****************************************************************************/
42 /****************************************************************************
44 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
45 ** All rights reserved.
46 ** Contact: Nokia Corporation (qt-info@nokia.com)
48 ** This file is part of the Qt GUI Toolkit.
49 ** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE
51 ****************************************************************************/
55 \title Deploying Qt Applications
58 Deploying an Qt application does not require any C++
59 programming. All you need to do is to build Qt and your
60 application in release mode, following the procedures described in
61 this documentation. We will demonstrate the procedures in terms of
62 deploying the \l {tools/plugandpaint}{Plug & Paint} application
63 that is provided in Qt's examples directory.
65 \section1 Static vs. Shared Libraries
67 There are two ways of deploying an application:
71 \o Shared Libraries (Frameworks on Mac)
74 Static linking results in a stand-alone executable. The advantage
75 is that you will only have a few files to deploy. The
76 disadvantages are that the executables are large and with no
77 flexibility (i.e a new version of the application, or of Qt, will
78 require that the deployment process is repeated), and that you
79 cannot deploy plugins.
81 To deploy plugin-based applications, you can use the shared
82 library approach. Shared libraries also provide smaller, more
83 flexible executables. For example, using the shared library
84 approach, the user is able to independently upgrade the Qt library
85 used by the application.
87 Another reason why you might want to use the shared library
88 approach, is if you want to use the same Qt libraries for a family
89 of applications. In fact, if you download the binary installation
90 of Qt, you get Qt as a shared library.
92 The disadvantage with the shared library approach is that you
93 will get more files to deploy. For more information, see
94 \l{sharedlibrary.html}{Creating Shared Libraries}.
96 \section1 Deploying Qt's Libraries
100 \o {4,1} Qt's Libraries
115 \o \l {QtScriptTools}
122 \o \l {QtXmlPatterns}
123 \o \l {Phonon Module}{Phonon}
127 Since Qt is not a system library, it has to be redistributed along
128 with your application; the minimum is to redistribute the run-time
129 of the libraries used by the application. Using static linking,
130 however, the Qt run-time is compiled into the executable.
132 In particular, you will need to deploy Qt plugins, such as
133 JPEG support or SQL drivers. For more information about plugins,
134 see the \l {plugins-howto.html}{How to Create Qt Plugins}
137 When deploying an application using the shared library approach
138 you must ensure that the Qt libraries will use the correct path to
139 find the Qt plugins, documentation, translation etc. To do this you
140 can use a \c qt.conf file. For more information, see the \l {Using
141 qt.conf} documentation.
143 Depending on configuration, compiler specific libraries must be
144 redistributed as well. For more information, see the platform
145 specific Application Dependencies sections: \l
146 {deployment-x11.html#application-dependencies}{X11}, \l
147 {deployment-windows.html#application-dependencies}{Windows}, \l
148 {deployment-mac.html#application-dependencies}{Mac}.
152 Some of Qt's libraries are based on third party libraries that are
153 not licensed using the same dual-license model as Qt. As a result,
154 care must be taken when deploying applications that use these
155 libraries, particularly when the application is statically linked
158 The following table contains an inexhaustive summary of the issues
159 you should be aware of.
162 \header \o Qt Library \o Dependency
164 \row \o QtHelp \o CLucene
165 \o The version of clucene distributed with Qt is licensed
166 under the GNU LGPL version 2.1 or later. This has implications for
167 developers of closed source applications. Please see
168 \l{QtHelp Module#License Information}{the QtHelp module documentation}
169 for more information.
171 \row \o QtNetwork \o OpenSSL
172 \o Some configurations of QtNetwork use OpenSSL at run-time. Deployment
173 of OpenSSL libraries is subject to both licensing and export restrictions.
174 More information can be found in the \l{Secure Sockets Layer (SSL) Classes}
177 \row \o QtWebKit \o WebKit
178 \o WebKit is licensed under the GNU LGPL version 2 or later.
179 This has implications for developers of closed source applications.
180 Please see \l{QtWebKit Module#License Information}{the QtWebKit module
181 documentation} for more information.
183 \row \o \l{Phonon Module}{Phonon} \o Phonon
184 \o Phonon relies on the native multimedia engines on different platforms.
185 Phonon itself is licensed under the GNU LGPL version 2. Please see
186 \l{Phonon Module#License Information}{the Phonon module documentation}
187 for more information on licensing and the
188 \l{Phonon Overview#Backends}{Phonon Overview} for details of the backends
189 in use on different platforms.
192 \section1 Platform-Specific Notes
194 The procedure of deploying Qt applications is different for the
198 \o \l{Deploying an Application on X11 Platforms}{Qt for X11 Platforms}
199 \o \l{Deploying an Application on Windows}{Qt for Windows}
200 \o \l{Deploying an Application on Mac OS X}{Qt for Mac OS X}
201 \o \l{Deploying Qt for Embedded Linux Applications}{Qt for Embedded Linux}
204 \sa Installation {Window System Specific Notes}
208 \page deployment-x11.html
209 \contentspage Deploying Qt Applications
211 \title Deploying an Application on X11 Platforms
214 Due to the proliferation of Unix systems (commercial Unices, Linux
215 distributions, etc.), deployment on Unix is a complex
216 topic. Before we start, be aware that programs compiled for one
217 Unix flavor will probably not run on a different Unix system. For
218 example, unless you use a cross-compiler, you cannot compile your
219 application on Irix and distribute it on AIX.
225 This documentation will describe how to determine which files you
226 should include in your distribution, and how to make sure that the
227 application will find them at run-time. We will demonstrate the
228 procedures in terms of deploying the \l {tools/plugandpaint}{Plug
229 & Paint} application that is provided in Qt's examples directory.
231 \section1 Static Linking
233 Static linking is often the safest and easiest way to distribute
234 an application on Unix since it relieves you from the task of
235 distributing the Qt libraries and ensuring that they are located
236 in the default search path for libraries on the target system.
238 \section2 Building Qt Statically
240 To use this approach, you must start by installing a static version
243 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 0
245 We specify the prefix so that we do not overwrite the existing Qt
246 installation. The example above only builds the Qt libraries,
247 i.e. the examples and Qt Designer will not be built. When \c make
248 is done, you will find the Qt libraries in the \c /path/to/Qt/lib
251 When linking your application against static Qt libraries, note
252 that you might need to add more libraries to the \c LIBS line in
253 your project file. For more information, see the \l {Application
254 Dependencies} section.
256 \section2 Linking the Application to the Static Version of Qt
258 Once Qt is built statically, the next step is to regenerate the
259 makefile and rebuild the application. First, we must go into the
260 directory that contains the application:
262 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 1
264 Now run qmake to create a new makefile for the application, and do
265 a clean build to create the statically linked executable:
267 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 2
269 You probably want to link against the release libraries, and you
270 can specify this when invoking \c qmake. Note that we must set the
271 path to the static Qt that we just built.
273 To check that the application really links statically with Qt, run
274 the \c ldd tool (available on most Unices):
276 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 3
278 Verify that the Qt libraries are not mentioned in the output.
280 Now, provided that everything compiled and linked without any
281 errors, we should have a \c plugandpaint file that is ready for
282 deployment. One easy way to check that the application really can
283 be run stand-alone is to copy it to a machine that doesn't have Qt
284 or any Qt applications installed, and run it on that machine.
286 Remember that if your application depends on compiler specific
287 libraries, these must still be redistributed along with your
288 application. For more information, see the \l {Application
289 Dependencies} section.
291 The \l {tools/plugandpaint}{Plug & Paint} example consists of
292 several components: The core application (\l
293 {tools/plugandpaint}{Plug & Paint}), and the \l
294 {tools/plugandpaintplugins/basictools}{Basic Tools} and \l
295 {tools/plugandpaintplugins/extrafilters}{Extra Filters}
296 plugins. Since we cannot deploy plugins using the static linking
297 approach, the executable we have prepared so far is
298 incomplete. The application will run, but the functionality will
299 be disabled due to the missing plugins. To deploy plugin-based
300 applications we should use the shared library approach.
302 \section1 Shared Libraries
304 We have two challenges when deploying the \l
305 {tools/plugandpaint}{Plug & Paint} application using the shared
306 libraries approach: The Qt runtime has to be correctly
307 redistributed along with the application executable, and the
308 plugins have to be installed in the correct location on the target
309 system so that the application can find them.
311 \section2 Building Qt as a Shared Library
313 We assume that you already have installed Qt as a shared library,
314 which is the default when installing Qt, in the \c /path/to/Qt
315 directory. For more information on how to build Qt, see the \l
316 {Installation} documentation.
318 \section2 Linking the Application to Qt as a Shared Library
320 After ensuring that Qt is built as a shared library, we can build
321 the \l {tools/plugandpaint}{Plug & Paint} application. First, we
322 must go into the directory that contains the application:
324 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 4
326 Now run qmake to create a new makefile for the application, and do
327 a clean build to create the dynamically linked executable:
329 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 5
331 This builds the core application, the following will build the
334 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 6
336 If everything compiled and linked without any errors, we will get
337 a \c plugandpaint executable and the \c libpnp_basictools.so and
338 \c libpnp_extrafilters.so plugin files.
340 \section2 Creating the Application Package
342 There is no standard package management on Unix, so the method we
343 present below is a generic solution. See the documentation for
344 your target system for information on how to create a package.
346 To deploy the application, we must make sure that we copy the
347 relevant Qt libraries (corresponding to the Qt modules used in the
348 application) as well as the executable to the same
349 directory. Remember that if your application depends on compiler
350 specific libraries, these must also be redistributed along with
351 your application. For more information, see the \l {Application
352 Dependencies} section.
354 We'll cover the plugins shortly, but the main issue with shared
355 libraries is that you must ensure that the dynamic linker will
356 find the Qt libraries. Unless told otherwise, the dynamic linker
357 doesn't search the directory where your application resides. There
358 are many ways to solve this:
361 \o You can install the Qt libraries in one of the system
362 library paths (e.g. \c /usr/lib on most systems).
364 \o You can pass a predetermined path to the \c -rpath command-line
365 option when linking the application. This will tell the dynamic
366 linker to look in this directory when starting your application.
368 \o You can write a startup script for your application, where you
369 modify the dynamic linker configuration (e.g. adding your
370 application's directory to the \c LD_LIBRARY_PATH environment
371 variable. \note If your application will be running with "Set
372 user ID on execution," and if it will be owned by root, then
373 LD_LIBRARY_PATH will be ignored on some platforms. In this
374 case, use of the LD_LIBRARY_PATH approach is not an option).
378 The disadvantage of the first approach is that the user must have
379 super user privileges. The disadvantage of the second approach is
380 that the user may not have privileges to install into the
381 predetemined path. In either case, the users don't have the option
382 of installing to their home directory. We recommend using the
383 third approach since it is the most flexible. For example, a \c
384 plugandpaint.sh script will look like this:
386 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 7
388 By running this script instead of the executable, you are sure
389 that the Qt libraries will be found by the dynamic linker. Note
390 that you only have to rename the script to use it with other
393 When looking for plugins, the application searches in a plugins
394 subdirectory inside the directory of the application
395 executable. Either you have to manually copy the plugins into the
396 \c plugins directory, or you can set the \c DESTDIR in the
397 plugins' project files:
399 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 8
401 An archive distributing all the Qt libraries, and all the plugins,
402 required to run the \l {tools/plugandpaint}{Plug & Paint}
403 application, would have to include the following files:
407 \o Component \o {2, 1} File Name
410 \o {2, 1} \c plugandpaint
412 \o The script to run the executable
413 \o {2, 1} \c plugandpaint.sh
415 \o The Basic Tools plugin
416 \o {2, 1} \c plugins\libpnp_basictools.so
418 \o The ExtraFilters plugin
419 \o {2, 1} \c plugins\libpnp_extrafilters.so
421 \o The Qt Core module
422 \o {2, 1} \c libQtCore.so.4
425 \o {2, 1} \c libQtGui.so.4
428 On most systems, the extension for shared libraries is \c .so. A
429 notable exception is HP-UX, which uses \c .sl.
431 Remember that if your application depends on compiler specific
432 libraries, these must still be redistributed along with your
433 application. For more information, see the \l {Application
434 Dependencies} section.
436 To verify that the application now can be successfully deployed,
437 you can extract this archive on a machine without Qt and without
438 any compiler installed, and try to run it, i.e. run the \c
439 plugandpaint.sh script.
441 An alternative to putting the plugins in the \c plugins
442 subdirectory is to add a custom search path when you start your
443 application using QApplication::addLibraryPath() or
444 QApplication::setLibraryPaths().
446 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 9
448 \section1 Application Dependencies
450 \section2 Additional Libraries
452 To find out which libraries your application depends on, run the
453 \c ldd tool (available on most Unices):
455 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 10
457 This will list all the shared library dependencies for your
458 application. Depending on configuration, these libraries must be
459 redistributed along with your application. In particular, the
460 standard C++ library must be redistributed if you're compiling
461 your application with a compiler that is binary incompatible with
462 the system compiler. When possible, the safest solution is to link
463 against these libraries statically.
465 You will probably want to link dynamically with the regular X11
466 libraries, since some implementations will try to open other
467 shared libraries with \c dlopen(), and if this fails, the X11
468 library might cause your application to crash.
470 It's also worth mentioning that Qt will look for certain X11
471 extensions, such as Xinerama and Xrandr, and possibly pull them
472 in, including all the libraries that they link against. If you
473 can't guarantee the presence of a certain extension, the safest
474 approach is to disable it when configuring Qt (e.g. \c {./configure
477 FontConfig and FreeType are other examples of libraries that
478 aren't always available or that aren't always binary
479 compatible. As strange as it may sound, some software vendors have
480 had success by compiling their software on very old machines and
481 have been very careful not to upgrade any of the software running
484 When linking your application against the static Qt libraries, you
485 must explicitly link with the dependent libraries mentioned
486 above. Do this by adding them to the \c LIBS variable in your
491 Your application may also depend on one or more Qt plugins, such
492 as the JPEG image format plugin or a SQL driver plugin. Be sure
493 to distribute any Qt plugins that you need with your application,
494 and note that each type of plugin should be located within a
495 specific subdirectory (such as \c imageformats or \c sqldrivers)
496 within your distribution directory, as described below.
498 \note If you are deploying an application that uses QtWebKit to display
499 HTML pages from the World Wide Web, you should include all text codec
500 plugins to support as many HTML encodings possible.
502 The search path for Qt plugins (as well as a few other paths) is
503 hard-coded into the QtCore library. By default, the first plugin
504 search path will be hard-coded as \c /path/to/Qt/plugins. As
505 mentioned above, using pre-determined paths has certain
506 disadvantages, so you need to examine various alternatives to make
507 sure that the Qt plugins are found:
511 \o \l{qt-conf.html}{Using \c qt.conf}. This is the recommended
512 approach since it provides the most flexibility.
514 \o Using QApplication::addLibraryPath() or
515 QApplication::setLibraryPaths().
517 \o Using a third party installation utility or the target system's
518 package manager to change the hard-coded paths in the QtCore
523 The \l{How to Create Qt Plugins} document outlines the issues you
524 need to pay attention to when building and deploying plugins for
529 \page deployment-windows.html
530 \contentspage Deploying Qt Applications
532 \title Deploying an Application on Windows
535 This documentation will describe how to determine which files you
536 should include in your distribution, and how to make sure that the
537 application will find them at run-time. We will demonstrate the
538 procedures in terms of deploying the \l {tools/plugandpaint}{Plug
539 & Paint} application that is provided in Qt's examples directory.
545 \section1 Static Linking
547 If you want to keep things simple by only having a few files to
548 deploy, i.e. a stand-alone executable with the associated compiler
549 specific DLLs, then you must build everything statically.
551 \section2 Building Qt Statically
553 Before we can build our application we must make sure that Qt is
554 built statically. To do this, go to a command prompt and type the
557 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 11
559 Remember to specify any other options you need, such as data base
560 drivers, as arguments to \c configure. Once \c configure has
561 finished, type the following:
563 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 12
565 This will build Qt statically. Note that unlike with a dynamic build,
566 building Qt statically will result in libraries without version numbers;
567 e.g. \c QtCore4.lib will be \c QtCore.lib. Also, we have used \c nmake
568 in all the examples, but if you use MinGW you must use
569 \c mingw32-make instead.
571 \note If you later need to reconfigure and rebuild Qt from the
572 same location, ensure that all traces of the previous configuration are
573 removed by entering the build directory and typing \c{nmake distclean}
574 before running \c configure again.
576 \section2 Linking the Application to the Static Version of Qt
578 Once Qt has finished building we can build the \l
579 {tools/plugandpaint}{Plug & Paint} application. First we must go
580 into the directory that contains the application:
582 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 13
584 We must then run \c qmake to create a new makefile for the
585 application, and do a clean build to create the statically linked
588 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 14
590 You probably want to link against the release libraries, and you
591 can specify this when invoking \c qmake. Now, provided that
592 everything compiled and linked without any errors, we should have
593 a \c plugandpaint.exe file that is ready for deployment. One easy
594 way to check that the application really can be run stand-alone is
595 to copy it to a machine that doesn't have Qt or any Qt
596 applications installed, and run it on that machine.
598 Remember that if your application depends on compiler specific
599 libraries, these must still be redistributed along with your
600 application. You can check which libraries your application is
601 linking against by using the \c depends tool. For more
602 information, see the \l {Application Dependencies} section.
604 The \l {tools/plugandpaint}{Plug & Paint} example consists of
605 several components: The application itself (\l
606 {tools/plugandpaint}{Plug & Paint}), and the \l
607 {tools/plugandpaintplugins/basictools}{Basic Tools} and \l
608 {tools/plugandpaintplugins/extrafilters}{Extra Filters}
609 plugins. Since we cannot deploy plugins using the static linking
610 approach, the application we have prepared is incomplete. It will
611 run, but the functionality will be disabled due to the missing
612 plugins. To deploy plugin-based applications we should use the
613 shared library approach.
615 \section1 Shared Libraries
617 We have two challenges when deploying the \l
618 {tools/plugandpaint}{Plug & Paint} application using the shared
619 libraries approach: The Qt runtime has to be correctly
620 redistributed along with the application executable, and the
621 plugins have to be installed in the correct location on the target
622 system so that the application can find them.
624 \section2 Building Qt as a Shared Library
626 We assume that you already have installed Qt as a shared library,
627 which is the default when installing Qt, in the \c C:\path\to\Qt
628 directory. For more information on how to build Qt, see the \l
629 {Installation} documentation.
631 \section2 Linking the Application to Qt as a Shared Library
633 After ensuring that Qt is built as a shared library, we can build
634 the \l {tools/plugandpaint}{Plug & Paint} application. First, we
635 must go into the directory that contains the application:
637 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 15
639 Now run \c qmake to create a new makefile for the application, and
640 do a clean build to create the dynamically linked executable:
642 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 16
644 This builds the core application, the following will build the
647 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 17
649 If everything compiled and linked without any errors, we will get
650 a \c plugandpaint.exe executable and the \c pnp_basictools.dll and
651 \c pnp_extrafilters.dll plugin files.
653 \section2 Creating the Application Package
655 To deploy the application, we must make sure that we copy the
656 relevant Qt DLL (corresponding to the Qt modules used in
657 the application) as well as the executable to the same directory
658 in the \c release subdirectory.
660 Remember that if your application depends on compiler specific
661 libraries, these must be redistributed along with your
662 application. You can check which libraries your application is
663 linking against by using the \c depends tool. For more
664 information, see the \l {Application Dependencies} section.
666 We'll cover the plugins shortly, but first we'll check that the
667 application will work in a deployed environment: Either copy the
668 executable and the Qt DLLs to a machine that doesn't have Qt
669 or any Qt applications installed, or if you want to test on the
670 build machine, ensure that the machine doesn't have Qt in its
673 If the application starts without any problems, then we have
674 successfully made a dynamically linked version of the \l
675 {tools/plugandpaint}{Plug & Paint} application. But the
676 application's functionality will still be missing since we have
677 not yet deployed the associated plugins.
679 Plugins work differently to normal DLLs, so we can't just
680 copy them into the same directory as our application's executable
681 as we did with the Qt DLLs. When looking for plugins, the
682 application searches in a \c plugins subdirectory inside the
683 directory of the application executable.
685 So to make the plugins available to our application, we have to
686 create the \c plugins subdirectory and copy over the relevant DLLs:
688 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 18
690 An archive distributing all the Qt DLLs and application
691 specific plugins required to run the \l {tools/plugandpaint}{Plug
692 & Paint} application, would have to include the following files:
696 \o Component \o {2, 1} File Name
699 \o {2, 1} \c plugandpaint.exe
701 \o The Basic Tools plugin
702 \o {2, 1} \c plugins\pnp_basictools.dll
704 \o The ExtraFilters plugin
705 \o {2, 1} \c plugins\pnp_extrafilters.dll
707 \o The Qt Core module
708 \o {2, 1} \c qtcore4.dll
711 \o {2, 1} \c qtgui4.dll
714 In addition, the archive must contain the following compiler
715 specific libraries depending on your version of Visual Studio:
719 \o \o VC++ 6.0 \o VC++ 7.1 (2003) \o VC++ 8.0 (2005)
732 To verify that the application now can be successfully deployed,
733 you can extract this archive on a machine without Qt and without
734 any compiler installed, and try to run it.
736 An alternative to putting the plugins in the plugins subdirectory
737 is to add a custom search path when you start your application
738 using QApplication::addLibraryPath() or
739 QApplication::setLibraryPaths().
741 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 19
743 One benefit of using plugins is that they can easily be made
744 available to a whole family of applications.
746 It's often most convenient to add the path in the application's \c
747 main() function, right after the QApplication object is
748 created. Once the path is added, the application will search it
749 for plugins, in addition to looking in the \c plugins subdirectory
750 in the application's own directory. Any number of additional paths
753 \section2 Visual Studio 2005 Onwards
755 When deploying an application compiled with Visual Studio 2005 onwards,
756 there are some additional steps to be taken.
758 First, we need to copy the manifest file created when linking the
759 application. This manifest file contains information about the
760 application's dependencies on side-by-side assemblies, such as the runtime
763 The manifest file needs to be copied into the \bold same folder as the
764 application executable. You do not need to copy the manifest files for
765 shared libraries (DLLs), since they are not used.
767 If the shared library has dependencies that are different from the
768 application using it, the manifest file needs to be embedded into the DLL
769 binary. Since Qt 4.1.3, the follwoing \c CONFIG options are available for
772 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 20
774 To use the options, add
776 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 21
778 to your .pro file. The \c embed_manifest_dll option is enabled by default.
780 You can find more information about manifest files and side-by-side
782 \l {http://msdn.microsoft.com/en-us/library/aa376307.aspx}{MSDN website}.
784 There are two ways to include the run time libraries: by bundling them
785 directly with your application or by installing them on the end-user's
788 To bundle the run time libraries with your application, copy the directory
790 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 22
792 into the folder where your executable is, so that you are including a
793 \c Microsoft.VC80.CRT directory alongside your application's executable. If
794 you are bundling the runtimes and need to deploy plugins as well, you have
795 to remove the manifest from the plugins (embedded as a resource) by adding
796 the following line to the \c{.pro} file of the plugins you are compiling:
798 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 23
800 \warning If you skip the step above, the plugins will not load on some
803 To install the runtime libraries on the end-user's system, you need to
804 include the appropriate Visual C++ Redistributable Package (VCRedist)
805 executable with your application and ensure that it is executed when the
806 user installs your application.
808 For example, on an 32-bit x86-based system, you would include the
809 \l{http://www.microsoft.com/downloads/details.aspx?FamilyId=32BC1BEE-A3F9-4C13-9C99-220B62A191EE}{vcredist_x86.exe}
810 executable. The \l{http://www.microsoft.com/downloads/details.aspx?familyid=526BF4A7-44E6-4A91-B328-A4594ADB70E5}{vcredist_IA64.exe}
811 and \l{http://www.microsoft.com/downloads/details.aspx?familyid=90548130-4468-4BBC-9673-D6ACABD5D13B}{vcredist_x64.exe}
812 executables provide the appropriate libraries for the IA64 and 64-bit x86
813 architectures, respectively.
815 \note The application you ship must be compiled with exactly the same
816 compiler version against the same C runtime version. This prevents
817 deploying errors caused by different versions of the C runtime libraries.
820 \section1 Application Dependencies
822 \section2 Additional Libraries
824 Depending on configuration, compiler specific libraries must be
825 redistributed along with your application. You can check which
826 libraries your application is linking against by using the
827 \l{Dependency Walker} tool. All you need to do is to run it like
830 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 24
832 This will provide a list of the libraries that your application
833 depends on and other information.
835 \image deployment-windows-depends.png
837 When looking at the release build of the Plug & Paint executable
838 (\c plugandpaint.exe) with the \c depends tool, the tool lists the
839 following immediate dependencies to non-system libraries:
850 \o QTCORE4.DLL - The QtCore runtime
851 \o QTGUI4.DLL - The QtGui runtime
854 \o MSVCRT.DLL - The C runtime
855 \o MSVCP60.DLL - The C++ runtime (only when STL is installed)
858 \o MSVCR71.DLL - The C runtime
859 \o MSVCP71.DLL - The C++ runtime (only when STL is installed)
862 \o MSVCR80.DLL - The C runtime
863 \o MSVCP80.DLL - The C++ runtime (only when STL is installed)
866 \o MINGWM10.DLL - The MinGW run-time
870 When looking at the plugin DLLs the exact same dependencies
875 Your application may also depend on one or more Qt plugins, such
876 as the JPEG image format plugin or a SQL driver plugin. Be sure
877 to distribute any Qt plugins that you need with your application,
878 and note that each type of plugin should be located within a
879 specific subdirectory (such as \c imageformats or \c sqldrivers)
880 within your distribution directory, as described below.
882 \note If you are deploying an application that uses QtWebKit to display
883 HTML pages from the World Wide Web, you should include all text codec
884 plugins to support as many HTML encodings possible.
886 The search path for Qt plugins is hard-coded into the QtCore library.
887 By default, the plugins subdirectory of the Qt installation is the first
888 plugin search path. However, pre-determined paths like the default one
889 have certain disadvantages. For example, they may not exist on the target
890 machine. For that reason, you need to examine various alternatives to make
891 sure that the Qt plugins are found:
895 \o \l{qt-conf.html}{Using \c qt.conf}. This approach is the recommended
896 if you have executables in different places sharing the same plugins.
898 \o Using QApplication::addLibraryPath() or
899 QApplication::setLibraryPaths(). This approach is recommended if you only
900 have one executable that will use the plugin.
902 \o Using a third party installation utility to change the
903 hard-coded paths in the QtCore library.
907 If you add a custom path using QApplication::addLibraryPath it could
910 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 54
912 Then qApp->libraryPaths() would return something like this:
914 "C:/customPath/plugins "
915 "C:/Qt/%VERSION%/plugins"
916 "E:/myApplication/directory/"
918 The executable will look for the plugins in these directories and
919 the same order as the QStringList returned by qApp->libraryPaths().
920 The newly added path is prepended to the qApp->libraryPaths() which
921 means that it will be searched through first. However, if you use
922 qApp->setLibraryPaths(), you will be able to determend which paths
923 and in which order they will be searched.
925 The \l{How to Create Qt Plugins} document outlines the issues you
926 need to pay attention to when building and deploying plugins for
931 \page deployment-mac.html
932 \contentspage Deploying Qt Applications
934 \title Deploying an Application on Mac OS X
937 Starting with version 4.5, Qt now includes a \l {macdeploy}{deployment tool}
938 that automates the prodecures described in this document.
940 This documentation will describe how to create a bundle, and how
941 to make sure that the application will find the resources it needs
942 at run-time. We will demonstrate the procedures in terms of
943 deploying the \l {tools/plugandpaint}{Plug & Paint} application
944 that is provided in Qt's examples directory.
950 On the Mac, a GUI application must be built and run from a
951 bundle. A bundle is a directory structure that appears as a single
952 entity when viewed in the Finder. A bundle for an application
953 typcially contains the executable and all the resources it
954 needs. See the image below:
956 \image deployment-mac-bundlestructure.png
958 The bundle provides many advantages to the user. One primary
959 advantage is that, since it is a single entity, it allows for
960 drag-and-drop installation. As a programmer you can access bundle
961 information in your own code. This is specific to Mac OS X and
962 beyond the scope of this document. More information about bundles
964 {http://developer.apple.com/documentation/CoreFoundation/Conceptual/CFBundles/index.html}{Apple's Developer Website}.
966 A Qt command line application on Mac OS X works similar to a
967 command line application on Unix and Windows. You probably don't
968 want to run it in a bundle: Add this to your application's .pro:
970 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 26
972 This will tell \c qmake not to put the executable inside a
973 bundle. Please refer to the \l{Deploying an Application on
974 X11 Platforms}{X11 deployment documentation} for information about how
975 to deploy these "bundle-less" applications.
979 We will only concern ourselves with command-line tools here. While
980 it is possible to use Xcode for this, Xcode has changed enough
981 between each version that it makes it difficult to document it
982 perfectly for each version. A future version of this document may
983 include more information for using Xcode in the deployment
986 \section1 Static Linking
988 If you want to keep things simple by only having a few files to
989 deploy, then you must build everything statically.
991 \section2 Building Qt Statically
993 Start by installing a static version of the Qt library. Remember
994 that you will not be able to use plugins and you must build in all
995 the image formats, SQL drivers, etc..
997 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 27
999 You can check the various options that are available by running \c
1002 \section2 Linking the Application to the Static Version of Qt
1004 Once Qt is built statically, the next step is to regenerate the
1005 makefile and rebuild the application. First, we must go into the
1006 directory that contains the application:
1008 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 28
1010 Now run \c qmake to create a new makefile for the application, and do
1011 a clean build to create the statically linked executable:
1013 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 29
1015 You probably want to link against the release libraries, and you
1016 can specify this when invoking \c qmake. If you have Xcode Tools
1017 1.5 or higher installed, you may want to take advantage of "dead
1018 code stripping" to reduce the size of your binary even more. You
1019 can do this by passing \c {LIBS+= -dead_strip} to \c qmake in
1020 addition to the \c {-config release} parameter. This doesn't have
1021 as large an effect if you are using GCC 4, since Qt will then have
1022 function visibility hints built-in, but if you use GCC 3.3, it
1023 could make a difference.
1025 Now, provided that everything compiled and linked without any
1026 errors, we should have a \c plugandpaint.app bundle that is ready
1027 for deployment. One easy way to check that the application really
1028 can be run stand-alone is to copy the bundle to a machine that
1029 doesn't have Qt or any Qt applications installed, and run the
1030 application on that machine.
1032 You can check what other libraries your application links to using
1035 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 30
1037 Here is what the output looks like for the static \l
1038 {tools/plugandpaint}{Plug & Paint}:
1040 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 31
1042 For more information, see the \l {Application Dependencies}
1045 If you see \e Qt libraries in the output, it probably
1046 means that you have both dynamic and static Qt libraries installed
1047 on your machine. The linker will always choose dynamic over
1048 static. There are two solutions: Either move your Qt dynamic
1049 libraries (\c .dylibs) away to another directory while you link
1050 the application and then move them back, or edit the \c Makefile
1051 and replace link lines for the Qt libraries with the absolute path
1052 to the static libraries. For example, replace
1054 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 32
1058 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 33
1060 The \l {tools/plugandpaint}{Plug & Paint} example consists of
1061 several components: The core application (\l
1062 {tools/plugandpaint}{Plug & Paint}), and the \l
1063 {tools/plugandpaintplugins/basictools}{Basic Tools} and \l
1064 {tools/plugandpaintplugins/extrafilters}{Extra Filters}
1065 plugins. Since we cannot deploy plugins using the static linking
1066 approach, the bundle we have prepared so far is incomplete. The
1067 application will run, but the functionality will be disabled due
1068 to the missing plugins. To deploy plugin-based applications we
1069 should use the framework approach.
1071 \section1 Frameworks
1073 We have two challenges when deploying the \l
1074 {tools/plugandpaint}{Plug & Paint} application using frameworks:
1075 The Qt runtime has to be correctly redistributed along with the
1076 application bundle, and the plugins have to be installed in the
1077 correct location so that the application can find them.
1079 When distributing Qt with your application using frameworks, you
1080 have two options: You can either distribute Qt as a private
1081 framework within your application bundle, or you can distribute Qt
1082 as a standard framework (alternatively use the Qt frameworks in
1083 the installed binary). These two approaches are essentially the
1084 same. The latter option is good if you have many Qt applications
1085 and you would prefer to save memory. The former is good if you
1086 have Qt built in a special way, or want to make sure the framework
1087 is there. It just comes down to where you place the Qt frameworks.
1089 \section2 Building Qt as Frameworks
1091 We assume that you already have installed Qt as frameworks, which
1092 is the default when installing Qt, in the /path/to/Qt
1093 directory. For more information on how to build Qt, see the \l
1094 Installation documentation.
1096 When installing, the identification name of the frameworks will
1097 also be set. The identification name is what the dynamic linker
1098 (\c dyld) uses to find the libraries for your application.
1100 \section2 Linking the Application to Qt as Frameworks
1102 After ensuring that Qt is built as frameworks, we can build the \l
1103 {tools/plugandpaint}{Plug & Paint} application. First, we must go
1104 into the directory that contains the application:
1106 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 34
1108 Now run qmake to create a new makefile for the application, and do
1109 a clean build to create the dynamically linked executable:
1111 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 35
1113 This builds the core application, the following will build the
1116 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 36
1118 Now run the \c otool for the Qt frameworks, for example Qt Gui:
1120 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 37
1122 You will get the following output:
1124 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 38
1126 For the Qt frameworks, the first line (i.e. \c
1127 {path/to/Qt/lib/QtGui.framework/Versions/4/QtGui (compatibility
1128 version 4.0.0, current version 4.0.1)}) becomes the framework's
1129 identification name which is used by the dynamic linker (\c dyld).
1131 But when you are deploying the application, your users may not
1132 have the Qt frameworks installed in the specified location. For
1133 that reason, you must either provide the frameworks in an agreed
1134 upon location, or store the frameworks in the bundle itself.
1135 Regardless of which solution you choose, you must make sure that
1136 the frameworks return the proper identification name for
1137 themselves, and that the application will look for these
1138 names. Luckily we can control this with the \c install_name_tool
1141 The \c install_name_tool works in two modes, \c -id and \c
1142 -change. The \c -id mode is for libraries and frameworks, and
1143 allows us to specify a new identification name. We use the \c
1144 -change mode to change the paths in the application.
1146 Let's test this out by copying the Qt frameworks into the Plug &
1147 Paint bundle. Looking at \c otool's output for the bundle, we can
1148 see that we must copy both the QtCore and QtGui frameworks into
1149 the bundle. We will assume that we are in the directory where we
1152 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 39
1154 First we create a \c Frameworks directory inside the bundle. This
1155 follows the Mac OS X application convention. We then copy the
1156 frameworks into the new directory. Since frameworks contain
1157 symbolic links, and we want to preserve them, we use the \c -R
1160 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 40
1162 Then we run \c install_name_tool to set the identification names
1163 for the frameworks. The first argument after \c -id is the new
1164 name, and the second argument is the framework which
1165 identification we wish to change. The text \c @executable_path is
1166 a special \c dyld variable telling \c dyld to start looking where
1167 the executable is located. The new names specifies that these
1168 frameworks will be located "one directory up and over" in the \c
1169 Frameworks directory.
1171 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 41
1173 Now, the dynamic linker knows where to look for QtCore and
1174 QtGui. Then we must make the application aware of the library
1175 locations as well using \c install_name_tool's \c -change mode.
1176 This basically comes down to string replacement, to match the
1177 identification names that we set for the frameworks.
1179 Finally, since the QtGui framework depends on QtCore, we must
1180 remember to change the reference for QtGui:
1182 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 42
1184 After all this we can run \c otool again and see that the
1185 application will look in the right locations.
1187 Of course, the thing that makes the \l {tools/plugandpaint}{Plug &
1188 Paint} example interesting are its plugins. The basic steps we
1189 need to follow with plugins are:
1192 \o Put the plugins inside the bundle
1193 \o Make sure that the plugins use the correct library using the
1194 \c install_name_tool
1195 \o Make sure that the application knows where to get the plugins
1198 While we can put the plugins anywhere we want in the bundle, the
1199 best location to put them is under Contents/Plugins. When we built
1200 the Plug & Paint plugins, the \c DESTDIR variable in their \c .pro
1201 file put the plugins' \c .dylib files in a \c plugins subdirectory
1202 in the \c plugandpaint directory. So, in this example, all we need
1203 to do is move this directory:
1205 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 43
1207 If we run \c otool on for example the \l
1208 {tools/plugandpaintplugins/basictools}{Basic Tools} plugin's \c
1209 .dylib file we get the following information.
1211 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 44
1213 Then we can see that the plugin links to the Qt frameworks it was
1214 built against. Since we want the plugins to use the framework in
1215 the application bundle we change them the same way as we did for
1216 the application. For example for the Basic Tools plugin:
1218 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 45
1221 We must also modify the code in \c
1222 tools/plugandpaint/mainwindow.cpp to \l {QDir::cdUp()}{cdUp()} one
1223 directory since the plugins live in the bundle. Add the following
1224 code to the \c mainwindow.cpp file:
1226 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 46
1230 \o \inlineimage deployment-mac-application.png
1232 The additional code in \c tools/plugandpaint/mainwindow.cpp also
1233 enables us to view the plugins in the Finder, as shown to the left.
1235 We can also add plugins extending Qt, for example adding SQL
1236 drivers or image formats. We just need to follow the directory
1237 structure outlined in plugin documentation, and make sure they are
1238 included in the QCoreApplication::libraryPaths(). Let's quickly do
1239 this with the image formats, following the approach from above.
1241 Copy Qt's image format plugins into the bundle:
1243 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 47
1245 Use \c install_name_tool to link the plugins to the frameworks in
1248 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 48
1250 Then we update the source code in \c tools/plugandpaint/main.cpp
1251 to look for the new plugins. After constructing the
1252 QApplication, we add the following code:
1254 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 49
1256 First, we tell the application to only look for plugins in this
1257 directory. In our case, this is what we want since we only want to
1258 look for the plugins that we distribute with the bundle. If we
1259 were part of a bigger Qt installation we could have used
1260 QCoreApplication::addLibraryPath() instead.
1264 \warning When deploying plugins, and thus make changes to the
1265 source code, the default identification names are reset when
1266 rebuilding the application, and you must repeat the process of
1267 making your application link to the Qt frameworks in the bundle
1268 using \c install_name_tool.
1270 Now you should be able to move the application to another Mac OS X
1271 machine and run it without Qt installed. Alternatively, you can
1272 move your frameworks that live outside of the bundle to another
1273 directory and see if the application still runs.
1275 If you store the frameworks in another location than in the
1276 bundle, the technique of linking your application is similar; you
1277 must make sure that the application and the frameworks agree where
1278 to be looking for the Qt libraries as well as the plugins.
1280 \section2 Creating the Application Package
1282 When you are done linking your application to Qt, either
1283 statically or as frameworks, the application is ready to be
1284 distributed. Apple provides a fair bit of information about how to
1285 do this and instead of repeating it here, we recommend that you
1287 {http://developer.apple.com/documentation/DeveloperTools/Conceptual/SoftwareDistribution/index.html}{software delivery}
1290 Although the process of deploying an application do have some
1291 pitfalls, once you know the various issues you can easily create
1292 packages that all your Mac OS X users will enjoy.
1294 \section1 Application Dependencies
1296 \section2 Qt Plugins
1298 Your application may also depend on one or more Qt plugins, such
1299 as the JPEG image format plugin or a SQL driver plugin. Be sure
1300 to distribute any Qt plugins that you need with your application,
1301 and note that each type of plugin should be located within a
1302 specific subdirectory (such as \c imageformats or \c sqldrivers)
1303 within your distribution directory, as described below.
1305 \note If you are deploying an application that uses QtWebKit to display
1306 HTML pages from the World Wide Web, you should include all text codec
1307 plugins to support as many HTML encodings possible.
1309 The search path for Qt plugins (as well as a few other paths) is
1310 hard-coded into the QtCore library. By default, the first plugin
1311 search path will be hard-coded as \c /path/to/Qt/plugins. But
1312 using pre-determined paths has certain disadvantages. For example,
1313 they may not exist on the target machine. For that reason you need
1314 to examine various alternatives to make sure that the Qt plugins
1319 \o \l{qt-conf.html}{Using \c qt.conf}. This is the recommended
1320 approach since it provides the most flexibility.
1322 \o Using QApplication::addLibraryPath() or
1323 QApplication::setLibraryPaths().
1325 \o Using a third party installation utility to change the
1326 hard-coded paths in the QtCore library.
1330 The \l{How to Create Qt Plugins} document outlines the issues you
1331 need to pay attention to when building and deploying plugins for
1334 \section2 Additional Libraries
1336 You can check which libraries your application is linking against
1337 by using the \c otool tool. To use \c otool, all you need to do is
1338 to run it like this:
1340 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 50
1342 Unlike the deployment processes on \l {Deploying an Application on
1343 X11 Platforms}{X11} and \l {Deploying an Application on
1344 Windows}{Windows}, compiler specific libraries rarely have to
1345 be redistributed along with your application. But since Qt can be
1346 configured, built, and installed in several ways on Mac OS X,
1347 there are also several ways to deploy applications. Typically your
1348 goals help determine how you are going to deploy the
1349 application. The last sections describe a couple of things to keep
1350 in mind when you are deploying your application.
1352 \section2 Mac OS X Version Dependencies
1354 Qt 4.2 has been designed to be built and deployed on Mac OS X 10.3
1355 up until the current version as of this writing, Mac OS X 10.4 and
1356 all their minor releases. Qt achieves this by using "weak
1357 linking." This means that Qt tests if a function added in newer
1358 versions of Mac OS X is available on the computer it is running on
1359 before it uses it. This results in getting access to newer
1360 features when running on newer versions of OS X while still
1361 remaining compatible on older versions.
1363 For more information about cross development issues on Mac OS X,
1365 {http://developer.apple.com/documentation/DeveloperTools/Conceptual/cross_development/index.html}{Apple's Developer Website}.
1367 Since the linker is set to be compatible with all OS X version, you have to
1368 change the \c MACOSX_DEPLOYMENT_TARGET environment variable to get weak
1369 linking to work for your application. You can add:
1371 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 51
1373 to your .pro file and qmake will take care of this for you.
1375 However, there is a bit of a wrinkle to keep in mind when your are
1376 deploying. Mac OS X 10.4 ("Tiger") ships GCC 4.0 as its default
1377 compiler. This is also the GCC compiler we use for building the
1378 binary Qt package. If you use GCC 4.0 to build your application,
1379 it will link against a dynamic libstdc++ that is only available on
1380 Mac OS X 10.4 and Mac OS X 10.3.9. The application will refuse to
1381 run on older versions of the operating system.
1383 For more information about C++ runtime environment, see \l
1384 {http://developer.apple.com/documentation/DeveloperTools/Conceptual/CppRuntimeEnv/index.html}{Apple's Developer Website}
1386 If you want to deploy to versions of Mac OS X earlier than 10.3.9,
1387 you must build with GCC 3.3 which is the default on Mac OS X
1388 10.3. GCC 3.3 is also available on the Mac OS X 10.4 "Xcode Tools"
1389 CD and as a download for earlier versions of Mac OS X from Apple
1390 (\l {https://connect.apple.com/}{connect.apple.com}). You can use
1391 Apple's \c gcc_select(1) command line tool to switch the default
1392 complier on your system.
1394 \section3 Deploying Phonon Applications on Mac OS X
1397 \o If you build your Phonon application on Tiger, it will work on
1398 Tiger, Leopard and Panther.
1399 \o If you build your application on Leopard, it will \bold not work
1400 on Panther unless you rename the libraries with the following command
1401 after you have built your application:
1403 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 51a
1405 This command must be invoked in the directory where
1406 \c{libphonon_qt7.dylib} is located, usually in
1407 \c{yourapp.app/Contents/plugins/phonon_backend/}.
1408 \o The \l {macdeploy}{deployment tool} will perform this step for you.
1410 \o If you are using Leopard, but would like to build your application
1411 against Tiger, you can use:
1413 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 51b
1416 \section2 Architecture Dependencies
1418 The Qt for Mac OS X libraries, tools, and examples can be built "universal"
1419 (i.e. they run natively on both Intel and PowerPC machines). This
1420 is accomplished by passing \c -universal on the \c configure line
1421 of the source package, and requires that you use GCC 4.0.x. On
1422 PowerPC hardware you will need to pass the universal SDK as a
1423 command line argument to the Qt configure command. For example:
1425 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 52
1427 From 4.1.1 the Qt binary package is already universal.
1429 If you want to create a binary that runs on older versions of
1430 PowerPC and x86, it is possible to build Qt for the PowerPC using
1431 GCC 3.3, and for x86 one using GCC 4.0, and use Apple's \c lipo(1)
1432 tool to stitch them together. This is beyond the scope of this
1433 document and is not something we have tried, but Apple documents
1435 {http://developer.apple.com/documentation/}{developer website}.
1437 Once you have a universal Qt, \a qmake will generate makefiles
1438 that will build for its host architecture by default. If you want
1439 to build for a specific architecture, you can control this with
1440 the \c CONFIG line in your \c .pro file. Use \c CONFIG+=ppc for
1441 PowerPC, and \c CONFIG+=x86 for x86. If you desire both, simply
1442 add both to the \c CONFIG line. PowerPC users also need an
1445 \snippet doc/src/snippets/code/doc_src_deployment.qdoc 53
1447 Besides \c lipo, you can also check your binaries with the \c file(1)
1448 command line tool or the Finder.
1450 \section1 The Mac Deployment Tool
1452 The Mac deployment tool can be found in QTDIR/bin/macdeployqt. It is
1453 designed to automate the process of creating a deployable
1454 application bundle that contains the Qt libraries as private
1457 The mac deployment tool also deploys the Qt plugins, according
1458 to the following rules:
1460 \o Debug versions of the plugins are not deployed.
1461 \o The designer plugins are not deployed.
1462 \o The Image format plugins are always deployed.
1463 \o SQL driver plugins are deployed if the application uses the QtSql module.
1464 \o Script plugins are deployed if the application uses the QtScript module.
1465 \o The Phonon backend plugin is deployed if the application uses the \l{Phonon Module} {Phonon} module.
1466 \o The svg icon plugin is deployed if the application uses the QtSvg module.
1467 \o The accessibility plugin is always deployed.
1468 \o Accessibility for Qt3Support is deployed if the application uses the Qt3Support module.
1471 macdeployqt supports the following options:
1473 \o -no-plugins: Skip plugin deployment
1474 \o -dmg : Create a .dmg disk image
1475 \o -no-strip : Don't run 'strip' on the binaries