Notas sobre la plataforma - iOS

Despliegue

Desarrollar, construir, ejecutar y depurar una aplicación Qt para iOS se puede hacer con Qt Creator en macOS. La cadena de herramientas es proporcionada por Xcode de Apple, y la ejecución de qmake o CMake en un proyecto dirigido a iOS también generará un archivo de proyecto Xcode (.xcodeproj), con la configuración inicial de la aplicación. Como Qt Creator no proporciona una interfaz para gestionar todos los ajustes específicos de la plataforma iOS, a veces es necesario ajustarlos en Xcode directamente. Comprobar que la aplicación está configurada correctamente es especialmente importante antes de enviar una aplicación para su publicación en la App Store de Apple.

Paquetes de aplicaciones

Las aplicaciones iOS suelen desplegarse como paquetes de aplicaciones independientes. El paquete de aplicaciones contiene el ejecutable de la aplicación, así como dependencias, como las bibliotecas Qt, plugins, traducciones y otros recursos que la aplicación pueda necesitar.

Para compilar su aplicación como un paquete de aplicaciones con CMake, establezca la propiedad MACOSX_BUNDLE en tu ejecutable, como se indica a continuación:

qt_add_executable(MyApp)
if(APPLE)
    set_target_properties(MyApp PROPERTIES MACOSX_BUNDLE TRUE)
endif()

Con qmake, los paquetes son el valor predeterminado. Establezca CONFIG -= app_bundle en su archivo de proyecto (.pro) para desactivarlo.

Archivos de lista de propiedades de información

El archivo de lista de propiedades de información (Info.plist) en iOS y macOS se utiliza para configurar un paquete de aplicaciones. Estos ajustes de configuración incluyen:

• Nombre para mostrar e identificador de la aplicación
• Capacidades requeridas del dispositivo
• Orientaciones de interfaz de usuario compatibles
• Iconos e imágenes de inicio

Consulte la documentación sobre el archivo de lista de propiedades de información en la biblioteca para desarrolladores de iOS para obtener más detalles.

Info.plist con CMake

CMake genera un archivo Info.plist por defecto si un objetivo tiene su propiedad MACOSX_BUNDLE establecida en TRUE. Desafortunadamente ese archivo no es adecuado para proyectos iOS.

En su lugar, los proyectos pueden utilizar qt_add_executable, que generará automáticamente un archivo Info.plist con valores predeterminados adecuados para proyectos iOS.

Para especificar un Info.plist personalizado, los proyectos pueden establecer la propiedad de destino MACOSX_BUNDLE_INFO_PLIST como se muestra a continuación. Al hacerlo, se desactivará la generación automática de archivos proporcionada por qt_add_executable y, en su lugar, se utilizará el manejo nativo de CMake para el archivo Info.plist proporcionado por el proyecto.

qt_add_executable(app)
if(IOS)
    set_target_properties(app
        PROPERTIES MACOSX_BUNDLE_INFO_PLIST "${CMAKE_CURRENT_SOURCE_DIR}/ios/Info.plist")
endif()

Consulte la documentación de CMake MACOSX_BUNDLE_INFO_PLIST para obtener información sobre qué propiedades y variables de destino se pueden especificar para la sustitución de plantillas realizada por CMake.

Info.plist con QMake

Cuando se ejecuta qmake, se genera un archivo Info.plist con los valores predeterminados adecuados.

Es aconsejable sustituir el Info.plist generado por tu propia copia, para evitar que se sobrescriba la próxima vez que se ejecute qmake. Puede definir una lista de propiedades de información personalizada con la variable QMAKE_INFO_PLIST en su archivo .pro.

ios {
    QMAKE_INFO_PLIST = ios/Info.plist
}

Activos de la aplicación

Para los archivos que no se pueden empaquetar en los recursos Qt, la variable qmake QMAKE_BUNDLE_DATA proporciona una forma de especificar un conjunto de archivos que se copiarán en el paquete de la aplicación. Por ejemplo

ios {
    fontFiles.files = $$files(fonts/*.ttf)
    fontFiles.path = fonts
    QMAKE_BUNDLE_DATA += fontFiles
}

Con CMake, lo mismo se puede hacer de la siguiente manera:

qt_add_executable(app)
file(GLOB_RECURSE font_files CONFIGURE_DEPENDS "fonts/*.ttf")
if(IOS AND font_files)
    target_sources(app PRIVATE ${font_files})
    set_source_files_properties(
        ${font_files}
        PROPERTIES MACOSX_PACKAGE_LOCATION Resources/fonts)
endif()

Para los recursos de imagen, una forma alternativa es hacer uso de los catálogos de activos en Xcode, que se pueden añadir de la siguiente manera con qmake:

ios {
    QMAKE_ASSET_CATALOGS += ios/Assets.xcassets
}

Con CMake:

qt_add_executable(app)
set(asset_catalog_path "ios/Assets.xcassets")
target_sources(app PRIVATE "${asset_catalog_path}")
set_source_files_properties(
    ${asset_catalog_path}
    PROPERTIES MACOSX_PACKAGE_LOCATION Resources)

Iconos

A partir de Xcode 13, los iconos deben añadirse a un conjunto de iconos del catálogo de activos, que normalmente se llama AppIcon. Xcode se encargará entonces de actualizar el archivo Info.plist con las claves y valores correctos, así como de copiar los archivos de iconos necesarios directamente en el paquete de la aplicación.

A partir de Xcode 14, sólo se necesita una imagen de 1024x1024 píxeles. Xcode se encarga de generar todos los iconos necesarios a partir de ella. También es posible especificar las imágenes manualmente en el catálogo de activos.

Una lista detallada de los iconos que se pueden especificar está disponible en Archivos de iconos.

El nombre del archivo no es importante, pero sí lo es el tamaño real en píxeles. Para soportar una aplicación universal iOS, se requieren las siguientes imágenes:

• AppIcon60x60@2x.png: 120 x 120 (para iPhone)
• AppIcon76x76@2x~ipad.png: 152 x 152 (para iPad)
• AppIcon167x167.png: 167 x 167 (para iPad Pro)
• AppIcon1024x1024.png: 1024 x 1024 (para App Store)

Las distribuciones ad hoc también deben incluir los siguientes nombres de archivo en el paquete de aplicaciones para visualizar la aplicación en iTunes:

• iTunesArtwork 512x512
• iTunesArtwork@2x 1024x1024

La forma más sencilla de añadir los iconos es seguir la documentación de Xcode en Crear catálogos y conjuntos de activos.

Cuando se construye un proyecto con CMake, también debe especificar el siguiente atributo de Xcode para asegurar que los iconos de la aplicación son generados por Xcode.

set_target_properties(app_target_name PROPERTIES
    XCODE_ATTRIBUTE_ASSETCATALOG_COMPILER_APPICON_NAME AppIcon)

A continuación se muestra un ejemplo de cómo un archivo Assets.xcassets/AppIcon.appiconset/Contents.json para Xcode 14 podría parecer:

{
  "images" : [
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "20x20"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "20x20"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "29x29"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "29x29"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "38x38"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "38x38"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "40x40"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "40x40"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "60x60"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "60x60"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "64x64"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "64x64"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "68x68"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "76x76"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "83.5x83.5"
    },
    {
      "filename" : "AppIcon1024x1024.png",
      "idiom" : "universal",
      "platform" : "ios",
      "size" : "1024x1024"
    }
  ],
  "info" : {
    "author" : "xcode",
    "version" : 1
  }
}

Pantallas de inicio e imágenes de inicio

Pantallas de inicio

Cada aplicación iOS debe proporcionar una pantalla de inicio que se mostrará cuando se inicie la aplicación. Una pantalla de inicio es un archivo .xib del creador de la interfaz, también denominado archivo de guión gráfico. Para obtener más información, consulte Especificación de la pantalla de inicio de la aplicación.

La compatibilidad con pantallas de inicio se introdujo en iOS 9.0.

Tanto qmake como CMake generan una pantalla de inicio predeterminada denominada LaunchScreen.storyboard.

Para especificar una pantalla de inicio personalizada, debe copiarse en el paquete de la aplicación y la clave UILaunchStoryboardName debe establecerse con el nombre de la pantalla de inicio en el archivo Info.plist.

Qt soporta pantallas de inicio personalizadas con CMake desde Qt 6.4, y con qmake desde Qt 6.0.

Asumiendo que el archivo de lanzamiento se llama Launch.storyboard, se puede añadir a Info.plist de la siguiente manera:

<key>UILaunchStoryboardName</key>
<string>Launch</string>

Para copiar la pantalla de lanzamiento en el paquete de la aplicación con qmake, utilice el siguiente fragmento de código en el archivo .pro de su proyecto:

ios {
    QMAKE_IOS_LAUNCH_SCREEN = $$PWD/Launch.storyboard
}

Con CMake:

qt_add_executable(app)
if(IOS)
    set_target_properties(app PROPERTIES
        QT_IOS_LAUNCH_SCREEN "${CMAKE_CURRENT_SOURCE_DIR}/Launch.storyboard")
endif()

Imágenes de lanzamiento

También es posible especificar imágenes de lanzamiento (archivos PNG) en lugar de la pantalla de lanzamiento.

Las imágenes de inicio deben copiarse en el paquete de la aplicación y sus nombres deben definirse en el archivo Info.plist mediante la tecla UILaunchImages.

Deben prepararse las siguientes imágenes:

• LaunchImage-iOS7-568h@2x.png: 640 x 1136
• LaunchImage-iOS7-Paisaje.png: 1024 x 768
• LaunchImage-iOS7-Landscape@2x.png: 2048 x 1536
• LaunchImage-iOS7-Retrato.png: 768 x 1024
• LaunchImage-iOS7-Portrait@2x.png: 1536 x 2048
• LaunchImage-iOS7@2x.png: 640 x 960

Las imágenes pueden añadirse a Info.plist del siguiente modo:

<key>UILaunchImages</key>
<array>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7</string>
        <key>UILaunchImageOrientation</key>
        <string>Portrait</string>
        <key>UILaunchImageSize</key>
        <string>{320, 568}</string>
    </dict>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7</string>
        <key>UILaunchImageOrientation</key>
        <string>Portrait</string>
        <key>UILaunchImageSize</key>
        <string>{320, 480}</string>
    </dict>
</array>
<key>UILaunchImages~ipad</key>
<array>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7-Landscape</string>
        <key>UILaunchImageOrientation</key>
        <string>Landscape</string>
        <key>UILaunchImageSize</key>
        <string>{768, 1024}</string>
    </dict>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7-Portrait</string>
        <key>UILaunchImageOrientation</key>
        <string>Portrait</string>
        <key>UILaunchImageSize</key>
        <string>{768, 1024}</string>
    </dict>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7</string>
        <key>UILaunchImageOrientation</key>
        <string>Portrait</string>
        <key>UILaunchImageSize</key>
        <string>{320, 568}</string>
    </dict>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7</string>
        <key>UILaunchImageOrientation</key>
        <string>Portrait</string>
        <key>UILaunchImageSize</key>
        <string>{320, 480}</string>
    </dict>
</array>

Para copiar las imágenes de lanzamiento en el paquete de la aplicación con qmake, utilice el siguiente fragmento de código en el archivo .pro del proyecto:

ios {
    app_launch_images.files = $$files($$PWD/ios/LaunchImage*.png)
    QMAKE_BUNDLE_DATA += app_launch_images
}

Con CMake:

qt_add_executable(app)
file(GLOB_RECURSE launch_images CONFIGURE_DEPENDS "ios/LaunchImage*.png")
if(IOS AND launch_images)
    target_sources(app PRIVATE ${launch_images})
    set_source_files_properties(
        ${launch_images}
        PROPERTIES MACOSX_PACKAGE_LOCATION Resources)
endif()

Selector de imágenes nativo

Si su archivo Info.plist contiene una entrada para NSPhotoLibraryUsageDescription, qmake incluirá automáticamente un complemento adicional que permite el acceso al selector de imágenes nativo.

Para CMake, vincule manualmente el selector de imágenes nativo con qt_import_plugins:

qt_import_plugins(app INCLUDE Qt6::QIosOptionalPlugin_NSPhotoLibraryPlugin)

Si el directorio en su QFileDialog se establece en:

QStandardPaths::standardLocations(QStandardPaths::PicturesLocation).last();

o alternativamente el currentFolder en un FileDialog en QML a:

shortcuts.pictures

entonces se muestra el selector de imágenes nativo para permitir el acceso al álbum de fotos del usuario.

Expresión de las versiones de iOS soportadas

Las plataformas de Apple tienen una forma integrada de expresar las versiones del sistema operativo que admite una aplicación, lo que permite que las versiones más antiguas de las plataformas muestren automáticamente un mensaje de error fácil de usar que pide al usuario que actualice su sistema operativo, en lugar de bloquearse y mostrar un seguimiento de pila.

Los principales conceptos que intervienen a la hora de expresar la compatibilidad con un determinado rango de versiones de SO son:

• El objetivo de implementación especifica la versión mínima de macOS o iOS que admite la aplicación.
• La versión del SDK especifica la versión máxima de macOS o iOS que admite la aplicación.

Cuando desarrolle una aplicación para una plataforma de Apple, debe utilizar siempre la última versión de Xcode y el último SDK disponible en el momento del desarrollo. En algunas plataformas, como iOS, de hecho serás rechazado de la App Store si no lo haces. Por lo tanto, la versión del SDK es siempre mayor o igual que el objetivo de despliegue.

Cuando desarrolle una aplicación para una plataforma Apple, debe establecer el objetivo de despliegue. Varias herramientas de compilación dentro de la cadena de herramientas de Xcode tienen una bandera que se puede utilizar para establecer este valor, incluyendo pero no limitado al compilador y enlazador. Al establecer el valor del objetivo de despliegue, estás declarando explícitamente que tu aplicación debe funcionar al menos en esa versión, y no funcionará con ninguna versión anterior del sistema operativo. Depende de ti asegurarte de que el uso que haces de las APIs del sistema coincide con lo que has declarado. Dado que el compilador sabe lo que has declarado, puede ayudarte a cumplirlo.

La versión del SDK se considera una versión máxima suave del sistema operativo con la que una aplicación es compatible en el sentido de que si la aplicación se construye con un SDK, seguirá utilizando los comportamientos de ese SDK incluso en versiones más recientes del sistema operativo, porque el sistema operativo comprueba los comandos de carga del binario y emula la compatibilidad hacia atrás con el sistema operativo anterior. Por ejemplo, si una aplicación se construye con el SDK de macOS 10.12, seguirá utilizando los comportamientos de 10.12 incluso en 10.13 y superiores.

Sin embargo, los binarios de macOS son intrínsecamente compatibles con versiones anteriores. Por ejemplo, una aplicación creada con el SDK de iOS 9 funcionará perfectamente en iOS 10, pero es posible que no se le apliquen los cambios de comportamiento que se hayan realizado en determinadas funciones de la nueva versión hasta que la aplicación se vuelva a compilar con el SDK más reciente.

La versión mínima del sistema operativo puede ser expresada al sistema por las banderas del compilador y del enlazador que la incrustan en el binario Mach-O. Además, se debe establecer la clave LSMinimumSystemVersion en el paquete de aplicaciones de la aplicación. Este valor debe ser igual al valor pasado al compilador y enlazador, porque en macOS permitirá que el sistema operativo muestre un diálogo de error fácil de usar que dice que la aplicación requiere una versión más reciente del sistema operativo en lugar de un diálogo de bloqueo. El LSMinimumSystemVersion es también la clave que la App Store utiliza para mostrar la versión requerida del sistema operativo, el compilador y enlazador banderas no tienen poder allí.

En su mayor parte, las aplicaciones Qt funcionarán sin problemas. Por ejemplo, en qmake, los mkspecs de Qt establecen QMAKE_IOS_DEPLOYMENT_TARGET o QMAKE_MACOSX_DEPLOYMENT_TARGET a la versión mínima que Qt mismo soporta. Del mismo modo, en Qbs, los módulos Qt establecen cpp.minimumIosVersion, cpp.minimumMacosVersion, cpp.minimumTvosVersion, o cpp.minimumWatchosVersion a la versión mínima que soporta Qt.

Sin embargo, debes tener cuidado cuando establezcas manualmente tu propia versión objetivo. Si la establece en un valor superior al que Qt requiere y suministra su propio archivo Info.plist, debe añadir una entrada LSMinimumSystemVersion a Info.plist que coincida con el valor del objetivo de despliegue, porque el SO usará el valor LSMinimumSystemVersion como el autoritativo.

Si especifica un valor de objetivo de despliegue inferior al que Qt requiere, la aplicación se bloqueará casi con toda seguridad en algún lugar de las librerías Qt cuando se ejecute en una versión anterior a la que Qt soporta. Por lo tanto, asegúrese de que el código del sistema de compilación refleja la versión mínima del sistema operativo que realmente se requiere.

Publicación en el App Store de Apple

La verificación de que la aplicación Qt para iOS está lista para su publicación en la App Store puede realizarse como se describe en Envío de la aplicación. Para enviar la aplicación, puede utilizar Xcode o el cargador de aplicaciones (que se instala con Xcode). Qt Creator no proporciona una interfaz para gestionar todos los ajustes de configuración de un proyecto de Xcode.

La aplicación debe probarse en las versiones de iOS y en los dispositivos para los que está diseñada. El objetivo de implementación mínimo para las aplicaciones Qt varía según la versión de Qt. Para obtener más información, consulte las configuraciones compatibles.

El proceso de publicación real implica la creación de un certificado de distribución y un perfil de suministro, la creación de un archivo firmado de la aplicación y la ejecución de un conjunto de pruebas de validación.

Consulte la Guía de distribución de aplicaciones en iOS Developer Library para obtener más información.

Advertencias de visibilidad de símbolos

En el contexto de la vinculación de bibliotecas C++, las funciones y los objetos se denominan símbolos. Los símbolos pueden tener visibilidad en default o hidden.

Por razones de rendimiento, Qt y muchas otras bibliotecas compilan sus fuentes utilizando la visibilidad hidden por defecto, y sólo marcan los símbolos con la visibilidad default cuando están destinados a ser utilizados en proyectos de usuario.

Desafortunadamente, el enlazador de Apple puede emitir advertencias cuando una librería se compila con visibilidad hidden y una aplicación o librería de un proyecto de usuario se compila con visibilidad default.

Si los desarrolladores de proyectos quieren silenciar la advertencia, tienen que compilar el código de su proyecto también con visibilidad hidden.

En CMake se puede hacer añadiendo el siguiente código a su CMakeLists.txt:

set(CMAKE_CXX_VISIBILITY_PRESET hidden)

En qmake que se puede hacer mediante la adición del siguiente código a su .pro archivo:

CONFIG+=hide_symbols

En caso de que un proyecto construya librerías, cualquier símbolo en la librería que vaya a ser usado en otra librería o aplicación tendrá que ser marcado explícitamente con la visibilidad default. Por ejemplo, esto puede hacerse anotando dichas funciones o clases con Q_DECL_EXPORT.

Problema de archivado de productos con CMake

Debido a un problema en CMake, intentar crear un archivo de producto con una aplicación iOS puede fallar.

Esto puede ocurrir tanto al intentar crear el archivo en Xcode utilizando el elemento de menú Producto -> Archivo, o desde la línea de comandos utilizando xcodebuild -archivePath.

El mensaje de error puede hacer referencia a símbolos no definidos o a rutas de archivo inexistentes.

Para solucionar el problema, asegúrese de crear una versión Release del proyecto antes de intentar crear un archivo.

Falta el paquete dSYM en xcarchive creado por un proyecto CMake Xcode

Debido a un error en Xcode y a ciertas limitaciones de CMake, un proyecto Xcode generado por CMake no incluirá el paquete dSYM de una aplicación en xcarchive, durante la tarea de archivado de Xcode.

Qt ofrece una solución opcional para que el paquete dSYM se incluya en xcarchive, pero tiene sus inconvenientes. Es decir, las siguientes características de CMake no funcionarán correctamente:

• cualquier expresión del generador $<TARGET_FILE:app> podría expandirse a una ruta no válida que no lleve al binario de la aplicación
• la variable CMAKE_RUNTIME_OUTPUT_DIRECTORY y su propiedad de destino asociada RUNTIME_OUTPUT_DIRECTORY se ignorarán incluso si se establecen
• otros problemas desconocidos

Para mitigar los problemas anteriores, puede:

• activar la solución alternativa sólo cuando vaya a crear xcarchive y no durante el desarrollo del proyecto
• asegúrate de que sólo añades ejecutables y bibliotecas en el directorio raíz del proyecto, y no en las llamadas a add_subdirectory.

Para activar la solución, configure el proyecto con la siguiente opción:

cmake . -DQT_USE_RISKY_DSYM_ARCHIVING_WORKAROUND=ON

o establezca la variable en el proyecto antes de cualquier llamada a qt_add_executable o qt_add_library:

set(QT_USE_RISKY_DSYM_ARCHIVING_WORKAROUND ON)

...

qt_add_executable(app)