Carthage
0.40.0
Carthage pretende ser a maneira mais simples de adicionar estruturas ao seu aplicativo Cocoa.
Carthage cria suas dependências e fornece estruturas binárias, mas você mantém controle total sobre a estrutura e configuração do seu projeto. Carthage não modifica automaticamente seus arquivos de projeto ou configurações de construção.
Obtenha Carthage executando brew install carthage ou escolha outro método de instalação
Crie um Cartfile no mesmo diretório onde está seu .xcodeproj ou .xcworkspace
Liste as dependências desejadas no Cartfile, por exemplo:
github "Alamofire/Alamofire" ~> 5.5
Execute carthage update --use-xcframeworks
Um arquivo Cartfile.resolved e um diretório Carthage aparecerão no mesmo diretório onde seu .xcodeproj ou .xcworkspace está
Arraste os pacotes .xcframework construídos de Carthage/Build para a seção "Frameworks and Libraries" do projeto Xcode do seu aplicativo.
Se você estiver usando Cartago para um aplicativo, selecione "Incorporar e assinar", caso contrário, "Não incorporar".
Para obter um guia detalhado, continue lendo Adicionando estruturas a um aplicativo
Existem várias opções para instalar o Cartago:
Instalador: Baixe e execute o arquivo Carthage.pkg para a versão mais recente e siga as instruções na tela. Se você estiver instalando o pacote via CLI, talvez seja necessário executar sudo chown -R $(whoami) /usr/local primeiro.
Homebrew: Você pode usar o Homebrew e instalar a ferramenta carthage em seu sistema simplesmente executando brew update e brew install carthage . (nota: se você instalou anteriormente a versão binária do Carthage, você deve excluir /Library/Frameworks/CarthageKit.framework ).
MacPorts: Você pode usar MacPorts e instalar a ferramenta carthage em seu sistema simplesmente executando sudo port selfupdate e sudo port install carthage . (nota: se você instalou anteriormente a versão binária do Carthage, você deve excluir /Library/Frameworks/CarthageKit.framework ).
Da fonte: Se você quiser executar a versão de desenvolvimento mais recente (que pode ser altamente instável ou incompatível), simplesmente clone o branch master do repositório e execute make install . Requer Xcode 10.0 (Swift 4.2).
Depois de instalar o Carthage, você pode começar a adicionar estruturas ao seu projeto. Observe que Carthage oferece suporte apenas a estruturas dinâmicas, que estão disponíveis apenas no iOS 8 ou posterior (ou em qualquer versão do OS X).
carthage update --use-xcframeworks . Isso irá buscar dependências em uma pasta Carthage/Checkouts e construir cada uma delas ou baixar um XCFramework pré-compilado.Incentivamos o uso do XCFrameworks a partir da versão 0.37.0 (janeiro de 2021) e exigimos o XCFrameworks ao construir em um Apple Silicon Mac. Mudar de pacotes de estrutura discretos para XCFrameworks requer algumas alterações em seu projeto:
Carthage/Build para remover quaisquer pacotes de estrutura existentes.carthage build --use-xcframeworks . Quaisquer outros argumentos com os quais você construir podem ser fornecidos normalmente.carthage copy-frameworks do destino, se presente.Incompatibilidade do Xcode 12+ : plataformas multiarquitetura não são suportadas ao construir pacotes de estrutura no Xcode 12 e superior. Prefira construir com XCFrameworks. Se você precisar criar pacotes configuráveis de estrutura discretos, use um arquivo xcconfig de solução alternativa.
carthage update --platform macOS . Isso irá buscar dependências em uma pasta Carthage/Checkouts e construir cada uma delas ou baixar uma estrutura pré-compilada.Além disso, você precisará copiar símbolos de depuração para depuração e relatórios de falhas no OS X.
Crie um Cartfile que liste as estruturas que você gostaria de usar em seu projeto.
Execute carthage update . Isso irá buscar dependências em uma pasta Carthage/Checkouts e, em seguida, construir cada uma delas ou baixar uma estrutura pré-compilada.
Abra a guia Configurações gerais dos destinos do seu aplicativo. Para o Xcode 11.0 e superior, na seção "Frameworks, Libraries, and Embedded Content", arraste e solte cada estrutura que deseja usar da pasta Carthage/Build no disco. Em seguida, na seção “Incorporar”, selecione “Não incorporar” no menu suspenso para cada item adicionado. Para Xcode 10.xe inferior, na seção "Linked Frameworks and Libraries", arraste e solte cada estrutura que deseja usar da pasta Carthage/Build no disco.
Na guia de configurações Build Phases dos destinos do seu aplicativo, clique no ícone + e escolha New Run Script Phase . Crie um Run Script no qual você especifica seu shell (ex: /bin/sh ), adicione o seguinte conteúdo à área de script abaixo do shell:
/usr/local/bin/carthage copy-frameworks Crie um arquivo chamado input.xcfilelist e um arquivo chamado output.xcfilelist
Adicione os caminhos para as estruturas que deseja usar em seu input.xcfilelist . Por exemplo:
$(SRCROOT)/Carthage/Build/iOS/Result.framework
$(SRCROOT)/Carthage/Build/iOS/ReactiveSwift.framework
$(SRCROOT)/Carthage/Build/iOS/ReactiveCocoa.framework
Adicione os caminhos das estruturas copiadas ao output.xcfilelist . Por exemplo:
$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/Result.framework
$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/ReactiveSwift.framework
$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/ReactiveCocoa.framework
Com os arquivos de saída especificados junto com os arquivos de entrada, o Xcode só precisa executar o script quando os arquivos de entrada forem alterados ou os arquivos de saída estiverem ausentes. Isso significa que compilações sujas serão mais rápidas quando você não reconstruir estruturas com Carthage.
Adicione input.xcfilelist à seção "Listas de arquivos de entrada" da fase de script de execução do Carthage
Adicione o output.xcfilelist à seção "Listas de arquivos de saída" da fase de script de execução do Carthage
Este script contorna um bug de envio da App Store acionado por binários universais e garante que os arquivos e dSYMs relacionados a bitcode necessários sejam copiados durante o arquivamento.
Com as informações de depuração copiadas para o diretório de produtos construídos, o Xcode poderá simbolizar o rastreamento de pilha sempre que você parar em um ponto de interrupção. Isso também permitirá que você percorra o código de terceiros no depurador.
Ao arquivar seu aplicativo para envio à App Store ou TestFlight, o Xcode também copiará esses arquivos no subdiretório dSYMs do pacote .xcarchive do seu aplicativo.
Ao longo do caminho, Cartago terá criado alguns artefatos de construção. O mais importante deles é o arquivo Cartfile.resolved, que lista as versões que foram realmente construídas para cada framework. Certifique-se de enviar seu Cartfile.resolved , porque qualquer outra pessoa que estiver usando o projeto precisará desse arquivo para construir as mesmas versões do framework.
Você pode adicionar uma fase Executar Script para avisar automaticamente quando uma de suas dependências estiver desatualizada.
Build Phases dos destinos do seu aplicativo, clique no ícone + e escolha New Run Script Phase . Crie um Run Script no qual você especifica seu shell (ex: /bin/sh ), adicione o seguinte conteúdo à área de script abaixo do shell: /usr/local/bin/carthage outdated --xcode-warnings 2> /dev/nullCarthage verificará se as estruturas Swift baixadas (e as estruturas Objective-C/Swift mistas) foram construídas com a mesma versão do Swift que está em uso localmente. Se houver uma incompatibilidade de versão, Carthage continuará a construir a estrutura a partir do código-fonte. Se a estrutura não puder ser construída a partir do código-fonte, Carthage irá falhar.
Como Carthage usa a saída de xcrun swift --version para determinar a versão local do Swift, certifique-se de executar os comandos do Carthage com o conjunto de ferramentas Swift que você pretende usar. Para muitos casos de uso, nada adicional é necessário. No entanto, por exemplo, se você estiver construindo um projeto Swift 2.3 usando o Xcode 8.x, uma abordagem para especificar seu swift padrão para carthage bootstrap é usar o seguinte comando:
TOOLCHAINS=com.apple.dt.toolchain.Swift_2_3 carthage bootstrap
Depois de concluir as etapas acima e enviar as alterações, outros usuários do projeto só precisam buscar o repositório e executar carthage bootstrap para começar a usar as estruturas que você adicionou.
Usar Carthage para as dependências de qualquer destino arbitrário é bastante semelhante a usar Carthage para um aplicativo. A principal diferença está em como as estruturas são realmente configuradas e vinculadas no Xcode.
Como os destinos de teste de unidade não têm a seção Linked Frameworks and Libraries na guia General settings, você deve arrastar as estruturas construídas para a fase de compilação Link Binaries With Libraries .
No destino de teste na guia Build Settings , adicione @loader_path/Frameworks aos Runpath Search Paths se ainda não estiver presente.
Em casos raros, você também pode querer copiar cada dependência no produto de construção (por exemplo, para incorporar dependências na estrutura externa ou certificar-se de que as dependências estejam presentes em um pacote de teste). Para fazer isso, crie uma nova fase de construção Copiar Arquivos com o destino Frameworks e, em seguida, adicione a referência da estrutura lá também. Você não deve usar o comando carthage copy-frameworks pois os pacotes de teste não precisam de estruturas removidas e a execução simultânea de instâncias de copy-frameworks (com compilações paralelas ativadas) não é suportada.
Se você modificou seu Cartfile ou deseja atualizar para as versões mais recentes de cada estrutura (sujeito aos requisitos especificados), basta executar o comando carthage update novamente.
Se você deseja atualizar apenas uma ou dependências específicas, passe-as como uma lista separada por espaços para o comando update . por exemplo
carthage update Box
ou
carthage update Box Result
Foi feita uma reescrita da lógica de atualização de frameworks com o objetivo de aumentar a velocidade e reduzir o uso de memória. Atualmente é um recurso opcional. Pode ser usado passando --new-resolver para o comando de atualização, por exemplo,
carthage update --new-resolver Box
Se você estiver enfrentando problemas de desempenho durante as atualizações, experimente o novo resolvedor
Se a estrutura que você deseja adicionar ao seu projeto tiver dependências listadas explicitamente em um Cartfile, o Carthage irá recuperá-las automaticamente para você. Você terá então que arrastá-los para o seu projeto a partir da pasta Carthage/Build.
Se a estrutura incorporada em seu projeto tiver dependências de outras estruturas, você deverá vinculá-las ao destino do aplicativo (mesmo que o destino do aplicativo não tenha dependência dessas estruturas e nunca as utilize).
Por padrão, Carthage fará check-out direto dos arquivos de origem das dependências na pasta do seu projeto, deixando você confirmá-los ou ignorá-los conforme desejar. Se você quiser ter dependências disponíveis como submódulos do Git (talvez para poder confirmar e enviar alterações dentro deles), você pode executar carthage update ou carthage checkout com o sinalizador --use-submodules .
Quando executado dessa forma, Carthage gravará nos arquivos .gitmodules e .git/config do seu repositório e atualizará automaticamente os submódulos quando as versões das dependências mudarem.
Se você quiser trabalhar em suas dependências durante o desenvolvimento e quiser que elas sejam reconstruídas automaticamente quando você construir seu projeto pai, você pode adicionar uma fase de construção Run Script que invoca Carthage da seguinte forma:
/usr/local/bin/carthage build --platform " $PLATFORM_NAME " --project-directory " $SRCROOT "Observe que você deve usar submódulos antes de fazer isso, porque checkouts simples não devem ser modificados diretamente.
Por padrão, Carthage reconstruirá uma dependência independentemente de ser a mesma versão resolvida de antes. Passar --cache-builds fará com que cartago evite reconstruir uma dependência, se possível. Consulte informações sobre arquivos de versão para obter detalhes sobre como Carthage realiza esse armazenamento em cache.
Nota: No momento --cache-builds é incompatível com --use-submodules . Usar ambos resultará na cópia de trabalho e nas alterações confirmadas na dependência do submódulo que não serão reconstruídas corretamente. Consulte #1785 para obter detalhes.
O preenchimento automático dos comandos e opções do Carthage está disponível conforme documentado em Bash/Zsh/Fish Completion.
Cartago suporta oficialmente apenas estruturas dinâmicas . Estruturas dinâmicas podem ser usadas em qualquer versão do OS X, mas apenas no iOS 8 ou posterior . Além disso, desde a versão 0.30.0, o Carthage oferece suporte a estruturas estáticas .
Como Carthage não possui uma lista de pacotes centralizada e nenhum formato de especificação de projeto, a maioria das estruturas deve ser construída automaticamente .
Os requisitos específicos de qualquer projeto-quadro estão listados abaixo.
Carthage criará apenas esquemas Xcode compartilhados em seu .xcodeproj . Você pode ver se todos os esquemas pretendidos foram construídos com sucesso executando carthage build --no-skip-current e verificando a pasta Carthage/Build.
Se um esquema importante não for criado quando você executar esse comando, abra o Xcode e certifique-se de que o esquema esteja marcado como Shared , para que Carthage possa descobri-lo.
Se você encontrar falhas de compilação em carthage build --no-skip-current , tente executar xcodebuild -scheme SCHEME -workspace WORKSPACE build ou xcodebuild -scheme SCHEME -project PROJECT build (com os valores reais) e veja se a mesma falha ocorre lá. Esperamos que isso forneça informações suficientes para resolver o problema.
Se você tiver várias versões das ferramentas de desenvolvedor da Apple instaladas (uma versão beta do Xcode, por exemplo), use xcode-select para alterar a versão que Carthage usa.
Se você ainda não conseguiu construir sua estrutura com Cartago, abra um problema e ficaremos felizes em ajudar!
Carthage determina quais versões do seu framework estão disponíveis pesquisando nas tags publicadas no repositório e tentando interpretar cada nome de tag como uma versão semântica. Por exemplo, na tag v1.2 , a versão semântica é 1.2.0.
Tags sem qualquer número de versão ou com quaisquer caracteres após o número de versão (por exemplo, 1.2-alpha-1 ) não são suportadas no momento e serão ignoradas.
Carthage pode usar estruturas pré-construídas automaticamente, em vez de compilar do zero, se elas estiverem anexadas a uma versão do GitHub no repositório do seu projeto ou por meio de um arquivo binário de definição de projeto.
Para oferecer estruturas pré-construídas para uma tag específica, os binários para todas as plataformas suportadas devem ser compactados em um arquivo, e esse arquivo deve ser anexado a uma versão publicada correspondente a essa tag. O anexo deve incluir .framework em seu nome (por exemplo, ReactiveCocoa.framework.zip ), para indicar a Carthage que contém binários. A estrutura de diretórios do arquivo é de formato livre, mas os frameworks devem aparecer apenas uma vez no arquivo , pois serão copiados para Carthage/Build/<platform> com base em seu nome (por exemplo, ReactiveCocoa.framework ).
Para oferecer XCFrameworks pré-construídos, construa com --use-xcframeworks e siga o mesmo processo para compactar todos os XCFrameworks em um arquivo. Inclua .xcframework no nome do anexo. A partir da versão 0.38.0, Carthage prefere baixar anexos .xcframework quando --use-xcframeworks é passado.
Você pode realizar a operação de arquivamento com o próprio Cartago usando:
-carthage build --no-skip-current
-carthage archive YourFrameworkNameou alternativamente
carthage build --archiveOs Draft Releases serão automaticamente ignorados, mesmo que correspondam à tag desejada.
É possível usar o travis-ci para construir e fazer upload de seus lançamentos marcados.
Instale o travis CLI com gem install travis
Configure o travis-ci para o seu repositório (etapas 1 e 2)
Crie o arquivo .travis.yml na raiz do seu repositório com base nesse modelo. Defina FRAMEWORK_NAME com o valor correto.
Substitua PROJECT_PLACEHOLDER e SCHEME_PLACEHOLDER
Se você estiver usando um espaço de trabalho em vez de um projeto, remova a linha xcode_project e remova o comentário da linha xcode_workspace.
O projeto deve estar no formato: MyProject.xcodeproj
O espaço de trabalho deve estar no formato: MyWorkspace.xcworkspace
Sinta-se à vontade para atualizar o valor xcode_sdk para outro SDK. Observe que o teste no SDK iphoneos exigiria que você carregasse uma identidade de assinatura de código
Para mais informações você pode visitar travis docs para projetos objetivo-c
language : objective-c
osx_image : xcode7.3
xcode_project : <PROJECT_PLACEHOLDER>
# xcode_workspace: <WORKSPACE_PLACEHOLDER>
xcode_scheme : <SCHEME_PLACEHOLDER>
xcode_sdk : iphonesimulator9.3
env :
global :
- FRAMEWORK_NAME=<THIS_IS_A_PLACEHOLDER_REPLACE_ME>
before_install :
- brew update
- brew outdated carthage || brew upgrade carthage
before_script :
# bootstrap the dependencies for the project
# you can remove if you don't have dependencies
- carthage bootstrap
before_deploy :
- carthage build --no-skip-current
- carthage archive $FRAMEWORK_NAME Execute travis setup releases , siga a documentação aqui
Este comando irá codificar suas credenciais do GitHub no arquivo .travis.yml para permitir que o travis carregue a versão para GitHub.com. Quando solicitado o upload do arquivo, digite $FRAMEWORK_NAME.framework.zip
Atualize a seção de implantação para executar em tags:
Em .travis.yml localize:
on :
repo : repo/repo E adicione tags: true e skip_cleanup: true :
skip_cleanup : true
on :
repo : repo/repo
tags : trueIsso permitirá que o travis saiba que deve criar uma implantação quando uma nova tag for enviada e impedirá que o travis limpe o arquivo zip gerado
Se você incorporar muitas estruturas dinâmicas ao seu aplicativo, os tempos de inicialização pré-principal poderão ser bastante lentos. Carthage é capaz de ajudar a mitigar isso construindo suas estruturas dinâmicas como estruturas estáticas. Estruturas estáticas podem ser vinculadas diretamente ao seu aplicativo ou mescladas em uma estrutura dinâmica maior com algumas modificações simples em seu fluxo de trabalho, o que pode resultar em reduções drásticas nos tempos de pré-lançamento principal.
Desde a versão 0.30.0, o projeto Carthage implementa suporte para estruturas vinculadas estaticamente escritas em Swift ou Objective-C, cujo suporte foi introduzido no Xcode 9.4. Observe, entretanto, que ele diz especificamente frameworks , portanto, Darwin vem com a extensão .framework e arquivos de objetos vinculados estaticamente dentro dele. Carthage atualmente não oferece suporte a esquemas de bibliotecas estáticas, nem há planos para introduzir seu suporte no futuro.
O fluxo de trabalho difere pouco:
No entanto:
Consulte o documento StaticFrameworks para obter detalhes.
Observe que algumas advertências se aplicam a esta abordagem:
Quer anunciar que seu projeto pode ser utilizado com Cartago? Você pode adicionar um selo de compatibilidade:
… ao seu README , simplesmente inserindo o seguinte Markdown:
[ ![ Carthage compatible ] ( https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat )] ( https://github.com/Carthage/Carthage ) A estrutura pré-construída não pode ser depurada usando a execução de etapas em outra máquina diferente da qual a estrutura foi construída. Simplesmente carthage bootstrap/build/update --no-use-binaries deve corrigir isso, mas para uma solução alternativa mais automatizada, consulte #924. Dupe rdar://23551273 se quiser que a Apple corrija a causa raiz deste problema.
A maior parte da funcionalidade da ferramenta de linha de comando carthage está, na verdade, encapsulada em uma estrutura chamada CarthageKit.
Se você estiver interessado em usar o Carthage como parte de outra ferramenta, ou talvez estender a funcionalidade do Carthage, dê uma olhada no código-fonte do CarthageKit para ver se a API atende às suas necessidades.
CocoaPods é um gerenciador de dependências de longa data para Cocoa. Então, por que Cartago foi criada?
Em primeiro lugar, CocoaPods (por padrão) cria e atualiza automaticamente um espaço de trabalho Xcode para seu aplicativo e todas as dependências. Carthage constrói binários de framework usando xcodebuild , mas deixa a responsabilidade de integrá-los ao usuário. A abordagem do CocoaPods é mais fácil de usar, enquanto a do Carthage é flexível e pouco intrusiva.
O objetivo do CocoaPods está listado em seu README da seguinte forma:
…para melhorar a descoberta e o envolvimento em bibliotecas de código aberto de terceiros, criando um ecossistema mais centralizado.
Em contrapartida, Cartago foi criada como uma gestora de dependências descentralizada . Não existe uma lista central de projetos, o que reduz os trabalhos de manutenção e evita qualquer ponto central de falha. No entanto, a descoberta do projeto é mais difícil – os usuários devem recorrer às páginas de tendências do GitHub ou similares.
Os projetos CocoaPods também devem ter o que é conhecido como arquivo podspec, que inclui metadados sobre o projeto e especifica como ele deve ser construído. Carthage usa xcodebuild para construir dependências, em vez de integrá-las em um único espaço de trabalho, ele não possui um arquivo de especificação semelhante, mas suas dependências devem incluir seu próprio projeto Xcode que descreve como construir seus produtos.
Em última análise, criamos o Carthage porque queríamos a ferramenta mais simples possível – um gerenciador de dependências que realizasse o trabalho sem assumir a responsabilidade do Xcode e sem criar trabalho extra para os autores da estrutura. CocoaPods oferece muitos recursos incríveis que Carthage nunca terá, às custas de complexidade adicional.
Cartago é lançado sob a licença do MIT.
A foto do pano de fundo do cabeçalho foi lançada sob a licença CC BY-NC-SA 2.0. Foto original de Richard Mortel.
