Nesta página, descrevemos como criar ou testar um projeto 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 fornece soluções de solução de problemas para resolver erros comuns.
Diferenças entre Xcode e Bazel
O Bazel exige que você especifique explicitamente cada destino de build e as dependências dele, além das configurações de build correspondentes usando regras de build.
O Bazel exige que todos os arquivos de que o projeto depende estejam presentes no diretório do espaço de trabalho ou sejam 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ê trabalhar no projeto no Xcode, será necessário gerar uma nova versão do projeto do Xcode que corresponda aos arquivosBUILD
usando rules_xcodeproj sempre que você atualizar os arquivosBUILD
. Algumas mudanças nos arquivosBUILD
, como a adição de dependências a um destino, não exigem a regeneração do projeto, o que pode acelerar o desenvolvimento. Se você não estiver usando o Xcode, os comandosbazel build
ebazel test
vão fornecer recursos de build e teste com algumas limitações descritas mais adiante neste guia.
Antes de começar
Antes de começar, faça o seguinte:
Instale o Bazel, caso ainda não tenha feito isso.
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
eBUILD
, além dos conceitos de destinos, regras de build e pacotes do Bazel.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:
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 usa dependências externas, esse arquivo pode 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 SwiftPM
Para integrar dependências do SwiftPM ao espaço de trabalho do Bazel com o swift_bazel, é necessário convertê-las em pacotes do Bazel, conforme descrito no tutorial a seguir.
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 do 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
: ID do pacote (caminho do DNS reverso 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: adicionar os destinos do teste (opcional)
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 rules_xcodeproj. Adicione destinos de teste da seguinte maneira:
macos_unit_test
para executar testes de unidade baseados em biblioteca e em app no 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 rules_xcodeproj 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 rules_xcodeproj e executar os testes no Xcode. O Bazel não executa testes de interface nativamente.
No mínimo, especifique um valor para o atributo minimum_os_version
. Embora
outros atributos de embalagem, como bundle_identifier
e infoplists
,
sejam 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 de 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
.
Você pode procurar exemplos de vários tipos de aplicativos diretamente no diretório de exemplos rules_apple. Exemplo:
Para mais informações sobre regras de build, consulte Regras da Apple para o Bazel.
Nesse 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. Esse aumento de granularidade oferece:
Maior incrementabilidade de builds,
Maior carregamento em paralelo de tarefas de compilação,
Melhor manutenção para usuários futuros,
Melhor controle sobre a visibilidade do código-fonte entre 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 atributosdeps
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 aglob()
diminuem.Ao adicionar um arquivo
BUILD
a um diretóriomain
, adicione também um arquivoBUILD
ao diretóriotest
correspondente.Aplique limites de visibilidade íntegros 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 rules_xcodeproj
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 rules_xcodeproj.
Solução de problemas
Erros do Bazel podem surgir quando ele fica fora de sincronia 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
.