// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page creator-developing-ios.html
    \previouspage creator-reference.html

    \title Developing for iOS

    \quotation
    \l {iOS}{How to: Develop for iOS}
    \endquotation

    \summary {Connect iOS devices to your local machine with a USB cable to
    run applications on them.}

    After you install Xcode, \QC automatically detects the toolchain and creates
    the necessary \l{Managing kits}{kits} to build applications for and run them on
    configured iOS devices.

    You only need Qt libraries that are built for iOS. You can install Qt for iOS
    with \l{Get and Install Qt}{\QOI}.

    \section1 iOS 17 devices

    \QC detects iOS devices, and you can deploy and run applications on them.

    Only C++ debugging is supported for devices with iOS 17 and later, and it
    requires Xcode 16 or later.

    \section1 Specifying supported iOS versions

    You can build applications for the latest iOS version and deploy them to
    previous versions. For the most part, this works automatically. However,
    you must take care when you manually set your own target version. If you set
    it to a value higher than what Qt requires and supply your own \c Info.plist
    file, you must add an \c LSMinimumSystemVersion entry to the \c Info.plist
    that matches the value of \l{CMake: CMAKE_OSX_DEPLOYMENT_TARGET}
    {CMAKE_OSX_DEPLOYMENT_TARGET} (when using CMake),
    \l QMAKE_IOS_DEPLOYMENT_TARGET (when using qmake), or
    \l{cpp.minimumIosVersion} (when using Qbs) because iOS (and the App Store)
    will use the \c LSMinimumSystemVersion value as the authoritative one.

    If you specify a deployment target value lower than what Qt requires, your
    application will almost certainly crash somewhere in the Qt libraries when
    run on an older version than Qt supports. Therefore, make sure that the
    actual build system code reflects the minimum iOS version that is actually
    required.

    \sa {iOS}{How to: Develop for iOS}, {Expressing Supported iOS Versions}
*/

/*!
    \page creator-how-to-connect-ios-devices.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-ios

    \title Connect iOS devices

    The connections between \QC and an iOS device are protected by using a
    certificate that you receive from Apple when you
    \l{Enroll in the Apple Developer Program}
    {enroll in the Apple Developer Program}. The certificate is copied to
    the device when you configure the device.

    The first time you connect the device to your local machine, you are asked to enable
    developer mode on the device. The next time you connect the device, \QC
    detects it automatically. To disable automatic connections to a device that
    you do not use for development, go to \preferences > \uicontrol iOS
    and clear \uicontrol {Ask about devices not in developer mode}.

    \note The process of configuring devices and the UI varies slightly
    depending on the Xcode version that you use. We recommend that you use the
    latest available Xcode version.

    \section1 Create a connection to an iOS device

    To configure connections between \QC and an iOS device:

    \list 1

        \li Check that you installed Xcode and \l{Qt for iOS}.

        \li Connect the device to your local machine with a USB cable.

        \li Start Xcode to configure the device.

            For example, in Xcode version 15, go to \uicontrol Window >
            \uicontrol {Devices and Simulators} > \uicontrol Devices, and select
            \uicontrol + to add the connected device.

        \li To specify build settings:

        \list 1

            \li Open a project for an application you want to develop for the
                device.

            \li Go to \uicontrol Projects > \uicontrol {Build & Run} to select
                the kit for building applications for and running them on iOS.

                \image {qtcreator-ios-add-kit.png} {iOS kit selected for a project in Build & Run}

            \li Go to \uicontrol {Build Settings}.

            \li In \uicontrol {iOS Settings}, select the development team to use
                for signing and provisioning applications. You must configure
                development teams and provisioning profiles in Xcode using an
                Apple developer account.

                \image {qtcreator-build-settings-ios.png} {iOS build settings}

            \li Select \uicontrol {Automatically manage signing}
                to automatically select the provisioning profile and signing
                certificate on your local machine that matches the entitlements
                and the bundle identifier of the iOS device.

        \endlist

        \li Go to \uicontrol {Run Settings} to specify run settings.

            Usually, you can use the default settings.

    When you run the project, \QC uses Xcode to deploy the application to the
    device.

    Your signing certificate is used to sign application packages for deployment
    to the device.

    \endlist

    \note If you cannot deploy applications because a provisioning profile is
    missing, check that provisioning profiles are listed in Xcode by going to
    \uicontrol Xcode > \uicontrol Preferences > \uicontrol Accounts. For more
    information about how to acquire and install a provisioning profile, see
    \l {Apple documentation: Create a development provisioning profile}.

    \section1 View device connection status

    When you connect an iOS device to your local machine with USB, \QC
    automatically detects the device if you have configured it by using Xcode.
    To view information about the connected device, go to \uicontrol Preferences >
    \uicontrol Devices.

    \image {qtcreator-ios-device-configurations.png} {Devices tab in Devices preferences}

    If the current device state is \uicontrol Connected, (the traffic light icon is
    orange), you need to configure the device using Xcode.

    \section1 Access files on iOS devices

    You can access files on a connected iOS device, including the crash
    reports directory and the developer's application directories.

    Access these files in one of the following ways:

    \list
        \li Go to \uicontrol File > \uicontrol {Open From Device}.
        \li Go to the \l {File System} view and select the
            device in the menu.
        \li Use the \l {Navigate with locator}{locator}.
    \endlist

    \sa {Activate kits for a project}, {iOS}{How to: Develop for iOS},
    {Developing for iOS}
*/

/*!
    \page creator-how-to-test-on-ios-simulator.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-ios

    \title Test on iOS Simulator

    If you do not have an iOS device or you do not want to create an account,
    you can test applications on
    \l{Simulator Help}{Simulator}, which is installed as part of Xcode. Each Xcode
    version simulates a predefined set of hardware devices and software versions.

    To change the simulated hardware and software version, go to
    \uicontrol Projects > \uicontrol {Run Settings} and select
    the device to simulate in the \uicontrol {Device type} field.

    \image {qtcreator-ios-simulator-deploy.png} {Deployment settings for iOS Simulator}

    The simulator starts automatically when you run the application.
    To start the simulator manually, either start the Simulator application
    directly with Spotlight, or go to \uicontrol Xcode > \uicontrol {Open Developer Tool}
    in Xcode.

    Manage the available simulator devices
    \l{Xcode documentation: Configure the list of simulated devices}{in Xcode}.

    \sa {iOS}{How to: Develop for iOS}, {Developing for iOS}
*/
