Gym (Fastlane): o que é, compilação de IPA e automação no desenvolvimento de aplicações

O que é Gym (Fastlane)?

Gym (Fastlane) é um componente do ecossistema Fastlane que compila aplicações iOS no formato IPA com um único comando de terminal. Ele abstrai o processo complexo de invocar o xcodebuild com dezenas de flags e fornece ao desenvolvedor uma interface simples com valores padrão sensatos.

No Xcode, para compilar um IPA é necessário abrir o projeto, selecionar um esquema, configurar Archive e Export, especificar o método de distribuição e aguardar a conclusão. A automação de compilação através do Gym elimina as etapas manuais e garante que cada compilação seja executada com parâmetros idênticos — algo fundamental para a previsibilidade dos pipelines CI/CD.

De acordo com SwiftLee (2024), as equipas que usam o Gym para compilar gastam 40% menos tempo a configurar o processo de lançamento em comparação com a exportação manual através do Xcode Organizer. O Gym também gera registos detalhados de compilação com cada etapa do xcodebuild, simplificando a depuração de compilações falhadas e a análise de erros de compilação.

Utilize o Gym em qualquer projeto iOS que exija compilações regulares de IPA para testes ou publicação — é a única forma de garantir uma configuração de compilação idêntica em todas as máquinas da equipa.

Como o Gym compila IPA: processo e parâmetros

Processo de compilação de IPA através do Gym

A compilação de IPA através do Gym consiste em três etapas sequenciais: arquivamento do projeto via xcodebuild, exportação do arquivo para um pacote binário e empacotamento no formato IPA com assinatura. O Gym deteta automaticamente o tipo de projeto (target único ou workspace) e seleciona o método de compilação correto.

Na etapa de arquivamento, o Gym executa xcodebuild archive com os parâmetros de esquema e configuração especificados no projeto. Após a criação bem-sucedida do arquivo .xcarchive, o Gym executa xcodebuild -exportArchive com o método de exportação selecionado. A exportação de IPA é o processo de conversão do .xcarchive num ficheiro .ipa instalável incluindo todos os recursos e assinaturas necessários.

Parâmetros de exportação de compilação

O método de exportação determina o tipo de Provisioning Profile que será utilizado para a assinatura do IPA. O Gym suporta quatro métodos: development para depuração em dispositivos de programadores, app-store para publicação na App Store, ad-hoc para testes beta num número limitado de dispositivos e enterprise para distribuição corporativa.

Os parâmetros adicionais incluem a especificação de export_options_plist para uma configuração de exportação precisa, a supressão do Swift overlay para reduzir o tamanho do IPA e a gestão de bitcode. O Gym também suporta compilações para simulador através da flag --skip_package_ipa, útil para uma verificação rápida do código sem exportação completa.

# Compilação básica de IPA via Gym
fastlane gym --workspace "MyApp.xcworkspace" --scheme "MyApp"

# Compilação especificando o método de exportação
fastlane gym --export_method app-store

# Compilação apenas do arquivo sem exportação de IPA
fastlane gym --skip_package_ipa

Configuração do Gym através do Gymfile

Gymfile é um ficheiro de configuração do Fastlane que armazena todos os parâmetros de compilação num formato Ruby estruturado. Ao contrário de passar flags através da linha de comando, o Gymfile permite fixar a configuração no repositório e garantir que todos os programadores e CI utilizem configurações de compilação idênticas.

# Gymfile — configuração de compilação
workspace("MyApp.xcworkspace")
scheme("MyApp")
export_method(:app-store)
configuration("Release")
output_directory("./build")
output_name("MyApp.ipa")
include_symbols(true)
include_bitcode(false)

O parâmetro export_method no Gymfile corresponde aos tipos de perfil do Apple Developer Portal. Para lançamentos na App Store usa-se :app-store, para testes :development ou :ad-hoc. O parâmetro configuration define a configuração de compilação: Release para versões de lançamento ou Debug para versões de depuração.

O parâmetro include_bitcode controla a inclusão de bitcode no IPA. A Apple exigia bitcode para aplicações watchOS e tvOS, mas para iOS este parâmetro pode ser desativado para reduzir o tamanho do binário. include_symbols inclui os ficheiros de depuração de símbolos .dSYM, necessários para a simbolização de registos de falhas do App Store Connect ou de serviços de monitorização de terceiros.

Os parâmetros adicionais do Gymfile incluem export_options_plist para um ficheiro plist de exportação personalizado, silent para suprimir a saída excessiva nos registos e build_path para especificar um diretório temporário de compilação. Estes parâmetros são úteis ao integrar o Gym em pipelines CI/CD complexos com requisitos específicos de artefactos.

Comandos do Gym para compilar aplicações

A interface de comandos do Gym inclui parâmetros básicos para cenários típicos de compilação e flags estendidas para ajuste preciso do comportamento. A maioria dos parâmetros pode ser passada tanto através da linha de comando como do Gymfile, tendo os argumentos da linha de comando prioridade sobre o ficheiro de configuração.

O comando fastlane gym sem parâmetros usa as configurações do Gymfile ou deteta automaticamente o projeto no diretório atual. Para projetos com vários targets, é necessário especificar --scheme e --workspace para selecionar corretamente a configuração de compilação do target.

Comandos típicos de compilação

Para uma compilação de depuração rápida usa-se fastlane gym --export_method development — compila um IPA com perfil Development para instalação em dispositivos de programadores. A compilação de IPA para a App Store requer a flag --export_method app-store e um certificado Distribution, que deve ser pré-configurado no Match ou Keychain.

# Compilação para App Store com nome personalizado
fastlane gym --export_method app-store --output_name "Release_1.0.ipa"

# Compilação com limpeza antes do arquivamento
fastlane gym --clean --configuration Debug

# Compilação para simulador sem IPA
fastlane gym --skip_package_ipa --destination "generic/platform=iOS Simulator"

A flag --clean remove os ficheiros temporários da compilação anterior antes de começar, evitando a utilização de cache obsoleta e garantindo uma compilação limpa. A flag --destination permite especificar a plataforma de destino: iOS Simulator, iOS Device ou macOS Catalyst.

Integração do Gym no pipeline CI/CD

A integração do Gym com CI/CD é uma prática padrão para as equipas de desenvolvimento iOS que procuram entrega contínua. O Gym é executado em pipelines do GitHub Actions, GitLab CI, Bitrise ou Jenkins após a fase de testes e antes do envio para o TestFlight ou App Store.

Um pipeline típico de iOS CI/CD inclui: clonagem do repositório, instalação de dependências através do CocoaPods ou SPM, configuração de certificados através do Match, compilação de IPA através do Gym e carregamento através do Pilot ou Deliver. GitLab CI é um sistema de integração contínua do GitLab que executa compilações em cada push no repositório.

# Exemplo de etapa de build no GitLab CI
fastlane gym --scheme "MyApp" \
      --export_method app-store \
      --output_directory "$CI_PROJECT_DIR/build"
      
# Salvando o IPA como artefato do build
cp "build/MyApp.ipa" "$CI_PROJECT_DIR/artifacts/"

Para o Gym funcionar corretamente em CI, é necessário que o xcodebuild tenha acesso ao Keychain com os certificados. Isto é feito através do comando security unlock-keychain antes de executar o Gym. Se for usado o Match, os certificados são instalados automaticamente e não é necessária configuração adicional do Keychain — o Match cria um chaveiro temporário para a compilação.

Após uma compilação bem-sucedida de IPA, este pode ser passado para as etapas seguintes do pipeline: carregamento no TestFlight através do Pilot ou envio para o App Store Connect através do Deliver. Configure as variáveis de ambiente do sistema CI para armazenar as credenciais do Apple Developer, incluindo FASTLANE_APPLE_API_KEY e MATCH_PASSWORD, para que todas as etapas do pipeline funcionem sem entrada interativa.

Erros comuns de compilação no Gym

Ao usar o Gym, os programadores encontram frequentemente erros relacionados com configuração incorreta do xcodebuild, falta de certificados ou incompatibilidade de versões do Xcode. O diagnóstico de erros no Gym começa com a análise do registo completo de compilação, que é exibido na consola após a conclusão de cada comando.

O erro "error: No matching provisioning profiles found" indica que não existe um Provisioning Profile adequado para o método de exportação selecionado. Solução: certifique-se de que o Match ou Keychain contém um perfil válido para o export_method especificado. O Provisioning Profile deve corresponder ao identificador da aplicação e ao tipo de certificado (Development ou Distribution) para uma assinatura IPA bem-sucedida.

O erro "error: Signing for requires a development team" ocorre quando o projeto não tem especificada uma equipa de desenvolvimento. Solução: adicione DEVELOPMENT_TEAM à configuração de compilação do projeto ou especifique team_id no Gymfile através do parâmetro export_team_id. Isto é especialmente relevante para projetos que trabalham com várias contas Apple Developer.

Para o erro "error: Multiple commands produce...", ocorre um conflito de ficheiros de saída entre diferentes targets no workspace. Solução: defina caminhos de saída únicos para cada target nas Build Settings do projeto Xcode ou use o novo sistema de compilação, que está ativado por padrão no Xcode 14 e versões posteriores. O Gym suporta ambas as opções através da flag --use_legacy_build_system.