Carthage: o que é, gerenciador de dependências descentralizado

O que é Carthage?

Carthage é um gerenciador de dependências com arquitetura descentralizada, criado em 2014 por desenvolvedores da comunidade Swift. O Carthage não usa um registro central de especificações — cada biblioteca é conectada diretamente de um repositório Git via URL ou nome no GitHub. O Carthage baixa o código fonte, compila-o em um framework binário (.xcframework ou .framework) e fornece ao desenvolvedor um artefato pronto para integração manual em um projeto Xcode.

A arquitetura do Carthage inclui três componentes: a ferramenta CLI carthage, o arquivo de configuração Cartfile e o diretório Carthage/Build/ com os frameworks compilados. A diferença chave entre Carthage e CocoaPods é a ausência de modificação automática do .xcodeproj. O Carthage não cria .xcworkspace, não configura flags do compilador e não gera Pods.xcconfig. O desenvolvedor adiciona manualmente os frameworks ao projeto via Xcode, proporcionando controle total sobre o processo de integração.

Carthage usa compilação paralela de dependências, o que acelera significativamente o processo em processadores multi-core. Cada dependência é compilada como um alvo separado, e o Carthage resolve automaticamente o grafo de dependências transitivas, compilando-as na ordem correta. De acordo com benchmarks da comunidade, o Carthage compila 15–20 dependências em média de 30–60 segundos em Macs modernos, o que é mais rápido que o CocoaPods para projetos com muitas bibliotecas. O Carthage suporta todas as plataformas Apple: iOS, macOS, watchOS e tvOS, e desde a versão 0.38+ — compilação de .xcframework universal para suporte a simulador e dispositivos Apple Silicon.

Como o Carthage funciona

Carthage clona o repositório Git de cada dependência, muda para a versão especificada (tag, commit ou ramo) e executa xcodebuild para compilar o framework. O Carthage determina automaticamente o tipo de projeto Xcode (framework, dynamic framework, biblioteca estática) pelo esquema de compilação. Se um projeto tem múltiplos esquemas, o Carthage usa o esquema padrão (primeiro em ordem alfabética). Após a compilação, o Carthage copia o framework pronto para Carthage/Build/ e cria um arquivo Cartfile.resolved com fixação de versões exatas. O Carthage suporta cache de frameworks compilados — a recompilação sem alterações nas dependências é ignorada.

Dependências transitivas no Carthage são tratadas através do Cartfile.resolved: o Carthage constrói um grafo de todas as dependências necessárias e as compila na ordem correta. Se duas bibliotecas dependem da mesma biblioteca de terceiros, o Carthage a compila uma vez e a usa para ambas. O Carthage relata erros de compilação indicando o alvo específico e a causa — isso simplifica o diagnóstico de problemas.

Cartfile: estrutura, sintaxe e exemplos

Cartfile é um arquivo de configuração com sintaxe semelhante a Ruby (formato Cartfile) que define as dependências de um projeto Carthage. O Cartfile está localizado na raiz do projeto ao lado do .xcodeproj. Cada linha do Cartfile descreve uma dependência: a fonte (URL Git, repositório GitHub) e a versão. A sintaxe suporta fixação de versões através de tags, commits e ramos.

# Dependências básicas do Carthage
github "Alamofire/Alamofire" ~> 5.9
github "SnapKit/SnapKit" ~> 5.7
github "onevcat/Kingfisher" == 8.0.0

A diretiva github "Owner/Repo" é uma forma abreviada para repositórios GitHub. O Carthage constrói automaticamente a URL https://github.com/Owner/Repo.git. Para GitLab, Bitbucket e outros hosts Git, usa-se a URL completa: git "https://gitlab.com/owner/repo.git". Operadores de versão: ~> 5.9 (qualquer versão de 5.9 até 6.0, excluindo 6.0), == 8.0.0 (versão exata), >= 1.0 (versão mínima). Pode-se fixar um commit específico via github "owner/repo" "abc1234".

Exemplo completo de Cartfile

Carthage suporta múltiplos diretórios para diferentes configurações: Cartfile (principal), Cartfile.private (para dependências internas não publicadas) e Cartfile.resolved (gerado automaticamente). Dependências privadas são úteis para bibliotecas usadas apenas em compilações de desenvolvimento, como frameworks de teste.

# Cartfile — dependências principais
github "Alamofire/Alamofire" ~> 5.9
github "SwiftyJSON/SwiftyJSON" ~> 4.0
github "realm/realm-swift" ~> 10.0

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

# Ramo de desenvolvimento
github "marmelroy/PhoneNumberKit" "development"

github e git são dois tipos de fontes no Cartfile. O primeiro é exclusivamente para GitHub e gera automaticamente a URL. O segundo é para qualquer repositório Git público ou privado com URL completa. Uma versão pode ser especificada como tag (== 2.1.1), intervalo semântico (~> 5.9), nome de ramo ("development") ou hash de commit ("a1b2c3d"). Intervalos semânticos (~>) são recomendados para dependências que seguem SemVer — isso protege contra mudanças disruptivas durante atualizações.

Cartfile.resolved é gerado automaticamente após carthage update. Ele fixa as versões exatas de todas as dependências instaladas, incluindo as transitivas. Este arquivo deve ser mantido no Git — sem ele, o comando carthage bootstrap em outra máquina compilará as bibliotecas pelas mesmas regras, mas as versões podem diferir. carthage outdated mostra uma lista de dependências desatualizadas para as quais novas versões estão disponíveis.

Instalação e configuração do Carthage

Carthage é instalado via Homebrew — o gerenciador de pacotes padrão para macOS. Métodos alternativos: instalação a partir de um instalador .pkg compilado do GitHub ou compilação a partir do código fonte. O Carthage requer Xcode com Command Line Tools (incluindo xcodebuild), e no Mac com Apple Silicon — Rosetta 2 para algumas dependências legadas.

# Instalação do Carthage via Homebrew
brew install carthage

# Verificação de versão
carthage version

# Instalação a partir do .pkg (se o Homebrew estiver indisponível)
# Baixar Carthage.pkg do GitHub Releases e instalar manualmente

Após instalar o Carthage, a inicialização do projeto começa com a criação de um Cartfile na raiz do projeto. O Carthage não tem comando init — o arquivo é criado manualmente em um editor de texto. Após preencher o Cartfile com dependências, o desenvolvedor executa carthage bootstrap (se o Cartfile.resolved já existir) ou carthage update (instalação inicial ou atualização). O Carthage clona os repositórios, compila os frameworks e os coloca em Carthage/Build/.

Atualizar o Carthage é feito via brew upgrade carthage. A versão é verificada com carthage version. A versão estável mais recente em meados de 2025 é a 0.40 com suporte padrão a .xcframework, compilação paralela melhorada e suporte completo ao Swift 6. A partir da versão 0.39, o Carthage parou de compilar .framework legados sem um shim de compatibilidade — recomenda-se especificar explicitamente --use-xcframeworks.

# Atualização do Carthage via Homebrew
brew upgrade carthage

# Instalar uma versão específica
brew install carthage@0.39

# Reinstalação completa
brew uninstall carthage && brew install carthage

Nota: o Carthage não cria .xcworkspace e não modifica .xcodeproj. Ao contrário do CocoaPods, o Carthage deixa o controle total da configuração do Xcode para o desenvolvedor. Isso significa que após instalar as dependências, você precisa adicionar manualmente os frameworks ao Xcode (veja a seção «Integração de frameworks Carthage no Xcode»). O Carthage também requer que cada dependência contenha um projeto Xcode ou workspace com um alvo de framework — caso contrário, a compilação falhará.

Compilação de frameworks: bootstrap e update

Carthage oferece três comandos principais para trabalhar com dependências: bootstrap, update e build. carthage bootstrap compila dependências a partir de um Cartfile.resolved existente — recomendado para ambientes CI e desenvolvedores que se juntam ao projeto. carthage update atualiza o Cartfile.resolved para as últimas versões (respeitando as restrições do Cartfile) e realiza a compilação. carthage build compila todas as dependências especificadas sem salvar versões.

# Instalação inicial (atualiza versões)
carthage update --use-xcframeworks --platform iOS

# Recompilação com versões fixadas
carthage bootstrap --use-xcframeworks --platform iOS

# Compilar apenas uma dependência
carthage build Alamofire --platform iOS

A flag --use-xcframeworks instrui o Carthage a compilar .xcframework universais em vez dos .framework legados. Isso garante suporte tanto para o simulador quanto para um dispositivo real, além de Mac com Apple Silicon sem scripts adicionais. A flag --platform iOS limita a compilação a uma única plataforma iOS — isso acelera significativamente o processo, especialmente se o projeto incluir bibliotecas multiplataforma.

Carthage suporta compilação paralela através da flag --cache-builds, que armazena em cache os frameworks já compilados. Ao recompilar, o Carthage verifica o hash do commit Git e, se o código não mudou, pula a compilação. Para servidores CI, recomenda-se armazenar em cache o diretório Carthage/Build/ e ~/Library/Caches/carthage/. O Carthage também suporta --verbose para registro detalhado e --no-use-binaries para compilação forçada a partir do código fonte (se o desenvolvedor não confiar em binários pré-compilados).

Integração de frameworks Carthage no Xcode

Integração de frameworks Carthage no Xcode é feita manualmente em quatro etapas. Após executar carthage update ou bootstrap, todos os frameworks compilados estão em Carthage/Build/iOS/ (ou na plataforma correspondente). O desenvolvedor abre o projeto Xcode, seleciona o alvo do aplicativo e adiciona os frameworks em General → Frameworks, Libraries, and Embedded Content. Para frameworks em tempo de execução (bibliotecas dinâmicas), é necessário selecionar «Embed & Sign» — caso contrário, o aplicativo falhará ao iniciar com o erro «dyld: Library not loaded».

Carthage para bibliotecas estáticas é mais simples — elas não requerem fase de embed, pois são vinculadas diretamente no arquivo executável do aplicativo. No entanto, o Carthage compila frameworks dinâmicos por padrão (exceto para bibliotecas estáticas explicitamente configuradas). Para projetos onde minimizar o tamanho do aplicativo é importante, recomenda-se a vinculação estática através das configurações do Xcode.

Uma etapa adicional é adicionar Input Files em Build Phase → Run Script. O Carthage requer um script para remover artefatos do simulador do framework compilado (strip simulator architectures). Este script é necessário para compilações da App Store:

# Run Script 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 não requer o uso de .xcworkspace — todas as dependências já estão compiladas em frameworks binários. O Carthage funciona diretamente com .xcodeproj, ao contrário do CocoaPods, que cria um workspace. Isso simplifica o controle de versão e a configuração de CI, porque as dependências do Carthage não alteram a configuração do projeto Xcode. A única alteração é adicionar frameworks ao alvo, que é registrada no .pbxproj.

Carthage vs CocoaPods vs Swift Package Manager

Carthage, CocoaPods e Swift Package Manager (SPM) são os três principais gerenciadores de dependências no desenvolvimento iOS. O Carthage se destaca pela sua abordagem descentralizada, o CocoaPods oferece um registro centralizado e o SPM é a solução integrada da Apple. A escolha entre eles depende dos requisitos do projeto, tamanho da equipe e nível de automação desejado.

Carthage é escolhido para projetos que exigem interferência mínima na configuração do Xcode e controle total sobre o processo de integração. O Carthage é ideal para bibliotecas e frameworks de código aberto onde o autor quer permitir que os usuários compilem dependências independentemente. O Carthage também é popular entre desenvolvedores que valorizam a filosofia UNIX: cada ferramenta faz bem uma coisa. O CocoaPods continua sendo o padrão para projetos empresariais com dezenas de dependências onde a automação é importante. O SPM é a escolha para novos projetos, pois é integrado ao Xcode e ativamente desenvolvido pela Apple.

Migração entre gerenciadores requer diferentes abordagens. Carthage → SPM: remover frameworks do Xcode, excluir o Cartfile e adicionar Package Dependencies via File → Add Package Dependencies. Carthage → CocoaPods: remover frameworks do Carthage, criar um Podfile, adicionar dependências e executar pod init && pod install. Ao migrar do Carthage para CocoaPods ou SPM, a necessidade de atualizar manualmente os frameworks desaparece — todas as dependências são atualizadas com um único comando. O Carthage continua relevante para projetos onde é importante evitar vendor lock-in e manter a transparência da compilação de dependências.

Problemas comuns e suas soluções

Carthage é uma ferramenta estável, mas os desenvolvedores encontram periodicamente problemas típicos, especialmente ao compilar em servidores CI, atualizar o Xcode ou mudar versões do Swift. A maioria dos problemas é resolvida limpando o cache, configurando corretamente --use-xcframeworks e verificando a versão mínima do iOS.

Erro «The file manager returned an error» — ocorre quando o cache do Carthage está corrompido ou há conflito de permissões de arquivo. Solução: excluir o cache com rm -rf ~/Library/Caches/carthage e reiniciar carthage bootstrap. Também ajuda excluir o diretório Carthage/ no projeto e recompilar. Em servidores CI, o cache do Carthage deve ser atualizado apenas quando o Cartfile.resolved mudar.

Erro «No such module» — o framework não é encontrado no Xcode embora a compilação do Carthage tenha sido bem-sucedida. Solução: verificar o caminho do framework em General → Frameworks, Libraries, and Embedded Content. O framework deve estar em Carthage/Build/iOS/. Certifique-se de que .xcframework foi adicionado corretamente (arraste novamente). Para frameworks dinâmicos, verifique Embed & Sign. Se o erro persistir, adicione FRAMEWORK_SEARCH_PATHS em Build Settings.

Erro de compilação devido a incompatibilidade de Swift — a biblioteca foi compilada para uma versão diferente do Swift do que o projeto. Solução: use carthage update --no-use-binaries para forçar a compilação a partir do código fonte com a mesma versão do Swift. Se a biblioteca não compilar sob a versão atual, use .xcconfig para especificar a versão do Swift ou faça um fork da biblioteca. Desde o Carthage 0.39, --use-xcframeworks inclui automaticamente a versão correta do Swift no binário.

Problemas com compilação em CI — o Carthage em CI requer configuração adequada de cache. Solução: armazenar em cache Carthage/Build/ e ~/Library/Caches/carthage/. Use carthage bootstrap --use-xcframeworks --platform iOS em vez de update em CI para evitar mudar versões. Uma ação oficial do Carthage está disponível para GitHub Actions. Para Jenkins — o plugin CarthageBuild. O Carthage pode falhar em macOS sem GUI — solução: instalar brew install xcode-build-server ou adicionar a flag -UseModernBuildSystem=NO.