Carthage: qué es, gestor de dependencias descentralizado

¿Qué es Carthage?

Carthage es un gestor de dependencias con arquitectura descentralizada, creado en 2014 por desarrolladores de la comunidad Swift. Carthage no utiliza un registro central de especificaciones — cada biblioteca se conecta directamente desde un repositorio Git mediante URL o nombre en GitHub. Carthage descarga el código fuente, lo compila en un framework binario (.xcframework o .framework) y proporciona al desarrollador un artefacto listo para la integración manual en un proyecto Xcode.

La arquitectura de Carthage incluye tres componentes: la herramienta CLI carthage, el archivo de configuración Cartfile y el directorio Carthage/Build/ con los frameworks compilados. La diferencia clave entre Carthage y CocoaPods es la ausencia de modificación automática de .xcodeproj. Carthage no crea .xcworkspace, no configura flags del compilador ni genera Pods.xcconfig. El desarrollador añade manualmente los frameworks al proyecto mediante Xcode, lo que proporciona control total sobre el proceso de integración.

Carthage utiliza compilación paralela de dependencias, lo que acelera significativamente el proceso en procesadores multinúcleo. Cada dependencia se compila como un destino separado, y Carthage resuelve automáticamente el grafo de dependencias transitivas, compilándolas en el orden correcto. Según benchmarks de la comunidad, Carthage compila 15–20 dependencias en un promedio de 30–60 segundos en Mac modernos, lo que es más rápido que CocoaPods para proyectos con muchas bibliotecas. Carthage es compatible con todas las plataformas Apple: iOS, macOS, watchOS y tvOS, y desde la versión 0.38+ — compilación de .xcframework universal para soporte de simulador y dispositivos Apple Silicon.

Cómo funciona Carthage

Carthage clona el repositorio Git de cada dependencia, cambia a la versión especificada (tag, commit o rama) y ejecuta xcodebuild para compilar el framework. Carthage determina automáticamente el tipo de proyecto Xcode (framework, dynamic framework, librería estática) según el esquema de compilación. Si un proyecto tiene múltiples esquemas, Carthage usa el esquema por defecto (primero en orden alfabético). Después de compilar, Carthage copia el framework terminado en Carthage/Build/ y crea un archivo Cartfile.resolved con fijación de versiones exactas. Carthage admite el almacenamiento en caché de frameworks compilados — la recompilación sin cambios en las dependencias se omite.

Las dependencias transitivas en Carthage se manejan a través de Cartfile.resolved: Carthage construye un grafo de todas las dependencias necesarias y las compila en el orden correcto. Si dos bibliotecas dependen de la misma biblioteca de terceros, Carthage la compila una vez y la usa para ambas. Carthage informa errores de compilación indicando el destino específico y la causa — esto simplifica el diagnóstico de problemas.

Cartfile: estructura, sintaxis y ejemplos

Cartfile es un archivo de configuración con sintaxis similar a Ruby (formato Cartfile) que define las dependencias de un proyecto Carthage. Cartfile se encuentra en la raíz del proyecto junto a .xcodeproj. Cada línea de Cartfile describe una dependencia: la fuente (URL Git, repositorio GitHub) y la versión. La sintaxis admite fijación de versiones mediante tags, commits y ramas.

# Dependencias básicas de Carthage
github "Alamofire/Alamofire" ~> 5.9
github "SnapKit/SnapKit" ~> 5.7
github "onevcat/Kingfisher" == 8.0.0

La directiva github "Owner/Repo" es una forma abreviada para repositorios de GitHub. Carthage construye automáticamente la URL https://github.com/Owner/Repo.git. Para GitLab, Bitbucket y otros hosts Git, se usa la URL completa: git "https://gitlab.com/owner/repo.git". Operadores de versión: ~> 5.9 (cualquier versión desde 5.9 hasta 6.0, excluyendo 6.0), == 8.0.0 (versión exacta), >= 1.0 (versión mínima). Se puede fijar un commit específico mediante github "owner/repo" "abc1234".

Ejemplo completo de Cartfile

Carthage admite múltiples directorios para diferentes configuraciones: Cartfile (principal), Cartfile.private (para dependencias internas que no se publican) y Cartfile.resolved (generado automáticamente). Las dependencias privadas son útiles para bibliotecas utilizadas solo en compilaciones de desarrollo, como frameworks de prueba.

# Cartfile — dependencias principales
github "Alamofire/Alamofire" ~> 5.9
github "SwiftyJSON/SwiftyJSON" ~> 4.0
github "realm/realm-swift" ~> 10.0

# URL completa para GitLab
git "https://gitlab.com/company/internal-lib.git" == 2.1.1

# Rama de desarrollo
github "marmelroy/PhoneNumberKit" "development"

github y git son dos tipos de fuentes en Cartfile. El primero es exclusivamente para GitHub y genera automáticamente la URL. El segundo es para cualquier repositorio Git público o privado con URL completa. Una versión puede especificarse como tag (== 2.1.1), rango semántico (~> 5.9), nombre de rama ("development") o hash de commit ("a1b2c3d"). Se recomiendan los rangos semánticos (~>) para dependencias que siguen SemVer — esto protege contra cambios disruptivos durante las actualizaciones.

Cartfile.resolved se genera automáticamente después de carthage update. Fija las versiones exactas de todas las dependencias instaladas, incluidas las transitivas. Este archivo debe mantenerse en Git — sin él, el comando carthage bootstrap en otra máquina compilará las bibliotecas con las mismas reglas, pero las versiones pueden diferir. carthage outdated muestra una lista de dependencias desactualizadas para las que hay nuevas versiones disponibles.

Instalación y configuración de Carthage

Carthage se instala mediante Homebrew — el gestor de paquetes estándar para macOS. Métodos alternativos: instalación desde un instalador .pkg compilado de GitHub o compilación desde código fuente. Carthage requiere Xcode con Command Line Tools (incluyendo xcodebuild), y en Mac con Apple Silicon — Rosetta 2 para algunas dependencias heredadas.

# Instalación de Carthage a través de Homebrew
brew install carthage

# Verificación de versión
carthage version

# Instalación desde .pkg (si Homebrew no está disponible)
# Descargar Carthage.pkg desde GitHub Releases e instalar manualmente

Después de instalar Carthage, la inicialización del proyecto comienza con la creación de un Cartfile en la raíz del proyecto. Carthage no tiene comando init — el archivo se crea manualmente en un editor de texto. Después de llenar el Cartfile con dependencias, el desarrollador ejecuta carthage bootstrap (si ya existe Cartfile.resolved) o carthage update (instalación inicial o actualización). Carthage clona los repositorios, compila los frameworks y los coloca en Carthage/Build/.

Actualizar Carthage se hace mediante brew upgrade carthage. La versión se verifica con carthage version. La última versión estable a mediados de 2025 es la 0.40 con soporte predeterminado de .xcframework, compilación paralela mejorada y soporte completo de Swift 6. A partir de la versión 0.39, Carthage dejó de compilar .framework heredados sin un shim de compatibilidad — se recomienda especificar explícitamente --use-xcframeworks.

# Actualización de Carthage a través de Homebrew
brew upgrade carthage

# Instalar una versión específica
brew install carthage@0.39

# Reinstalación completa
brew uninstall carthage && brew install carthage

Nota: Carthage no crea .xcworkspace ni modifica .xcodeproj. A diferencia de CocoaPods, Carthage deja el control total de la configuración de Xcode al desarrollador. Esto significa que después de instalar las dependencias, es necesario añadir manualmente los frameworks a Xcode (consulte la sección «Integración de frameworks Carthage en Xcode»). Carthage también requiere que cada dependencia contenga un proyecto Xcode o workspace con un target de framework — de lo contrario, la compilación fallará.

Compilación de frameworks: bootstrap y update

Carthage ofrece tres comandos principales para trabajar con dependencias: bootstrap, update y build. carthage bootstrap compila dependencias desde un Cartfile.resolved existente — recomendado para entornos CI y desarrolladores que se unen al proyecto. carthage update actualiza Cartfile.resolved a las últimas versiones (respetando las restricciones de Cartfile) y realiza la compilación. carthage build compila todas las dependencias especificadas sin guardar versiones.

# Instalación inicial (actualiza versiones)
carthage update --use-xcframeworks --platform iOS

# Recompilación con versiones fijadas
carthage bootstrap --use-xcframeworks --platform iOS

# Compilar solo una dependencia
carthage build Alamofire --platform iOS

El flag --use-xcframeworks indica a Carthage que compile .xcframework universales en lugar de los .framework heredados. Esto garantiza soporte tanto para el simulador como para un dispositivo real, así como para Mac con Apple Silicon sin scripts adicionales. El flag --platform iOS limita la compilación a una sola plataforma iOS — esto acelera significativamente el proceso, especialmente si el proyecto incluye bibliotecas multiplataforma.

Carthage admite compilación paralela mediante el flag --cache-builds, que almacena en caché los frameworks ya compilados. Al recompilar, Carthage verifica el hash del commit Git y, si el código no ha cambiado, omite la compilación. Para servidores CI, se recomienda almacenar en caché el directorio Carthage/Build/ y ~/Library/Caches/carthage/. Carthage también admite --verbose para registro detallado y --no-use-binaries para compilación forzada desde código fuente (si el desarrollador no confía en los binarios precompilados).

Integración de frameworks Carthage en Xcode

La integración de frameworks Carthage en Xcode se realiza manualmente en cuatro pasos. Después de ejecutar carthage update o bootstrap, todos los frameworks compilados se encuentran en Carthage/Build/iOS/ (o la plataforma correspondiente). El desarrollador abre el proyecto Xcode, selecciona el target de la aplicación y añade los frameworks en General → Frameworks, Libraries, and Embedded Content. Para frameworks en tiempo de ejecución (bibliotecas dinámicas), debe seleccionar «Embed & Sign» — de lo contrario, la aplicación fallará al iniciar con el error «dyld: Library not loaded».

Carthage para bibliotecas estáticas es más simple — no requieren fase de embed ya que se enlazan directamente en el archivo ejecutable de la aplicación. Sin embargo, Carthage compila frameworks dinámicos por defecto (excepto para bibliotecas estáticas explícitamente configuradas). Para proyectos donde es importante minimizar el tamaño de la aplicación, se recomienda el enlace estático mediante la configuración de Xcode.

Un paso adicional es añadir Input Files en Build Phase → Run Script. Carthage requiere un script para eliminar artefactos del simulador del framework compilado (strip simulator architectures). Este script es necesario para compilaciones de App Store:

# Run Script completa para App Store (strip simulator architectures)
FRAMEWORKS_DIR="${SRCROOT}/Carthage/Build/iOS"
for framework in "$FRAMEWORKS_DIR"/*.framework; do
  bash "$BUILD_DIR/src/scripts/strip-framework.sh" "$framework"
done

Carthage no requiere usar .xcworkspace — todas las dependencias ya están compiladas en frameworks binarios. Carthage funciona directamente con .xcodeproj, a diferencia de CocoaPods, que crea un workspace. Esto simplifica el control de versiones y la configuración de CI, porque las dependencias de Carthage no cambian la configuración del proyecto Xcode. El único cambio es añadir frameworks al target, lo que se registra en .pbxproj.

Carthage vs CocoaPods vs Swift Package Manager

Carthage, CocoaPods y Swift Package Manager (SPM) son los tres principales gestores de dependencias en el desarrollo iOS. Carthage destaca por su enfoque descentralizado, CocoaPods ofrece un registro centralizado, y SPM es la solución integrada de Apple. La elección entre ellos depende de los requisitos del proyecto, el tamaño del equipo y el nivel de automatización deseado.

Carthage se elige para proyectos que requieren una interferencia mínima con la configuración de Xcode y control total sobre el proceso de integración. Carthage es ideal para bibliotecas y frameworks de código abierto donde el autor quiere permitir a los usuarios compilar dependencias de forma independiente. Carthage también es popular entre los desarrolladores que valoran la filosofía UNIX: cada herramienta hace bien una cosa. CocoaPods sigue siendo el estándar para proyectos empresariales con docenas de dependencias donde la automatización es importante. SPM es la elección para proyectos nuevos, ya que está integrado en Xcode y es desarrollado activamente por Apple.

La migración entre gestores requiere diferentes enfoques. Carthage → SPM: eliminar frameworks de Xcode, borrar Cartfile y añadir Package Dependencies mediante File → Add Package Dependencies. Carthage → CocoaPods: eliminar frameworks de Carthage, crear un Podfile, añadir dependencias y ejecutar pod init && pod install. Al migrar de Carthage a CocoaPods o SPM, desaparece la necesidad de actualizar manualmente los frameworks — todas las dependencias se actualizan con un solo comando. Carthage sigue siendo relevante para proyectos donde es importante evitar vendor lock-in y mantener la transparencia de la compilación de dependencias.

Problemas comunes y sus soluciones

Carthage es una herramienta estable, pero los desarrolladores se encuentran periódicamente con problemas típicos, especialmente al compilar en servidores CI, actualizar Xcode o cambiar versiones de Swift. La mayoría de los problemas se resuelven limpiando la caché, configurando correctamente --use-xcframeworks y verificando la versión mínima de iOS.

Error «The file manager returned an error» — ocurre cuando la caché de Carthage está corrupta o hay un conflicto de permisos de archivos. Solución: eliminar la caché con rm -rf ~/Library/Caches/carthage y reiniciar carthage bootstrap. También ayuda eliminar el directorio Carthage/ en el proyecto y recompilar. En servidores CI, la caché de Carthage solo debe actualizarse cuando cambie Cartfile.resolved.

Error «No such module» — el framework no se encuentra en Xcode aunque la compilación de Carthage fue exitosa. Solución: verificar la ruta del framework en General → Frameworks, Libraries, and Embedded Content. El framework debe estar en Carthage/Build/iOS/. Asegurarse de que .xcframework esté añadido correctamente (arrastrarlo de nuevo). Para frameworks dinámicos, verificar Embed & Sign. Si el error persiste, añadir FRAMEWORK_SEARCH_PATHS en Build Settings.

Error de compilación por incompatibilidad de Swift — la biblioteca se compiló para una versión diferente de Swift que el proyecto. Solución: usar carthage update --no-use-binaries para forzar la compilación desde código fuente con la misma versión de Swift. Si la biblioteca no compila con la versión actual, usar .xcconfig para especificar la versión de Swift o hacer un fork de la biblioteca. Desde Carthage 0.39, --use-xcframeworks incluye automáticamente la versión correcta de Swift en el binario.

Problemas con compilación en CI — Carthage en CI requiere una configuración adecuada de caché. Solución: almacenar en caché Carthage/Build/ y ~/Library/Caches/carthage/. Usar carthage bootstrap --use-xcframeworks --platform iOS en lugar de update en CI para evitar cambiar versiones. Hay una acción oficial de Carthage disponible para GitHub Actions. Para Jenkins — el plugin CarthageBuild. Carthage puede fallar en macOS sin GUI — solución: instalar brew install xcode-build-server o añadir el flag -UseModernBuildSystem=NO.