Doc: Discuss platform plugins in deployment documentation

The requirement to deploy the QPA platform plugin as part of
the application package was not highlighted clearly enough.
This change adds a paragraph for each of the main platforms.

Also fixes linking issue with Mac OS X deployment docs and
updates information about the macdeployqt tool.

Task-number: QTBUG-34274
Change-Id: I9554bd06aa85d4f85b6f32a574efedf424117076
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@digia.com>

3 files changed, 76 insertions, 29 deletions

diff --git a/doc/src/platforms/linux.qdoc b/doc/src/platforms/linux.qdoc
index f8e729261..81a4a810f 100644
--- a/doc/src/platforms/linux.qdoc
+++ b/doc/src/platforms/linux.qdoc
@@ -554,10 +554,10 @@
 
     To deploy the application, we must make sure that we copy the
     relevant Qt libraries (corresponding to the Qt modules used in the
-    application) as well as the executable to the same
-    directory. Remember that if your application depends on compiler
-    specific libraries, these must also be redistributed along with
-    your application. For more information, see the \l {Application
+    application), the \l {Qt Plugins}{platform plugin}, and the executable
+    to the same directory tree. Remember that if your application depends
+    on compiler specific libraries, these must also be redistributed along
+    with your application. For more information, see the \l {Application
     Dependencies} section.
 
     We'll cover the plugins shortly, but the main issue with shared
@@ -704,12 +704,19 @@
 
     \section2 Qt Plugins
 
+    All Qt GUI applications require a plugin that implements the \l {Qt
+    Platform Abstraction} (QPA) layer in Qt 5. For Linux/X11, the name of the
+    platform plugin is \c {libqxcb.so}. 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,
-    and note that each type of plugin should be located within a
-    specific subdirectory (such as \c imageformats or \c sqldrivers)
-    within your distribution directory, as described below.
+    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)
+    within your distribution directory.
 
     \note If you are deploying an application that uses \l{Qt WebKit} to display
     HTML pages from the World Wide Web, you should include all text codec
diff --git a/doc/src/platforms/macosx.qdoc b/doc/src/platforms/macosx.qdoc
index 10937c176..17c0a7721 100644
--- a/doc/src/platforms/macosx.qdoc
+++ b/doc/src/platforms/macosx.qdoc
@@ -141,7 +141,7 @@
     can be used as a starting point for app store deployment.
 
     \list
-    \li {Qt for Mac OS X - Deployment}
+    \li \l{Qt for Mac OS X - Deployment}
     \endlist
 
     \section1 Mac OS X Issues
@@ -915,7 +915,8 @@
     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 director.
+    under the \c plugandpaint directory. We just have to move this directory
+    to the correct location.
 
     \snippet snippets/code/doc_src_deployment.qdoc 43
 
@@ -1007,11 +1008,18 @@
 
     \section2 Qt Plugins
 
+    All Qt GUI applications require a plugin that implements the \l {Qt
+    Platform Abstraction} (QPA) layer in Qt 5. For Mac OS X, 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. Each type of plugin must be
-    located within a specific subdirectory (such as \c imageformats or \c
-    sqldrivers) in your distribution directory, as described below.
+    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.
 
     When deploying an application that uses Qt WebKit to display HTML pages from
     the World Wide Web, you must include all text codec plugins to support as
@@ -1090,14 +1098,16 @@
     frameworks.
 
     The mac deployment tool also deploys the Qt plugins, according
-    to the following rules:
+    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 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 SVG icon plugin is deployed if the application uses the \l{Qt SVG} module.
     \li The accessibility plugin is always deployed.
     \endlist
 
@@ -1105,11 +1115,33 @@
     into the bundle manually, after the bundle is created.
 
     \c macdeployqt supports the following options:
-    \list
-    \li \c{-no-plugins}: Skip plugin deployment
-    \li \c{-dmg}       : Create a .dmg disk image
-    \li \c{-no-strip}  : Don't run 'strip' on the binaries
-    \endlist
+    \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
+    \endtable
 */
 
 /*!
diff --git a/doc/src/platforms/windows.qdoc b/doc/src/platforms/windows.qdoc
index b4920b8e0..61f8021a3 100644
--- a/doc/src/platforms/windows.qdoc
+++ b/doc/src/platforms/windows.qdoc
@@ -398,13 +398,14 @@
 
     To deploy the application, we must make sure that we copy the
     relevant Qt DLL (corresponding to the Qt modules used in
-    the application) and the windows platform plugin as well as the executable
-    to the same directory in the \c release subdirectory.
+    the application) and the Windows platform plugin, \c {qwindows.dll},
+    as well as the executable to the same directory tree in the \c release
+    subdirectory.
 
     In contrast to user plugins, Qt plugins have to be put into subdirectories
-    matching the plugin type. As we want to deploy the windows platform plugin
-    it has to be put into a "platforms" subdirectory. Additional information
-    about user and Qt plugins will be covered later.
+    matching the plugin type. The correct location for the platform plugin
+    is a subdirectory named \c {platforms}. \l{Qt Plugins} section has
+    additional information about plugins and how Qt searches for them.
 
     Qt relies on the \l{ICU} library for unicode support. Therefore, you must
     include the ICU DLLs that are located in the \c bin directory of your Qt
@@ -681,12 +682,19 @@
 
     \section2 Qt Plugins
 
+    All Qt GUI applications require a plugin that implements the \l {Qt
+    Platform Abstraction} (QPA) layer in Qt 5. For Windows, the name of the
+    platform plugin is \c {qwindows.dll}. 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 print support plugin, the JPEG image format plugin or a SQL driver
     plugin. Be sure to distribute any Qt plugins that you need with your
-    application, and note that each type of plugin should be located within a
-    specific subdirectory (such as \c printsupport, \c imageformats or
-    \c sqldrivers) within your distribution directory, as described below.
+    application. Similar to the platform plugin, each type of plugin must
+    be located within a specific subdirectory (such as \c printsupport,
+    \c imageformats or \c sqldrivers) within your distribution directory.
 
     \note If you are deploying an application that uses Qt WebKit to display
     HTML pages from the World Wide Web, you should include all text codec