Como migrar do Maven para o Bazel

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

Ao migrar de qualquer ferramenta de build para o Bazel, é melhor ter as duas ferramentas em execução 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 começar a migração. O tutorial explica os conceitos, a estrutura e a sintaxe de rótulos do Bazel.

Diferenças entre Maven e Bazel

• O Maven usa arquivos pom.xml de nível superior. O Bazel é compatível com vários arquivos de build e vários destinos por arquivo BUILD, permitindo builds mais incrementais do que os do Maven.
• O Maven cuida das etapas do processo de implantação. O Bazel não automatiza a implantação.
• O Bazel permite expressar dependências entre linguagens.
• Ao adicionar novas seções ao projeto, talvez seja necessário adicionar novos arquivos BUILD com o Bazel. A prática recomendada é adicionar um arquivo BUILD a cada novo pacote do 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 do Maven para o Bazel. A versão v31.1 do projeto Guava é usada. Os exemplos que usam Guava não mostram cada etapa da migração, mas mostram os arquivos e conteúdos 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 do Guava: dependências externas

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

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), crie arquivos BUILD para descrever como seu projeto deve ser criado. Ao contrário do Maven, que tem um arquivo pom.xml, o Bazel pode usar vários arquivos BUILD para criar um projeto. Esses arquivos especificam várias metas de build, o que permite que o Bazel produza builds incrementais.

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

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

2. Neste arquivo BUILD, use a regra apropriada para criar uma meta e criar seu projeto. Veja algumas dicas:

   • Use a regra adequada:

     • Para criar projetos com um único módulo do Maven, use a regra java_library 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 regra java_library 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 regra java_binary:

       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 "everything".
       • srcs: use globbing para listar todos os arquivos .java no seu projeto.
       • resources: use o globbing para listar todos os recursos no seu projeto.
       • deps: você precisa determinar quais dependências externas seu 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 o 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 sucesso usando o Bazel. Você precisará adicionar mais arquivos BUILD para permitir builds incrementais do projeto.

Exemplo de projeto do Guava: comece com um arquivo BUILD

Ao migrar o projeto Guava para o Bazel, inicialmente um arquivo BUILD é usado para criar todo o projeto. Confira o conteúdo deste 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 sua primeira build. No entanto, considere dividir o build em partes menores adicionando mais arquivos BUILD com metas granulares.

Vários arquivos BUILD com vários destinos aumentam a granularidade do build, permitindo:

• aumento das builds incrementais do projeto;
• aumento da execução paralela da build;
• melhor capacidade de manutenção do build para usuários futuros;
• controle sobre a visibilidade de destinos entre pacotes, o que pode evitar problemas como bibliotecas que contêm detalhes de implementação vazando 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 avance até os pacotes com mais dependências.
• À medida que você adiciona arquivos BUILD e especifica destinos, adicione esses novos destinos às seções deps dos destinos que dependem deles. A função glob() não cruza limites de pacotes. 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 adequadamente entre os pacotes.
• Para simplificar a solução de problemas no seu conjunto 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 todas as suas metas ainda sejam criadas.

4. Criar usando o Bazel

Você tem criado usando o Bazel ao adicionar arquivos BUILD para validar a configuração da criação.

Quando você tiver arquivos BUILD na granularidade desejada, use o Bazel para produzir todos os builds.