path: root/doc/src/platforms/ios.qdoc

/****************************************************************************
**
** 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$
**
****************************************************************************/

/*!
    \page ios_support.html
    \title Qt for iOS
    \brief Provides insight into Qt's iOS port and how to use it.

    Qt's iOS port allows you to run Qt applications on iOS devices,
    such as iPhones and iPads.

    \section1 Getting Started

    Development and deployment is done using Xcode. The supported
    workflow is to maintain a \c .pro file based project, export it to
    Xcode (and re-export when the project setup changes), and then
    build and deploy using Xcode. We will look at that in more
    detail in the next section.

    The minimum deployment target for Qt applications is iOS 5.0. Qt
    then supports the following devices (iOS might need to be upgraded
    on some devices).

    \list
        \li iPhone 3GS and later
        \li iPod Touch third and later generations
        \li iPad 2 and later
        \li iPad Mini
    \endlist

    \section2 Setting Up the Development Environment

    You can download the Qt 5 installers from the \l Downloads page.
    For more information, see \l{Getting Started with Qt}.

    \note Qt Enterprise packages are available from the \l{Try Qt Enterprise}
    page. Qt for iOS is also available as part of the Qt Mobile Edition,
    see \l{Qt Enterprise}{qt.digia.com} for details.

    Before installing Qt, you first need to install
    Xcode. You will find it in the Mac App Store \l{Xcode}{here}.

    \note As \l{Xcode5Req}{required by Apple}, you should always use the latest
    Xcode 5 version when building your applications for the App Store.
    In practice this means you need OS X 10.8 or 10.9 to do iOS development
    with Qt, as those are the only platforms where Xcode 5 will run.

    For running Qt applications in the simulator that comes with Xcode,
    this is all you need. However, for running applications on a
    device and publishing your applications in the App Store, you must
    join the iOS Developer Program (see
    \l{https://developer.apple.com/programs/ios/}), and set up
    developer certificates and provisioning profiles. The easiest
    solution is to use a profile that takes any App ID (a \c *).

    Before building any Qt applications, you should test that Xcode
    is set up correctly, for example, by running one of the standard
    Xcode application templates on your device.

    \section2 Building Applications From the Command Line

    As mentioned previously, the development workflow on iOS consists
    of maintaining a normal \c .pro file project and export it to
    Xcode.

    Here is how to build a project:

    \list
        \li run qmake (if you have not done so previously)
        \li open the resulting \c .xcodeproject file in Xcode
        \li build the application in Xcode
    \endlist

    Note that you must re-import the project if its setup changes, for
    example, when adding or removing source files.

    \section1 Building Applications with Qt Creator

    You can find information on how to set up and run iOS applications
    in Qt Creator's manual:

    \list
        \li \l{Qt Creator: Connecting iOS devices}{Connecting iOS Devices}.
    \endlist

    As mentioned previously, you must have Xcode installed.

    \section2 Examples for iOS

    In Qt Creator, tested examples on iOS can be looked up. Use the \c ios
    keyword to search for examples in the Qt Creator Welcome mode. Note that
    some examples may have limited functionality.

    \section1 Using Objective-C Code in Qt Applications

    Clang, the compiler used for iOS applications, allows mixing C++
    and Objective-C code. To enable this mode, suffix your source
    files with \.c mm, and add them to \c OBJECTIVE_SOURCES instead of
    \c SOURCES in the \c .pro file. This makes it possible to use
    frameworks from Apple's iOS Developer Library in Qt applications.
    Most useful is perhaps the possibility for adding In-App
    Purchasing with the StoreKit framework.

    We currently have one example mixing Objective-C and C++ code. You
    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}
        \li \l {Qt for iOS - Building from Source}
    \endlist
*/

/*!
    \page building-from-source-ios.html
    \title Qt for iOS - Building from Source
    \brief Provides instructions to build Qt from source for iOS platform.

    Building \l {Qt for iOS} from sources requires \l Xcode with
    command-line tools installed. This can be done within Xcode from
    \gui Preferences > \gui Downloads > \gui Components >
    \gui {Command Line Tools}.

    Qt 5 sources can be obtained either by cloning the repositories or
    downloading the source package(s).

    We can then configure and build Qt. This is done from the Qt 5 top
    directory:

    \badcode
        > ./configure -xplatform macx-ios-clang -release
    \endcode

    For other configure options, see \l{Qt Configure Options}.

    Then, simply run \c{make}.

    \note A default build will include both simulator and device
    libraries. If you want to build for a single target, use the \c
    -sdk argument with either \c iphoneos or \c iphonesimulator.
*/

/*!
    \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.
*/