Regras de repositório HTTP

As funções a seguir podem ser carregadas de @bazel_tools//tools/build_defs/repo:http.bzl.

Regras para fazer o download de arquivos e arquivos por HTTP.

Configuração

Para usar essas regras em uma extensão de módulo, carregue-as no arquivo .bzl e chame-as da função de implementação da extensão. Por exemplo, para usar http_archive:

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

def _my_extension_impl(mctx):
  http_archive(name = "foo", urls = [...])

my_extension = module_extension(implementation = _my_extension_impl)

Como alternativa, é possível chamar diretamente essas regras de repositório no arquivo MODULE.bazel com use_repo_rule:

http_archive = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(name = "foo", urls = [...])

http_archive

load("@bazel//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(name, add_prefix, auth_patterns, build_file, build_file_content, canonical_id,
             integrity, netrc, patch_args, patch_cmds, patch_cmds_win, patch_tool, patches,
             remote_file_integrity, remote_file_urls, remote_patch_strip, remote_patches,
             repo_mapping, sha256, strip_prefix, type, url, urls, workspace_file,
             workspace_file_content)

Faz o download de um repositório do Bazel como um arquivo compactado, descompacta-o e disponibiliza os destinos para vinculação.

Ele oferece suporte às seguintes extensões de arquivo: "zip", "jar", "war", "aar", "tar", "tar.gz", "tgz", "tar.xz", "txz", "tar.zst", "tzst", tar.bz2, "ar" ou "deb".

Exemplos: suponha que o repositório atual contenha o código-fonte de um programa de chat, com raiz no diretório ~/chat-app. Ele precisa depender de uma biblioteca SSL disponível em http://example.com/openssl.zip. Esse arquivo .zip contém a seguinte estrutura de diretórios:

  WORKSPACE
  src/
    openssl.cc
    openssl.h

No repositório local, o usuário cria um arquivo openssl.BUILD que contém a seguinte definição de destino:

  cc_library(
      name = "openssl-lib",
      srcs = ["src/openssl.cc"],
      hdrs = ["src/openssl.h"],
  )

Os destinos no repositório ~/chat-app podem depender desse destino se as seguintes linhas forem adicionadas a ~/chat-app/WORKSPACE:

  load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

  http_archive(
      name = "my_ssl",
      url = "http://example.com/openssl.zip",
      sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      build_file = "@//:openssl.BUILD",
  )

Em seguida, os destinos especificariam @my_ssl//:openssl-lib como uma dependência.

ATRIBUTOS

name Nome: obrigatório

Um nome exclusivo para este repositório.

add_prefix String; opcional

Diretório de destino em relação ao diretório do repositório. O arquivo será descompactado nesse diretório após a aplicação de "strip_prefix" (se houver) aos caminhos do arquivo. Por exemplo, o arquivo "foo-1.2.3/src/foo.h" será descompactado em "bar/src/foo.h" se "add_prefix = "bar" e "strip_prefix = "foo-1.2.3"".

auth_patterns Dicionário: String -> String; opcional

Um dicionário opcional que mapeia nomes de host para padrões de autorização personalizados. Se o nome do host de um URL estiver presente neste dict, o valor será usado como padrão ao gerar o cabeçalho de autorização para a solicitação HTTP. Isso permite o uso de esquemas de autorização personalizados usados em muitos provedores de armazenamento em nuvem comuns. No momento, o padrão oferece suporte a dois tokens: <login> e <password>, que são substituídos pelo valor equivalente no arquivo netrc para o mesmo nome de host. Após a formatação, o resultado é definido como o valor do campo Authorization da solicitação HTTP. Exemplo de atributo e netrc para um download HTTP em uma API ativada para OAuth2 usando um token de portador: 

auth_patterns = {
    "storage.cloudprovider.com": "Bearer <password>"
}
netrc: 
machine storage.cloudprovider.com
        password RANDOM-TOKEN
A solicitação HTTP final teria o seguinte cabeçalho: 
Authorization: Bearer RANDOM-TOKEN

build_file Rótulo: opcional

O arquivo a ser usado como BUILD para este repositório. Esse atributo é um rótulo absoluto (use "@//" para o repositório principal). O arquivo não precisa ser chamado de BUILD, mas pode ser. Algo como BUILD.new-repo-name pode ser útil para diferenciá-lo dos arquivos BUILD reais do repositório. É possível especificar build_file ou build_file_content, mas não ambos.

build_file_content String; opcional

O conteúdo do arquivo BUILD para este repositório. É possível especificar build_file ou build_file_content, mas não ambos.

canonical_id String; opcional

Um ID canônico do arquivo transferido por download. Se especificado e não vazio, o Bazel não vai extrair o arquivo do cache, a menos que ele tenha sido adicionado ao cache por uma solicitação com o mesmo ID canônico. Se não for especificado ou estiver vazio, o Bazel por padrão usará os URLs do arquivo como o ID canônico. Isso ajuda a detectar o erro comum de atualizar os URLs sem atualizar o hash, resultando em builds bem-sucedidos localmente, mas que falham em máquinas sem o arquivo no cache. Esse comportamento pode ser desativado com --repo_env=BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID=0.

integrity String; opcional

Soma de verificação esperada no formato de integridade do subrecurso do arquivo salvo. Ela precisa corresponder à soma de verificação do arquivo transferido por download. _É um risco de segurança omitir a checksum, já que arquivos remotos podem mudar._ Na melhor das hipóteses, omitir esse campo vai tornar seu build não hermético. É opcional para facilitar o desenvolvimento, mas esse atributo ou "sha256" precisa ser definido antes do envio.

netrc String; opcional

Localização do arquivo .netrc a ser usado para autenticação

patch_args Lista de strings; opcional

Os argumentos fornecidos à ferramenta de patch. O padrão é -p0, mas -p1 geralmente é necessário para patches gerados pelo git. Se vários argumentos -p forem especificados, o último vai entrar em vigor.Se argumentos diferentes de -p forem especificados, o Bazel vai usar a ferramenta de linha de comando de patch em vez da implementação de patch nativa do Bazel. Quando a ferramenta de linha de comando de patch e o atributo patch_tool não forem especificados, o "patch" será usado. Isso afeta apenas os arquivos de patch no atributo "patches".

patch_cmds Lista de strings, opcional

Sequência de comandos do Bash a serem aplicados no Linux/Macos depois que os patches forem aplicados.

patch_cmds_win Lista de strings; opcional

Sequência de comandos do PowerShell a serem aplicados no Windows depois que os patches forem aplicados. Se esse atributo não for definido, o patch_cmds será executado no Windows, o que exige que o binário do Bash exista.

patch_tool String; opcional

O utilitário patch(1) a ser usado. Se isso for especificado, o Bazel vai usar a ferramenta de patch especificada em vez da implementação de patch nativa do Bazel.

patches Lista de rótulos; opcional

Uma lista de arquivos que serão aplicados como patches após a extração do arquivo. Por padrão, ele usa a implementação de patch nativa do Bazel, que não oferece suporte a correspondência de fuzz e patch binário, mas o Bazel vai usar a ferramenta de linha de comando de patch se o atributo "patch_tool" for especificado ou se houver argumentos diferentes de "-p" no atributo "patch_args".

remote_file_integrity Dicionário: String -> String; opcional

Um mapa dos caminhos relativos do arquivo (chave) para o valor de integridade (valor). Esses caminhos relativos precisam ser mapeados para os arquivos (chave) no atributo "remote_file_urls".

remote_file_urls Dicionário: string -> lista de strings; opcional

Um mapa de caminhos relativos (chave) para uma lista de URLs (valor) que serão transferidos por download e disponibilizados como arquivos sobrepostos no repositório. Isso é útil quando você quer adicionar arquivos WORKSPACE ou BUILD.bazel em um repositório. Os arquivos são transferidos antes da aplicação dos patches no atributo "patches", e a lista de URLs precisa ser um possível espelho do mesmo arquivo. Os URLs são testados em ordem até que um deles tenha sucesso.

remote_patch_strip Número inteiro; opcional

O número de barras iniciais a serem removidas do nome do arquivo nos patches remotos.

remote_patches Dictionary: String -> String; opcional.

Um mapeamento do URL do arquivo de patch para o valor de integridade. Eles são aplicados após a extração do arquivo e antes da aplicação de arquivos de patch do atributo "patches". Ele usa a implementação de patch nativa do Bazel. É possível especificar o número da faixa de patch com "remote_patch_strip"

repo_mapping Dicionário: String -> String; opcional

No contexto "WORKSPACE": um dicionário do nome do repositório local para o nome do repositório global. Isso permite o controle sobre a resolução de dependências do espaço de trabalho para dependências deste repositório. Por exemplo, uma entrada "@foo": "@bar" declara que, sempre que esse repositório depender de@foo (como uma dependência de@foo//some:target, ele precisa resolver essa dependência dentro de@bar declarado globalmente ("@bar//some:target"). Esse atributo _não_ tem suporte no contexto "MODULE.bazel" (ao invocar uma regra de repositório dentro da função de implementação de uma extensão de módulo).

sha256 String, opcional

O SHA-256 esperado do arquivo transferido por download. Precisa corresponder ao SHA-256 do arquivo baixado. _É um risco de segurança omitir o SHA-256, já que os arquivos remotos podem ser alterados._ A omissão desse campo tornará sua compilação não hermética. É opcional para facilitar o desenvolvimento, mas esse atributo ou "integrity" precisa ser definido antes do envio.

strip_prefix String, opcional

Um prefixo de diretório a ser removido dos arquivos extraídos. Muitos arquivos têm um diretório de nível superior que contém todos os arquivos úteis no arquivo. Em vez de precisar especificar esse prefixo várias vezes em "build_file", esse campo pode ser usado para removê-lo de todos os arquivos extraídos. Por exemplo, suponha que você esteja usando "foo-lib-latest.zip", que contém o diretório "foo-lib-1.2.3/", em que há um arquivo "WORKSPACE" e "src/", "lib/" e "test/", que contêm o código que você quer criar. Especifique "strip_prefix = "foo-lib-1.2.3"" para usar o diretório "foo-lib-1.2.3" como o diretório de nível superior. Se houver arquivos fora desse diretório, eles serão descartados e ficarão inacessíveis (por exemplo, um arquivo de licença de nível superior). Isso inclui arquivos/diretórios que começam com o prefixo, mas que não estão no diretório (por exemplo, `foo-lib-1.2.3.release-notes`). Se o prefixo especificado não corresponder a um diretório no arquivo, o Bazel vai retornar um erro.

type String; opcional

O tipo do arquivo baixado. Por padrão, o tipo de arquivo é determinado pela extensão do arquivo do URL. Se o arquivo não tiver uma extensão, especifique explicitamente uma das seguintes: `"zip"`, `"jar"`, `"war"`, `"war"`, `"aar"`, `"tar"`, `"tar.gz"`, `"tgz"`, `"tar.xz"`, `"txz"`, `"tar.zst"`, `"tzst"`, `"tar.bz2"`, `"ar"` ou `"deb"`.

url String; opcional

Um URL para um arquivo que será disponibilizado para o Bazel. Precisa ser um arquivo, URL http ou https. Os redirecionamentos são seguidos. A autenticação não é aceita. É possível ter mais flexibilidade com o parâmetro urls, que permite especificar URLs alternativos para buscar.

urls Lista de strings; opcional

Uma lista de URLs para um arquivo que será disponibilizado para o Bazel. Cada entrada precisa ser um arquivo, URL http ou https. Os redirecionamentos são seguidos. A autenticação não é aceita. Os URLs são tentados em ordem até que um deles seja bem-sucedido. Portanto, liste os espelhos locais primeiro. Se todos os downloads falharem, a regra também vai falhar.

workspace_file Rótulo: opcional

O arquivo a ser usado como "WORKSPACE" para este repositório. É possível especificar `workspace_file` ou `workspace_file_content` ou nenhum deles, mas não ambos.

workspace_file_content String, opcional

O conteúdo do arquivo WORKSPACE para este repositório. É possível especificar "workspace_file" ou "workspace_file_content", mas não ambos.

VARIÁVEIS DE AMBIENTE

Essa regra de repositório depende das seguintes variáveis de ambiente:

  • BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID

http_file

load("@bazel//tools/build_defs/repo:http.bzl", "http_file")

http_file(name, auth_patterns, canonical_id, downloaded_file_path, executable, integrity, netrc,
          repo_mapping, sha256, url, urls)

Faz o download de um arquivo de um URL e o disponibiliza para uso como um grupo de arquivos.

Exemplos: Suponha que você precise ter um pacote Debian para suas regras personalizadas. Esse pacote está disponível em http://example.com/package.deb. Em seguida, adicione ao arquivo WORKSPACE:

  load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")

  http_file(
      name = "my_deb",
      url = "http://example.com/package.deb",
      sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  )

Os destinos especificariam @my_deb//file como uma dependência para depender desse arquivo.

ATRIBUTOS

name Nome, obrigatório

Um nome exclusivo para este repositório.

auth_patterns Dicionário: String -> String; opcional

Um dicionário opcional que mapeia nomes de host para padrões de autorização personalizados. Se o nome de host de um URL estiver presente no dicionário, o valor será usado como um padrão ao gerar o cabeçalho de autorização para a solicitação HTTP. Isso permite o uso de esquemas de autorização personalizados usados em muitos provedores de armazenamento em nuvem comuns. No momento, o padrão oferece suporte a dois tokens: <login> e <password>, que são substituídos pelo valor equivalente no arquivo netrc para o mesmo nome de host. Após a formatação, o resultado é definido como o valor do campo Authorization da solicitação HTTP. Exemplo de atributo e netrc para um download HTTP em uma API ativada para OAuth2 usando um token de portador: 

auth_patterns = {
    "storage.cloudprovider.com": "Bearer <password>"
}
netrc: 
machine storage.cloudprovider.com
        password RANDOM-TOKEN
A solicitação HTTP final teria o seguinte cabeçalho: 
Authorization: Bearer RANDOM-TOKEN

canonical_id String, opcional

Um ID canônico do arquivo transferido por download. Se especificado e não vazio, o Bazel não vai extrair o arquivo do cache, a menos que ele tenha sido adicionado ao cache por uma solicitação com o mesmo ID canônico. Se não for especificado ou estiver vazio, o Bazel por padrão usará os URLs do arquivo como o ID canônico. Isso ajuda a detectar o erro comum de atualizar os URLs sem atualizar o hash, resultando em builds bem-sucedidos localmente, mas que falham em máquinas sem o arquivo no cache. Esse comportamento pode ser desativado com --repo_env=BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID=0.

downloaded_file_path String; opcional

Caminho atribuído ao arquivo transferido por download

executable Booleano; opcional

Se o arquivo baixado precisa ser executável.

integrity String; opcional

Soma de verificação esperada no formato de integridade do subrecurso do arquivo salvo. Ela precisa corresponder à soma de verificação do arquivo transferido por download. _É um risco de segurança omitir a checksum, já que arquivos remotos podem mudar._ Na melhor das hipóteses, omitir esse campo vai tornar seu build não hermético. É opcional para facilitar o desenvolvimento, mas esse atributo ou "sha256" precisa ser definido antes do envio.

netrc String; opcional

Localização do arquivo .netrc a ser usado para autenticação

repo_mapping Dicionário: String -> String; opcional

No contexto "WORKSPACE" somente: um dicionário do nome do repositório local para o nome do repositório global. Isso permite o controle sobre a resolução de dependências do espaço de trabalho para dependências deste repositório. Por exemplo, uma entrada `"@foo": "@bar"` declara que, a qualquer momento, este repositório depende de "@foo" (como uma dependência de "@foo//some:target", ele deve realmente resolver essa dependência dentro do "@bar" declarado globalmente ("@bar//some:target"). Este atributo _não_ é compatível com a implementação de um repositório de regras de extensão do módulo.bazel.

sha256 String, opcional

O SHA-256 esperado do arquivo transferido por download. Ele precisa corresponder ao SHA-256 do arquivo transferido por download. _É um risco de segurança omitir o SHA-256, porque os arquivos remotos podem mudar._ Na melhor das hipóteses, omitir esse campo vai tornar seu build não hermético. É opcional para facilitar o desenvolvimento, mas precisa ser definido antes do envio.

url String; opcional

Um URL para um arquivo que será disponibilizado para o Bazel. Precisa ser um arquivo, URL http ou https. Os redirecionamentos são seguidos. A autenticação não é aceita. É possível ter mais flexibilidade com o parâmetro urls, que permite especificar URLs alternativos para buscar.

urls Lista de strings; opcional

Uma lista de URLs para um arquivo que será disponibilizado para o Bazel. Cada entrada precisa ser um arquivo, URL http ou https. Os redirecionamentos são seguidos. A autenticação não é aceita. Os URLs são tentados em ordem até que um deles seja bem-sucedido. Portanto, liste os espelhos locais primeiro. Se todos os downloads falharem, a regra também vai falhar.

VARIÁVEIS DE AMBIENTE

Essa regra do repositório depende das seguintes variáveis de ambiente:

  • BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID

http_jar

load("@bazel//tools/build_defs/repo:http.bzl", "http_jar")

http_jar(name, auth_patterns, canonical_id, downloaded_file_name, integrity, netrc, repo_mapping,
         sha256, url, urls)

Faz o download de um JAR de um URL e o disponibiliza como java_import

Os arquivos transferidos por download precisam ter a extensão .jar.

Exemplos: suponha que o repositório atual contenha o código-fonte de um programa de chat, com raiz no diretório ~/chat-app. Ela precisa depender de uma biblioteca SSL, disponível em http://example.com/openssl-0.2.jar.

Os destinos no repositório ~/chat-app podem depender desse destino se as linhas a seguir forem adicionadas a ~/chat-app/WORKSPACE:

  load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_jar")

  http_jar(
      name = "my_ssl",
      url = "http://example.com/openssl-0.2.jar",
      sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  )

Os destinos especificariam @my_ssl//jar como uma dependência para depender desse jar.

Também é possível fazer referência a arquivos no sistema atual (localhost) usando "file:///path/to/file" se você estiver em sistemas baseados em Unix. No Windows, use "file:///c:/path/to/file". Em ambos os exemplos, observe os três tracinhos (/). Os dois primeiros tracinhos pertencem a file://, e o terceiro pertence ao caminho absoluto do arquivo.

ATRIBUTOS

name Nome: obrigatório

Um nome exclusivo para este repositório.

auth_patterns Dicionário: String -> String; opcional

Um dict opcional que mapeia nomes de host para padrões de autorização personalizados. Se o nome de host de um URL estiver presente no dicionário, o valor será usado como um padrão ao gerar o cabeçalho de autorização para a solicitação HTTP. Isso permite o uso de esquemas de autorização personalizados usados em muitos provedores de armazenamento em nuvem comuns. No momento, o padrão oferece suporte a dois tokens: <login> e <password>, que são substituídos pelo valor equivalente no arquivo netrc para o mesmo nome de host. Após a formatação, o resultado é definido como o valor do campo Authorization da solicitação HTTP. Exemplo de atributo e netrc para um download HTTP em uma API ativada para OAuth2 usando um token de portador: 

auth_patterns = {
    "storage.cloudprovider.com": "Bearer <password>"
}
netrc: 
machine storage.cloudprovider.com
        password RANDOM-TOKEN
A solicitação HTTP final teria o seguinte cabeçalho: 
Authorization: Bearer RANDOM-TOKEN

canonical_id String; opcional

Um ID canônico do arquivo transferido por download. Se especificado e não vazio, o Bazel não vai extrair o arquivo do cache, a menos que ele tenha sido adicionado ao cache por uma solicitação com o mesmo ID canônico. Se não for especificado ou estiver vazio, o Bazel por padrão usará os URLs do arquivo como o ID canônico. Isso ajuda a detectar o erro comum de atualizar os URLs sem atualizar o hash, resultando em builds bem-sucedidos localmente, mas que falham em máquinas sem o arquivo no cache. Esse comportamento pode ser desativado com --repo_env=BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID=0.

downloaded_file_name String, opcional

Nome do arquivo atribuído ao jar transferido por download

integrity String; opcional

Soma de verificação esperada no formato de integridade do subrecurso do arquivo salvo. Ela precisa corresponder à soma de verificação do arquivo transferido por download. _É um risco de segurança omitir a checksum, já que arquivos remotos podem mudar._ Na melhor das hipóteses, omitir esse campo vai tornar seu build não hermético. É opcional para facilitar o desenvolvimento, mas esse atributo ou "sha256" precisa ser definido antes do envio.

netrc String; opcional

Localização do arquivo .netrc a ser usado para autenticação

repo_mapping Dicionário: String -> String; opcional

Somente no contexto "WORKSPACE": um dicionário do nome do repositório local para o nome do repositório global. Isso permite o controle da resolução de dependências do espaço de trabalho para dependências desse repositório. Por exemplo, uma entrada "@foo": "@bar" declara que, sempre que esse repositório depender de@foo (como uma dependência de@foo//some:target, ele precisa resolver essa dependência dentro de@bar declarado globalmente ("@bar//some:target"). Esse atributo _não_ tem suporte no contexto "MODULE.bazel" (ao invocar uma regra de repositório dentro da função de implementação de uma extensão de módulo).

sha256 String, opcional

O SHA-256 esperado do arquivo transferido por download. Precisa corresponder ao SHA-256 do arquivo baixado. _É um risco de segurança omitir o SHA-256, já que os arquivos remotos podem ser alterados._ A omissão desse campo tornará sua compilação não hermética. É opcional para facilitar o desenvolvimento, mas esse atributo ou "integrity" precisa ser definido antes do envio.

url String; opcional

Um URL para um arquivo que será disponibilizado para o Bazel. Precisa ser um arquivo, URL http ou https. Os redirecionamentos são seguidos. A autenticação não é aceita. É possível ter mais flexibilidade com o parâmetro urls, que permite especificar URLs alternativos para buscar. O URL precisa terminar em ".jar".

urls Lista de strings; opcional

Uma lista de URLs para um arquivo que será disponibilizado para o Bazel. Cada entrada precisa ser um arquivo, URL http ou https. Os redirecionamentos são seguidos. A autenticação não é aceita. Os URLs são tentados em ordem até que um deles seja bem-sucedido. Portanto, liste os espelhos locais primeiro. Se todos os downloads falharem, a regra também vai falhar. Todos os URLs precisam terminar em ".jar".

VARIÁVEIS DE AMBIENTE

Essa regra do repositório depende das seguintes variáveis de ambiente:

  • BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID