Como migrar do Maven para o Bazel

Esta página descreve como migrar do Maven para o Bazel, incluindo os pré-requisitos e as etapas de instalação. Ela descreve as diferenças entre o Maven e o Bazel e fornece um exemplo de migração usando o projeto Guava.

Ao migrar de qualquer ferramenta de build para o Bazel, é recomendável que as duas ferramentas de build sejam executadas em paralelo até que você tenha migrado totalmente sua equipe de desenvolvimento, o sistema de CI e outros sistemas relevantes. É possível executar o Maven e o Bazel no mesmo repositório.

Antes de começar

• Instale o Bazel se ele ainda não estiver instalado.
• Se você não conhece o Bazel, faça o tutorial Introdução ao Bazel: criar Java antes de iniciar a migração. O tutorial explica os conceitos, a estrutura e a sintaxe de rótulo do Bazel.

Diferenças entre o Maven e o Bazel

• O Maven usa arquivos pom.xml de nível superior. O Bazel oferece suporte a vários arquivos de build e vários destinos por arquivo BUILD, permitindo builds mais incrementais do que o Maven's.
• O Maven é responsável pelas etapas do processo de implantação. O Bazel não automatiza a implantação.
• O Bazel permite expressar dependências entre idiomas.
• Ao adicionar novas seções ao projeto, com o Bazel, talvez seja necessário adicionar novos BUILD arquivos. A prática recomendada é adicionar um arquivo BUILD a cada novo pacote Java.

Migrar do Maven para o Bazel

As etapas abaixo descrevem como migrar seu projeto para o Bazel:

1. Criar o arquivo MODULE.bazel
2. Criar um arquivo BUILD
3. Criar mais arquivos BUILD
4. Criar usando o Bazel

Os exemplos abaixo são de uma migração do projeto Guava project do Maven para o Bazel. O projeto Guava usado é a versão v31.1. Os exemplos que usam o Guava não mostram cada etapa da migração, mas mostram os arquivos e conteúdos que são gerados ou adicionados manualmente para a migração.

$ git clone https://github.com/google/guava.git && cd guava
$ git checkout v31.1

1. Criar o arquivo MODULE.bazel

Crie um arquivo chamado MODULE.bazel na raiz do projeto. Se o projeto não tiver dependências externas, esse arquivo poderá ficar 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 MODULE.bazel. É possível usar rules_jvm_external para gerenciar dependências do Maven. Para instruções sobre como usar esse conjunto de regras, consulte o README .

Exemplo de projeto Guava: dependências externas

É possível listar as dependências externas do projeto Guava com o rules_jvm_external conjunto de regras.

Adicione o seguinte snippet ao arquivo MODULE.bazel:

bazel_dep(name = "rules_jvm_external", version = "6.2")
maven = use_extension("@rules_jvm_external//:extensions.bzl", "maven")
maven.install(
    artifacts = [
        "com.google.code.findbugs:jsr305:3.0.2",
        "com.google.errorprone:error_prone_annotations:2.11.0",
        "com.google.j2objc:j2objc-annotations:1.3",
        "org.codehaus.mojo:animal-sniffer-annotations:1.20",
        "org.checkerframework:checker-qual:3.12.0",
    ],
    repositories = [
        "https://repo1.maven.org/maven2",
    ],
)
use_repo(maven, "maven")

2. Criar um arquivo BUILD

Agora que você definiu seu espaço de trabalho e listou as dependências externas (se aplicável), é necessário criar BUILD arquivos para descrever como o projeto deve ser criado. Ao contrário do Maven, com um arquivo pom.xml, o Bazel pode usar muitos BUILD arquivos para criar um projeto. Esses arquivos especificam vários destinos de build, o que permite que o Bazel produza builds incrementais.

Adicione BUILD arquivos em etapas. Comece adicionando um arquivo BUILD na raiz do projeto e usando-o para fazer um build inicial usando o Bazel. Em seguida, refine o build adicionando mais BUILD arquivos com destinos mais granulares.

1. No mesmo diretório do arquivo MODULE.bazel, crie um arquivo de texto e nomeie-o como BUILD.

2. Nesse arquivo BUILD, use a regra apropriada para criar um destino para criar o projeto. Veja algumas dicas:

   • Use a regra apropriada:

     • Para criar projetos com um único módulo do Maven, use a java_library regra da seguinte maneira:

       java_library(
          name = "everything",
          srcs = glob(["src/main/java/**/*.java"]),
          resources = glob(["src/main/resources/**"]),
          deps = ["//:all-external-targets"],
       )
       

     • Para criar projetos com vários módulos do Maven, use a java_library regra da seguinte maneira:

       java_library(
          name = "everything",
          srcs = glob([
                "Module1/src/main/java/**/*.java",
                "Module2/src/main/java/**/*.java",
                ...
          ]),
          resources = glob([
                "Module1/src/main/resources/**",
                "Module2/src/main/resources/**",
                ...
          ]),
          deps = ["//:all-external-targets"],
       )
       

     • Para criar binários, use a java_binary regra:

       java_binary(
          name = "everything",
          srcs = glob(["src/main/java/**/*.java"]),
          resources = glob(["src/main/resources/**"]),
          deps = ["//:all-external-targets"],
          main_class = "com.example.Main"
       )
       

     • Especifique os atributos:

       • name: dê um nome significativo ao destino. Nos exemplos acima, o destino é chamado de "tudo".
       • srcs: use o globbing para listar todos os arquivos .java no projeto.
       • resources: use o globbing para listar todos os recursos no projeto.
       • deps: é necessário determinar quais dependências externas o projeto precisa.

     • Confira o exemplo abaixo desse arquivo BUILD de nível superior da migração do projeto Guava.

3. Agora que você tem um arquivo BUILD na raiz do projeto, crie seu projeto para garantir que ele funcione. Na linha de comando, no diretório do espaço de trabalho, use bazel build //:everything para criar o projeto com o Bazel.

   O projeto foi criado com o Bazel. Será necessário adicionar mais BUILD arquivos para permitir builds incrementais do projeto.

Exemplo de projeto Guava: começar com um arquivo BUILD

Ao migrar o projeto Guava para o Bazel, inicialmente um arquivo BUILD é usado para criar o projeto inteiro. Confira o conteúdo desse arquivo BUILD inicial no diretório do espaço de trabalho:

java_library(
    name = "everything",
    srcs = glob([
        "guava/src/**/*.java",
        "futures/failureaccess/src/**/*.java",
    ]),
    javacopts = ["-XepDisableAllChecks"],
    deps = [
        "@maven//:com_google_code_findbugs_jsr305",
        "@maven//:com_google_errorprone_error_prone_annotations",
        "@maven//:com_google_j2objc_j2objc_annotations",
        "@maven//:org_checkerframework_checker_qual",
        "@maven//:org_codehaus_mojo_animal_sniffer_annotations",
    ],
)

3. Criar mais arquivos BUILD (opcional)

O Bazel funciona com apenas um BUILD file, como você viu depois de concluir o primeiro build. No entanto, considere dividir o build em partes menores adicionando mais arquivos BUILD com destinos granulares.

Vários arquivos BUILD com vários destinos vão aumentar a granularidade do build, permitindo:

• aumento de builds incrementais do projeto,
• aumento da execução paralela do build,
• melhor capacidade de manutenção do build para futuros usuários e
• controle sobre a visibilidade dos destinos entre pacotes, o que pode evitar problemas, como bibliotecas que contêm detalhes de implementação que vazam para APIs públicas.

Dicas para adicionar mais arquivos BUILD:

• Comece adicionando um arquivo BUILD a cada pacote Java. Comece com pacotes Java que têm o menor número de dependências e trabalhe até pacotes com mais dependências.
• Ao adicionar arquivos BUILD e especificar destinos, adicione esses novos destinos às seções 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.
• Sempre que você adicionar um arquivo BUILD a um diretório main, adicione um arquivo BUILD ao diretório test correspondente.
• Tome cuidado para limitar a visibilidade corretamente entre os pacotes.
• Para simplificar a solução de problemas na configuração de arquivos BUILD, verifique se o projeto continua sendo criado com o Bazel à medida que você adiciona cada arquivo de build. Execute bazel build //... para garantir que todos os destinos ainda sejam criados.

4. Criar usando o Bazel

Você tem criado usando o Bazel à medida que adiciona arquivos BUILD para validar a configuração do build.

Quando você tem arquivos BUILD na granularidade desejada, é possível usar o Bazel para produzir todos os builds.