Crear un SDK iOS usando XCFramework

15 de junio, 2025

Crear un SDK para iOS tradicionalmente implica generar múltiples builds para diferentes arquitecturas, lo que complica la distribución de los binarios.

En este tutorial revisaremos paso a paso cómo crear un XCFramework , empaquetando todas las arquitecturas en un solo bundle y eliminando los "Fat Binaries" pesados y los builds separados.

A diferencia de CocoaPods o SPM —que distribuyen dependencias exponiendo el código fuente— XCFramework distribuye código ya compilado. Es la opción ideal para SDKs comerciales, bibliotecas internas o cualquier escenario donde necesites entregar funcionalidad sin revelar la implementación, garantizando compatibilidad universal independientemente del método de integración del cliente.

Prerrequisitos: Xcode 15 o superior, nociones básicas de Swift y acceso a una terminal con permisos para ejecutar xcodebuild.

Crear el proyecto del SDK

  • Abre Xcode y selecciona "Create New Project..."
  • Selecciona la plataforma "iOS"
  • Ahora en la sección "Framework & Library" , selecciona el template "Framework"
    Selección del template "Framework" en Xcode al crear un nuevo proyecto
  • Escribe el nombre que le quieres dar a tu SDK
  • Escribe el identificador de organización , usando " reverse domain name notation "
  • Selecciona Swift como lenguaje para el SDK
    Configuración del nombre, identificador de organización y lenguaje Swift del SDK en Xcode

Implementación del SDK

Una vez creado el proyecto, es momento de implementar la lógica de tu SDK y definir la API de acceso que usarán las apps que lo integren.

Durante la compilación, todos los elementos (clases, protocolos, enums, estructuras, funciones, etc.) marcados como public quedarán expuestos para uso externo. Cualquier otro elemento permanecerá como componente interno del SDK.

public class Foo {

    // Permite instanciar esta clase fuera del SDK
    public init() {}
    
    public func bar() -> Bool {
        return true
    }

}

Compilar el XCFramework para distribución

Ahora vamos a compilar el XCFramework usando xcodebuild para diferentes arquitecturas. Usaremos tres comandos: dos para compilar el SDK para cada arquitectura y uno para empaquetar todo en un XCFramework.

En los comandos siguientes, mysdk es un placeholder — reemplázalo por el nombre real de tu proyecto (el mismo que usaste al crearlo en Xcode).

Compilar el SDK para iPhone y Simulator

iOS Device 

xcodebuild archive \
    -project "mysdk.xcodeproj" \
    -scheme "mysdk" \
    -configuration Release \
    -destination 'generic/platform=iOS' \
    -archivePath "build/iphone.xcarchive" \
    SKIP_INSTALL=NO \
    BUILD_LIBRARY_FOR_DISTRIBUTION=YES

Este comando genera el framework optimizado para dispositivos físicos iPhone/iPad.

iOS Simulator 

xcodebuild archive \
    -project "mysdk.xcodeproj" \
    -scheme "mysdk" \
    -configuration Release \
    -destination 'generic/platform=iOS Simulator' \
    -archivePath "build/simulator.xcarchive" \
    SKIP_INSTALL=NO \
    BUILD_LIBRARY_FOR_DISTRIBUTION=YES

Este comando crea la versión para simulador (x86_64 y ARM64 para Macs con Apple Silicon).

La flag BUILD_LIBRARY_FOR_DISTRIBUTION=YES habilita la module stability , permitiendo que el XCFramework siga siendo compatible con futuras versiones del compilador de Swift. Es obligatoria al distribuir un SDK como binario.
Si deseamos omitir el firmado de los binarios compilados, se debe añadir a ambos comandos los siguientes argumentos:
CODE_SIGNING_REQUIRED=NO
CODE_SIGNING_ALLOWED=NO
CODE_SIGN_IDENTITY=''

Crear el XCFramework 

xcodebuild -create-xcframework \
    -framework "build/iphone.xcarchive/Products/Library/Frameworks/mysdk.framework" \
    -framework "build/simulator.xcarchive/Products/Library/Frameworks/mysdk.framework" \
    -output "build/mysdk.xcframework"

Esto genera una carpeta con el XCFramework en la ruta "build/mysdk.xcframework" lista para distribuir.

Consumir el XCFramework desde una app

Una vez generado el .xcframework, cualquier proyecto iOS puede integrarlo siguiendo estos pasos:

  1. Arrastra mysdk.xcframework al navegador de proyecto en Xcode.
  2. En la pestaña "General" del target, dentro de "Frameworks, Libraries, and Embedded Content" , asegúrate de que aparezca como "Embed & Sign" .
  3. Ya puedes importarlo desde cualquier archivo Swift de tu app:¬
import mysdk

let foo = Foo()
print(foo.bar())

Distribución del XCFramework

Tienes varias opciones para hacer llegar el binario a tus clientes o equipos:

  • GitHub Releases : comprime la carpeta mysdk.xcframework en un .zip y adjúntala a una release versionada. Es la alternativa más simple para SDKs open-source o internos con acceso al repositorio.
  • Swift Package Manager con `binaryTarget` : expón el XCFramework como un paquete SPM remoto. Los consumidores lo agregan con una URL y una versión, obteniendo control explícito de actualizaciones.
  • Registro privado o CDN : para SDKs comerciales, publica el ZIP en un servidor propio con autenticación y firma su checksum para garantizar integridad.

Conclusiones

Con el XCFramework generado ya puedes distribuir tu SDK a cualquier app iOS que quiera implementarlo. Obtienes un paquete profesional que funciona universalmente en dispositivos y simuladores, sin configuraciones adicionales para los desarrolladores que lo consumen.