XCFramework: qué es, formato de distribución binaria y aplicación

¿Qué es XCFramework?

XCFramework es un formato de empaquetado para bibliotecas y frameworks binarios presentado por Apple en la WWDC 2019. Su objetivo principal es crear un único bundle que contenga versiones compiladas de una biblioteca para todas las plataformas y arquitecturas de destino.

Antes de XCFramework, los desarrolladores usaban .framework con fat binaries que combinaban múltiples arquitecturas mediante la utilidad lipo. Este enfoque causaba problemas: al compilar un proyecto para el simulador, el fat binary contenía tanto la arquitectura del simulador como la del dispositivo, lo que provocaba errores al enviar la compilación a la App Store. Los desarrolladores tenían que escribir fases Run Script para eliminar las arquitecturas innecesarias.

Según la Documentación para Desarrolladores de Apple (2024), XCFramework admite todas las plataformas del ecosistema Apple: iOS, iPadOS, macOS, tvOS, watchOS, visionOS y aplicaciones Catalyst. Cada plataforma recibe un slice separado dentro del paquete, lo que elimina los conflictos de arquitectura y simplifica la distribución de SDK.

¿Cuándo se necesita XCFramework?

XCFramework se utiliza en tres escenarios principales: distribución de SDK cerrados a desarrolladores externos, distribución de módulos nativos para Flutter y React Native, y publicación de bibliotecas que requieren precompilación. El formato es obligatorio para todos los SDK nuevos publicados en el ecosistema Apple.

Los desarrolladores eligen XCFramework cuando el código fuente no se puede divulgar, cuando la biblioteca utiliza algoritmos propietarios o cuando se requiere protección de licencia. A diferencia de Swift Package Manager, que trabaja con código fuente, XCFramework entrega archivos binarios ya compilados.

¿Cómo resuelve XCFramework el problema del fat binary?

El problema del fat binary era que un binario universal contenía múltiples arquitecturas en un solo archivo Mach-O. Al compilar una aplicación para el simulador, Xcode incluía tanto la arquitectura arm64 del dispositivo como la x86_64 del simulador — la App Store solo aceptaba la arquitectura del dispositivo.

La solución tradicional implicaba agregar una fase Run Script que llamara a lipo para eliminar las arquitecturas del simulador de la compilación final. Este enfoque era frágil y se rompía con las actualizaciones de Xcode o cuando aparecían nuevas arquitecturas (por ejemplo, arm64 para el simulador en Apple Silicon).

Según Swift.org (2023), el equipo de Swift Package Manager se encontró inicialmente con este problema al intentar admitir dependencias binarias. XCFramework lo resolvió a nivel de formato: cada slice es una carpeta separada con un Info.plist que describe la plataforma y arquitectura de destino. Xcode selecciona automáticamente el slice necesario durante la compilación, sin requerir posprocesamiento.

Ventajas del enfoque de slices separados

Cada slice en XCFramework contiene solo una combinación de plataforma y arquitectura. Por ejemplo, ios-arm64 contiene el binario solo para dispositivos iOS, e ios-x86_64-simulator solo para el simulador de Intel Mac. Xcode selecciona automáticamente el slice correcto, eliminando la necesidad de scripts de eliminación de arquitecturas y reduciendo el riesgo de errores de compilación.

El slice ios-arm64-x86_64-simulator se introdujo para admitir Mac con Apple Silicon. Anteriormente, el simulador requería un binario separado para arm64 (Apple Silicon) y x86_64 (Intel). XCFramework permite un fat binary dentro de un solo slice de simulador — esta es la única excepción donde el fat binary está justificado.

Estructura del paquete XCFramework

Un paquete XCFramework es un directorio con extensión .xcframework, que contiene un Info.plist en el nivel superior y carpetas con slices binarios. Cada slice incluye una biblioteca .framework o .a para una plataforma específica.

MyLibrary.xcframework/
  Info.plist
  ios-arm64/
    MyLibrary.framework/
      Info.plist
      MyLibrary
  ios-x86_64-simulator/
    MyLibrary.framework/
      Info.plist
      MyLibrary
  macos-arm64-x86_64/
    MyLibrary.framework/
      Info.plist
      MyLibrary

El Info.plist del paquete contiene la clave AvailableLibraries, que enumera LibraryIdentifier, LibraryPath y SupportedPlatform para cada slice. Xcode lee este archivo al agregar un XCFramework al proyecto y configura automáticamente las rutas de búsqueda y la fase Embed Frameworks.

Cada slice es un .framework completo o una biblioteca estática con su propio Info.plist. Esto permite que XCFramework admita tipos mixtos: bibliotecas estáticas para algunas plataformas y frameworks dinámicos para otras, aunque en la práctica se usa un tipo para todos los slices.

Crear XCFramework desde la línea de comandos

La creación de un XCFramework se realiza mediante xcodebuild -create-xcframework. El comando toma bibliotecas .framework o .a ya compiladas para cada plataforma y las combina en un solo paquete.

El proceso consta de dos pasos: primero, se compilan los binarios para cada plataforma de destino, luego se empaquetan en un XCFramework. Para la compilación se utilizan los flags de destination estándar de Xcode.

# Step 1: build frameworks for each platform
xcodebuild archive -scheme MyLibrary -destination "generic/platform=iOS Simulator"
xcodebuild archive -scheme MyLibrary -destination "generic/platform=iOS"
xcodebuild archive -scheme MyLibrary -destination "generic/platform=macOS"

# Step 2: create XCFramework
xcodebuild -create-xcframework -framework ./iOS/MyLibrary.framework -framework ./iOSSim/MyLibrary.framework -framework ./macOS/MyLibrary.framework -output ./MyLibrary.xcframework

El flag -create-xcframework se introdujo en Xcode 11. El comando crea automáticamente la estructura de directorios correcta y genera un Info.plist con la descripción de todas las plataformas. Si uno de los .framework está dañado o compilado con la arquitectura incorrecta, xcodebuild devuelve un error en la fase de validación.

Automatización mediante scripts de compilación

Para CI/CD se utiliza un script de shell que automatiza la compilación para todas las plataformas y la creación del XCFramework. Un enfoque popular es un envoltorio en forma de Makefile o Fastlane lane con parametrización de scheme y ruta de salida.

# build_xcframework.sh - automation script
set -e
SCHEME="MyLibrary"
OUTPUT="./build"

xcodebuild archive -scheme "$SCHEME" -sdk iphonesimulator -archivePath "$OUTPUT/sim.xcarchive"
xcodebuild archive -scheme "$SCHEME" -sdk iphoneos -archivePath "$OUTPUT/dev.xcarchive"
xcodebuild -create-xcframework -framework "$OUTPUT/dev.xcarchive/Products/Library/Frameworks/MyLibrary.framework" -framework "$OUTPUT/sim.xcarchive/Products/Library/Frameworks/MyLibrary.framework" -output "$OUTPUT/MyLibrary.xcframework"

Este script se ejecuta en un pipeline de CI (GitHub Actions, Bitrise, Jenkins) después de pasar las pruebas. El XCFramework resultante se archiva y se carga como un artefacto de lanzamiento o se publica a través de un gestor de dependencias como CocoaPods mediante pod spec.

Integrar XCFramework en un proyecto Xcode

Integrar un XCFramework en un proyecto de Xcode no requiere configuración manual de rutas de búsqueda. Basta con arrastrar el .xcframework a la sección Frameworks, Libraries, and Embedded Content en la configuración General del target.

A diferencia de .framework, XCFramework no requiere agregar una fase Run Script para eliminar las arquitecturas del simulador. Xcode determina automáticamente los slices disponibles e incluye solo los necesarios para el esquema de compilación actual. Para un dispositivo físico se usa el slice ios-arm64, para el simulador — ios-arm64-x86_64-simulator o ios-x86_64-simulator.

import MyLibrary

func processData() {
    // XCFramework resolves the correct slice at build time
    let processor = DataProcessor()
    let result = processor.analyze(input: "sample")
    print(result)
}

Para CocoaPods, la integración se realiza mediante un podspec con vendored_frameworks y una lista de plataformas compatibles. El gestor de dependencias determina automáticamente qué slices necesita el proyecto. Muchos SDK comerciales — Firebase, Adjust, AppsFlyer — han migrado a XCFramework para simplificar la instalación.

Comparación entre XCFramework y Swift Package Manager

Swift Package Manager y XCFramework no compiten, sino que se complementan. SPM trabaja con código fuente y compila las dependencias en cada compilación del proyecto. XCFramework proporciona binarios listos sin requerir compilación en el lado del consumidor.

• XCFramework — distribución binaria, protección del código fuente, compatibilidad con todas las plataformas Apple en un solo paquete
• SPM — código abierto, posibilidad de inspección, compilación automática para la plataforma de destino
• Las dependencias binarias de SPM utilizan XCFramework como formato de empaquetado, combinando ambos enfoques

Con el lanzamiento de Swift Package Manager 5.3, Apple agregó soporte para dependencias binarias — ahora SPM puede descargar un XCFramework como dependencia remota. Package.swift especifica la URL del artefacto binario y su suma de verificación para la verificación.

Según la documentación de Swift Package Manager (2024), se recomiendan las dependencias binarias para SDK que no divulgan el código fuente, o para bibliotecas cuyo tiempo de compilación es desproporcionadamente largo. Para proyectos de código abierto, se prefiere la distribución de código fuente mediante SPM.