Doc: Added platform and porting notes for iOS

Discuss deployment and publishing to App Store for
Qt for iOS apps.

Add a brief porting guide, similar to the one for
Android.

Task-number: QTBUG-37490
Change-Id: I7e7ba4037694cf092dcff27811d841611a417d6b
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@digia.com>

3 files changed, 223 insertions, 17 deletions

diff --git a/doc/src/platforms/android.qdoc b/doc/src/platforms/android.qdoc
index 2231b61d..9885ac8e 100644
--- a/doc/src/platforms/android.qdoc
+++ b/doc/src/platforms/android.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -203,20 +203,7 @@ depend on a specific hardware or software feature not supported by Android.
 If your application is not using any such feature, deployment is probably the
 only step that demands some changes to your application.
 
-Like most UI applications, Qt applications also depend on resources such as
-images, icons, translation files, and so on. These resources must be made
-available on the device as they are required for the application to function
-effectively.
-
-The most convenient option is to bundle the resources into a qrc file,
-which gets built into the application binary. This approach reduces the porting
-effort considerably and provides faster access to the resources. It is
-also a cross-platform approach, which makes porting to other platforms easier.
-
-By default, all Qt applications can access the contents of a qrc file using
-the ":/" prefix or the URL scheme prefix, "qrc:". To know more about qrc files
-and how they are handled, see
-\l{The Qt Resource System}{the Qt Resource System}.
+\include porting-notes.qdocinc using resources
 
 The other approach is to deploy the resources into the package's \c{assets}
 directory. It is the best option if you want to achieve better
diff --git a/doc/src/platforms/ios.qdoc b/doc/src/platforms/ios.qdoc
index 960556b2..b3bea824 100644
--- a/doc/src/platforms/ios.qdoc
+++ b/doc/src/platforms/ios.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -92,7 +92,7 @@
     We can then build Qt. This is done from the Qt 5 top directory,
     like so:
 
-    \code
+    \badcode
         > ./configure -xplatform macx-ios-clang -release
     \endcode
 
@@ -150,4 +150,179 @@
     find it
     \l{https://qt-project.org/wiki/Mixing_C_and_ObjectiveC_Code}{here}.
 
+    \section1 Related Topics
+
+    The following topics provide more details about Qt for iOS:
+    \list
+        \li \l {Porting to iOS}{Porting a Qt Quick Application}
+        \li \l {Platform Notes -iOS}{Platform Notes}
+    \endlist
+*/
+/*!
+    \page porting-to-ios.html
+    \title Porting to iOS
+    \brief Provides instructions to port your existing Qt application to iOS.
+
+    In this section, we are going to port an existing Qt application to
+    \l{Qt for iOS}{iOS} and deploy it to the device.
+
+    Most Qt applications should be portable to iOS with ease, unless they
+    depend on a specific hardware or software feature not supported on iOS.
+    A major part of the porting effort consists of ensuring that all the
+    application's assets (for example, QML files, images, and icons) are
+    deployed correctly to the device.
+
+    \include porting-notes.qdocinc using resources
+
+    The following step-by-step instructions guide you to port an existing Qt Quick
+    application to iOS using the qrc approach:
+
+    \list 1
+     \li Open the existing project in Qt Creator and configure it with
+         \e {iOS} or \e {iOS Simulator} kit. For more information, see
+         \l{Qt Creator: Configuring Projects}.
+
+     \li Update all local directory imports in the \c{qml} files to use a local
+         namespace. For example, to import the QML documents in the "contents"
+         directory relative to \c{main.qml}, use the following import statement:
+
+         \code
+         import "contents" as Contents
+         \endcode
+
+     \li Identify all the resources used by your application and add them to one
+         or more qrc files.
+         Qt Creator updates your qmake project file with the \c RESOURCES
+         variable, listing the qrc files you added.
+
+     \li To load or refer to the resources in the qrc file from a C++ file,
+         use the "\c{qrc:}" prefix for the URL. For example:
+
+         \code
+         QQuickView viewer;
+         viewer.setSource(QUrl("qrc:qml/main.qml"));
+         viewer.show();
+         \endcode
+
+         \note QML documents can refer to files in the resources simply by
+         using the relative path to the document. Such references do not
+        require the "\c{qrc:}" or "\c{:/}" prefix.
+
+     \li Update the "Run" settings for your project as described in the
+         \l{Qt Creator: Specifying Run Settings}
+
+     \li If your application uses imports or plugins which depend on special Qt
+         modules, these Qt modules should be added to the .pro file. For example, if
+         your application uses the \l{Qt Multimedia} import in QML, you should add
+         the following to your .pro file:
+
+         \badcode
+         QT += multimedia
+         \endcode
+
+         In Qt for iOS, everything is compiled statically and placed into the application
+         bundle. The applications are "sandboxed" inside their bundles and cannot make use
+         of shared object files. Because of this, also the plugins used by the Qt modules
+         need to be statically linked. To do this, define the required plugins using the
+         \l QTPLUGIN variable. For example, to use the camera APIs from Qt Multimedia:
+
+         \badcode
+         QTPLUGIN += qavfcamera
+         \endcode
+
+         See \l {http://qt-project.org/wiki/QtMultimedia_iOS}{Qt Multimedia on iOS}
+         for information on other Qt Multimedia plugins. If your project uses APIs
+         from \l {Qt Sensors}, use the following:
+
+         \badcode
+         QT += sensors
+         QTPLUGIN += qtsensors_ios
+         \endcode
+
+     \li Save the changes to your project and run the application.
+    \endlist
+
+    Qt Creator deploys your application on the iOS device, if the
+    device is detected and configured correctly in Xcode. It is also possible to
+    test the application in iOS Simulator. For more information, see
+    \l {http://qt-project.org/doc/qtcreator/creator-developing-ios.html}{Connecting iOS Devices}.
+
+    \sa {Platform Notes - iOS}
+*/
+
+/*!
+    \page platform-notes-ios.html
+    \title Platform Notes - iOS
+    \brief This page contains information about building Qt applications for and running them on the iOS platform.
+
+    \section1 Deployment
+
+    Developing, building, running, and debugging a Qt for iOS application can all be done
+    with Qt Creator on Mac OS X. The toolchain is provided by Apple's Xcode,
+    and running qmake on a project targeted for iOS will also generate an
+    Xcode project file (.xcodeproj), with initial application settings. As Qt
+    Creator does not provide an interface for managing all of the settings specific
+    to iOS platform, it is often necessary to adjust them in Xcode directly.
+    Checking that the application is configured correctly is especially important
+    before submitting an application for publishing in Apple's App Store.
+
+    \target Info.plist
+    \section2 Information Property List Files
+
+    Information property list file (Info.plist) on iOS and Mac OS X is used for configuring
+    an application bundle. These configuration settings include:
+
+    \list
+        \li Application display name and identifier
+        \li Required device capabilities
+        \li Supported user interface orientations
+        \li Icons and launch images
+    \endlist
+
+    See the documentation on \l {https://developer.apple.com/library/ios/documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/App-RelatedResources/App-RelatedResources.html}
+    {Information Property List File} in iOS Developer Library for details.
+
+    When qmake is run, an \c Info.plist file is generated with appropriate default values.
+
+    It is advisable to replace the generated Info.plist with your own copy, to prevent
+    it from being overwritten the next time qmake is run. You can define a custom information
+    property list with \l QMAKE_INFO_PLIST variable in your .pro file:
+
+    \badcode
+    ios {
+        QMAKE_INFO_PLIST = ios/AppInfo.plist
+    }
+    \endcode
+
+    \section2 Application Assets
+
+    For files that cannot be bundled into Qt resources, \l QMAKE_BUNDLE_DATA qmake variable
+    provides a way to specify a set of files to be copied into the application bundle. For
+    example:
+
+    \badcode
+    ios {
+        fontFiles.files = fonts/*.ttf
+        fontFiles.path = fonts
+        QMAKE_BUNDLE_DATA += fontFiles
+    }
+    \endcode
+
+    For image resources, an alternative way is to make use of \l {https://developer.apple.com/library/ios/recipes/xcode_help-image_catalog-1.0/Recipe.html}
+    {asset catalogs} in Xcode.
+
+    \section1 Publishing to Apple App Store
+
+    Verifying that your Qt for iOS application is ready for publishing to App Store is done
+    directly in Xcode. Qt Creator does not provide an interface for managing all of the
+    settings in an Xcode project configuration.
+
+    The application should be tested on a variety of iOS versions and devices, depending on what
+    it's targeted to support. The minimum deployment target for Qt applications is iOS 5.0.
+
+    The actual publishing process involves creating a distribution certificate and a provision profile,
+    creating a signed archive of your application, and running a set of validation tests on it.
+
+    See the \l {https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/SubmittingYourApp/SubmittingYourApp.html}
+    {App Distribution Guide} in iOS Developer Library for more information.
 */
diff --git a/doc/src/platforms/porting-notes.qdocinc b/doc/src/platforms/porting-notes.qdocinc
new file mode 100644
index 00000000..3a059faf
--- /dev/null
+++ b/doc/src/platforms/porting-notes.qdocinc
@@ -0,0 +1,44 @@
+pwd/****************************************************************************
+**
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** 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 Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+//! [using resources]
+    Like most UI applications, Qt applications also depend on resources such as
+    images, icons, translation files, and so on. These resources must be made
+    available on the device as they are required for the application to function
+    correctly.
+
+    The most convenient option is to bundle the resources into a qrc file,
+    which gets built into the application binary. This approach reduces the porting
+    effort considerably and provides faster access to the resources. It is
+    also a cross-platform approach, which makes porting to other platforms easier.
+
+    By default, all Qt applications can access the contents of a qrc file using
+    the ":/" prefix or the URL scheme prefix, "qrc:". To know more about qrc files
+    and how they are handled, see \l{The Qt Resource System}{the Qt Resource System}.
+//! [using resources]
+*/