Como migrar do Xcode para o Bazel

Esta página descreve como criar ou testar um projeto do Xcode com o Bazel. Ele descreve as diferenças entre o Xcode e o Bazel e fornece as etapas para converter um projeto do Xcode em um projeto do Bazel. Ele também oferece soluções de solução de problemas para resolver erros comuns.

Diferenças entre Xcode e Bazel

• O Bazel exige que você especifique explicitamente todos os destinos de build e as dependências, além das configurações de build correspondentes usando regras de build.

• O Bazel exige que todos os arquivos em que o projeto depende estejam presentes no diretório do espaço de trabalho ou especificados como importações no arquivo WORKSPACE.

• Ao criar projetos do Xcode com o Bazel, os arquivos BUILD se tornam a fonte de verdade. Se você trabalha no projeto no Xcode, é necessário gerar uma nova versão do projeto do Xcode que corresponda aos arquivos BUILD usando o Tulsi sempre que você atualizar os arquivos BUILD. Se você não estiver usando o Xcode, os comandos bazel build e bazel test oferecem recursos de build e teste com algumas limitações descritas mais adiante neste guia.

• Devido a diferenças nos esquemas de configuração do build, como layouts de diretório ou flags de build, o Xcode pode não estar totalmente ciente do "quadro geral" do build. Por isso, alguns recursos do Xcode podem não funcionar. Mais especificamente:

  • Dependendo das metas selecionadas para conversão no Tulsi, o Xcode pode não conseguir indexar corretamente a origem do projeto. Isso afeta a conclusão e a navegação do código no Xcode, já que o Xcode não vai conseguir acessar todo o código-fonte do projeto.

  • A análise estática, os limpadores de endereços e os limpadores de linhas de execução podem não funcionar, já que o Bazel não produz as saídas que o Xcode espera para esses recursos.

  • Se você gerar um projeto do Xcode com o Tulsi e usar esse projeto para executar testes no Xcode, o Xcode vai executar os testes em vez do Bazel. Para executar testes com o Bazel, execute o comando bazel test manualmente.

Antes de começar

Antes de começar, faça o seguinte:

1. Instale o Bazel, caso ainda não tenha feito isso.

2. Se você não conhece o Bazel e os conceitos dele, conclua o tutorial do app iOS. Você precisa entender o espaço de trabalho do Bazel, incluindo os arquivos WORKSPACE e BUILD, além dos conceitos de destinos, regras de build e pacotes do Bazel.

3. Analise e entenda as dependências do projeto.

Analisar as dependências do projeto

Ao contrário do Xcode, o Bazel exige que você declare explicitamente todas as dependências de cada destino no arquivo BUILD.

Para mais informações sobre dependências externas, consulte Como trabalhar com dependências externas.

Criar ou testar um projeto do Xcode com o Bazel

Para criar ou testar um projeto do Xcode com o Bazel, faça o seguinte:

1. Criar o arquivo WORKSPACE

2. (Experimental) Integrar dependências do CocoaPods

3. Crie um arquivo BUILD:

   a. Adicionar o destino do aplicativo

   b. (Opcional) Adicionar os destinos de teste

   c. Adicionar os alvos da biblioteca

4. (Opcional) Granular o build

5. Executar o build

6. Gerar o projeto do Xcode com o Tulsi

Etapa 1: criar o arquivo WORKSPACE

Crie um arquivo WORKSPACE em um novo diretório. Esse diretório se torna a raiz do espaço de trabalho do Bazel. Se o projeto não usar dependências externas, esse arquivo poderá estar vazio. Se o projeto depender de arquivos ou pacotes que não estão em um dos diretórios do projeto, especifique essas dependências externas no arquivo WORKSPACE.

Etapa 2: (experimental) integrar dependências do CocoaPods

Para integrar as dependências do CocoaPods ao espaço de trabalho do Bazel, é necessário convertê-las em pacotes do Bazel, conforme descrito em Como converter dependências do CocoaPods.

Etapa 3: criar um arquivo BUILD

Depois de definir o espaço de trabalho e as dependências externas, você precisa criar um arquivo BUILD que informe ao Bazel como o projeto está estruturado. Crie o arquivo BUILD na raiz do espaço de trabalho do Bazel e configure-o para fazer um build inicial do projeto da seguinte maneira:

• Etapa 3a: adicionar o destino do aplicativo
• Etapa 3b: adicionar os destinos de teste (opcional)
• Etapa 3c: adicionar os destinos da biblioteca

Dica:para saber mais sobre pacotes e outros conceitos do Bazel, consulte Espaços de trabalho, pacotes e destinos.

Etapa 3a: adicionar o destino do aplicativo

Adicione uma segmentação por macos_application ou uma regra de segmentação ios_application. Esse destino cria um pacote de aplicativo macOS ou iOS, respectivamente. Na meta, especifique o seguinte, no mínimo:

• bundle_id: o ID do pacote (caminho reverso do DNS seguido pelo nome do app) do binário.

• provisioning_profile: perfil de provisionamento da sua conta de desenvolvedor da Apple (se estiver criando para um dispositivo iOS).

• families (somente iOS): se o aplicativo será criado para iPhone, iPad ou ambos.

• infoplists: lista de arquivos .plist a serem mesclados no arquivo Info.plist final.

• minimum_os_version: a versão mínima do macOS ou iOS com suporte do aplicativo. Isso garante que o Bazel crie o aplicativo com os níveis de API corretos.

Etapa 3b: (opcional) adicionar os destinos de teste

As regras de build da Apple do Bazel oferecem suporte à execução de testes de unidade baseados em biblioteca no iOS e no macOS, bem como testes baseados em aplicativos no macOS. Para testes baseados em aplicativos no iOS ou testes de interface em qualquer plataforma, o Bazel vai criar as saídas de teste, mas os testes precisam ser executados no Xcode por um projeto gerado com o Tulsi. Adicione segmentos de teste da seguinte maneira:

• macos_unit_test para executar testes de unidade baseados em biblioteca e em aplicativo em um macOS.

• ios_unit_test para executar testes de unidade baseados em biblioteca no iOS. Para testes que exigem o simulador do iOS, o Bazel vai criar as saídas de teste, mas não vai executar os testes. É necessário gerar um projeto do Xcode com o Tulsi e executar os testes no Xcode.

• ios_ui_test para criar saídas necessárias para executar testes de interface do usuário no simulador do iOS usando o Xcode. É necessário gerar um projeto do Xcode com o Tulsi e executar os testes no Xcode. O Bazel não pode executar testes de IU de forma nativa.

No mínimo, especifique um valor para o atributo minimum_os_version. Enquanto outros atributos de embalagem, como bundle_identifier e infoplists, são padrão para os valores mais usados, verifique se esses padrões são compatíveis com o projeto e ajuste-os conforme necessário. Para testes que exigem o simulador do iOS, especifique também o nome de destino ios_application como o valor do atributo test_host.

Etapa 3c: adicionar os alvos da biblioteca

Adicione um destino objc_library para cada biblioteca Objective C e um destino swift_library para cada biblioteca Swift em que o aplicativo e/ou os testes dependem.

Adicione os destinos da biblioteca da seguinte maneira:

• Adicione os destinos da biblioteca do aplicativo como dependências aos destinos do aplicativo.

• Adicione os destinos da biblioteca de teste como dependências aos destinos de teste.

• Liste as fontes de implementação no atributo srcs.

• Liste os cabeçalhos no atributo hdrs.

Para mais informações sobre as regras de build, consulte Regras da Apple para o Bazel.

Neste ponto, é recomendável testar o build:

bazel build //:<application_target>

Etapa 4: (opcional) granularizar o build

Se o projeto for grande ou crescer, considere dividi-lo em vários pacotes do Bazel. Essa granularidade maior oferece:

• Aumento da incrementalidade dos builds,

• Aumento da paralelização de tarefas de build.

• Melhor manutenção para usuários futuros,

• Controle melhor da visibilidade do código-fonte em destinos e pacotes. Isso evita problemas como bibliotecas que contêm detalhes de implementação que vazam para APIs públicas.

Dicas para detalhar o projeto:

• Coloque cada biblioteca no próprio pacote do Bazel. Comece com aqueles que exigem o menor número de dependências e avance pela árvore de dependências.

• Ao adicionar arquivos BUILD e especificar destinos, adicione esses novos destinos aos atributos deps dos destinos que dependem deles.

• A função glob() não cruza os limites do pacote. Portanto, à medida que o número de pacotes aumenta, os arquivos correspondentes a glob() diminuem.

• Ao adicionar um arquivo BUILD a um diretório main, adicione também um arquivo BUILD ao diretório test correspondente.

• Aplique limites de visibilidade saudáveis nos pacotes.

• Crie o projeto após cada mudança importante nos arquivos BUILD e corrija os erros de build conforme eles aparecem.

Etapa 5: executar o build

Execute o build totalmente migrado para garantir que ele seja concluído sem erros ou avisos. Execute cada aplicativo e destino de teste individualmente para encontrar com mais facilidade as origens de erros que ocorrem.

Exemplo:

bazel build //:my-target

Etapa 6: gerar o projeto Xcode com o Tulsi

Ao criar com o Bazel, os arquivos WORKSPACE e BUILD se tornam a fonte de informações sobre o build. Para que o Xcode saiba disso, é necessário gerar um projeto Xcode compatível com o Bazel usando o Tulsi.

Solução de problemas

Erros do Bazel podem surgir quando ele fica fora de sincronização com a versão do Xcode selecionada, como quando você aplica uma atualização. Confira algumas soluções se você estiver enfrentando erros com o Xcode, por exemplo, "A versão do Xcode precisa ser especificada para usar um CROSSTOOL da Apple".

• Execute o Xcode manualmente e aceite os Termos e Condições.

• Use o Xcode Select para indicar a versão correta, aceitar a licença e limpar o estado do Bazel.

  sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
  sudo xcodebuild -license
  bazel sync --configure

• Se isso não funcionar, tente executar bazel clean --expunge.