Archivos .bzl

Informar un problema Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Métodos globales disponibles en todos los archivos .bzl.

Miembros

analysis_test_transition

transition analysis_test_transition(settings)

Crea una transición de configuración para aplicar a las dependencias de una regla de prueba de análisis. Esta transición solo se puede aplicar en atributos de reglas con analysis_test = True. Estas reglas tienen capacidades restringidas (por ejemplo, el tamaño de su árbol de dependencias es limitado), por lo que las transiciones creadas con esta función tienen un alcance potencial limitado en comparación con las transiciones creadas con transition().

Esta función está diseñada principalmente para facilitar la biblioteca principal de Analysis Test Framework. Consulta su documentación (o su implementación) para conocer las prácticas recomendadas.

Parámetros

Parámetro Descripción
settings dict; obligatorio
Es un diccionario que contiene información sobre los parámetros de configuración que se deben establecer con esta transición de configuración. Las claves son etiquetas de configuración de compilación y los valores son sus nuevos valores posteriores a la transición. Todos los demás parámetros de configuración permanecen sin cambios. Úsalo para declarar parámetros de configuración específicos que una prueba de análisis requiere que se establezcan para aprobarse.

aspecto

Aspect aspect(implementation, attr_aspects=[], toolchains_aspects=[], attrs={}, required_providers=[], required_aspect_providers=[], provides=[], requires=[], fragments=[], host_fragments=[], toolchains=[], incompatible_use_toolchain_transition=False, doc=None, *, apply_to_generating_rules=False, exec_compatible_with=[], exec_groups=None, subrules=[])

Crea un aspecto nuevo. El resultado de esta función se debe almacenar en un valor global. Consulta la introducción a los aspectos para obtener más detalles.

Parámetros

Parámetro Descripción
implementation function: obligatorio
Una función de Starlark que implementa este aspecto, con exactamente dos parámetros: Target (el destino al que se aplica el aspecto) y ctx (el contexto de la regla a partir del cual se crea el destino). Los atributos del objetivo están disponibles a través del campo ctx.rule. Esta función se evalúa durante la fase de análisis para cada aplicación de un aspecto a un destino.
attr_aspects sequence de strings; el valor predeterminado es []
Lista de nombres de atributos. El aspecto se propaga a lo largo de las dependencias especificadas en los atributos de un destino con estos nombres. Los valores comunes aquí incluyen deps y exports. La lista también puede contener una sola cadena "*" para propagarse a lo largo de todas las dependencias de un destino.
toolchains_aspects sequence; El valor predeterminado es []
Lista de tipos de cadenas de herramientas. El aspecto se propaga a las cadenas de herramientas de destino que coinciden con estos tipos de cadenas de herramientas.
attrs dict; El valor predeterminado es {}
Diccionario que declara todos los atributos del aspecto. Se asigna desde un nombre de atributo a un objeto de atributo, como attr.label o attr.string (consulta el módulo attr). Los atributos de aspecto están disponibles para la función de implementación como campos del parámetro ctx.

Los atributos implícitos que comienzan con _ deben tener valores predeterminados y ser de tipo label o label_list.

Los atributos explícitos deben tener el tipo string y usar la restricción values. Los atributos explícitos restringen el aspecto para que solo se use con reglas que tengan atributos con el mismo nombre, tipo y valores válidos según la restricción.

Los atributos declarados convertirán None al valor predeterminado.
required_providers sequence; el valor predeterminado es []
Este atributo permite que el aspecto limite su propagación solo a los objetivos cuyas reglas anuncian sus proveedores requeridos. El valor debe ser una lista que contenga proveedores individuales o listas de proveedores, pero no ambos. Por ejemplo, [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] es un valor válido, mientras que [FooInfo, BarInfo, [BazInfo, QuxInfo]] no lo es.

Una lista de proveedores sin anidar se convertirá automáticamente en una lista que contiene una lista de proveedores. Es decir, [FooInfo, BarInfo] se convertirá automáticamente en [[FooInfo, BarInfo]].

Para que un aspecto pueda ver el objetivo de alguna regla (p.ej., some_rule), some_rule debe anunciar todos los proveedores de al menos una de las listas de proveedores requeridos. Por ejemplo, si el required_providers de un aspecto es [[FooInfo], [BarInfo], [BazInfo, QuxInfo]], este aspecto puede ver los objetivos de some_rule solo si some_rule proporciona FooInfo, o BarInfo, o ambos BazInfo y QuxInfo.

required_aspect_providers sequence; el valor predeterminado es []
Este atributo permite que este aspecto inspeccione otros aspectos. El valor debe ser una lista que contenga proveedores individuales o listas de proveedores, pero no ambos. Por ejemplo, [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] es un valor válido, mientras que [FooInfo, BarInfo, [BazInfo, QuxInfo]] no lo es.

Una lista de proveedores sin anidar se convertirá automáticamente en una lista que contiene una lista de proveedores. Es decir, [FooInfo, BarInfo] se convertirá automáticamente en [[FooInfo, BarInfo]].

Para que otro aspecto (p.ej., other_aspect) sea visible para este aspecto, other_aspect debe proporcionar todos los proveedores de al menos una de las listas. En el ejemplo de [[FooInfo], [BarInfo], [BazInfo, QuxInfo]], este aspecto puede ver other_aspect solo si other_aspect proporciona FooInfo, o BarInfo, o ambos BazInfo y QuxInfo.

provides sequence; El valor predeterminado es []
Es una lista de proveedores que debe devolver la función de implementación.

Es un error si la función de implementación omite cualquiera de los tipos de proveedores que se enumeran aquí de su valor de devolución. Sin embargo, la función de implementación puede devolver proveedores adicionales que no se mencionan aquí.

Cada elemento de la lista es un objeto *Info que devuelve provider(), excepto que un proveedor heredado se representa con su nombre de cadena.Cuando un destino de la regla se usa como dependencia de un destino que declara un proveedor obligatorio, no es necesario especificar ese proveedor aquí. Es suficiente con que la función de implementación lo devuelva. Sin embargo, se considera una práctica recomendada especificarlo, aunque no sea obligatorio. Sin embargo, el campo required_providers de un aspecto requiere que los proveedores se especifiquen aquí.

requires sequence de Aspects; el valor predeterminado es []
Lista de aspectos que se deben propagar antes de este aspecto.
fragments sequence de strings; el valor predeterminado es []
Lista de nombres de fragmentos de configuración que el aspecto requiere en la configuración de destino.
host_fragments sequence de strings; el valor predeterminado es []
Lista de nombres de fragmentos de configuración que el aspecto requiere en la configuración del host.
toolchains sequence; el valor predeterminado es []
Si se configura, es el conjunto de cadenas de herramientas que requiere este aspecto. La lista puede contener objetos String, Label o StarlarkToolchainTypeApi, en cualquier combinación. Las cadenas de herramientas se encontrarán verificando la plataforma actual y se proporcionarán a la implementación del aspecto a través de ctx.toolchain.
incompatible_use_toolchain_transition bool; el valor predeterminado es False
Obsoleto. Ya no se usa y se debe quitar.
doc cadena o None; El valor predeterminado es None
Es una descripción del aspecto que pueden extraer las herramientas de generación de documentación.
apply_to_generating_rules bool; el valor predeterminado es False
Si es verdadero, cuando el aspecto se aplique a un archivo de salida, se aplicará a la regla de generación del archivo de salida.

Por ejemplo, supongamos que un aspecto se propaga de forma transitiva a través del atributo "deps" y se aplica al destino "alfa". Supongamos que "alfa" tiene "deps = [":beta_output"]", donde "beta_output" es un resultado declarado de un destino "beta". Supongamos que "beta" tiene un destino "charlie" como uno de sus "deps". Si "apply_to_generating_rules=True" para el aspecto, entonces el aspecto se propagará a través de "alfa", "beta" y "charlie". Si es False, el aspecto solo se propagará a "alfa".

El valor predeterminado es falso.
exec_compatible_with secuencia de cadenas; el valor predeterminado es []
Es una lista de restricciones en la plataforma de ejecución que se aplican a todas las instancias de este aspecto.
exec_groups dict o None; el valor predeterminado es None
Es un diccionario del nombre del grupo de ejecución (cadena) para exec_groups. Si se configura, permite que los aspectos ejecuten acciones en varias plataformas de ejecución dentro de una sola instancia. Consulta la documentación sobre grupos de ejecución para obtener más información.
subrules secuencia de Subrules; el valor predeterminado es []
Experimental: Es la lista de subreglas que usa este aspecto.

configuration_field

LateBoundDefault configuration_field(fragment, name)

Hace referencia a un valor predeterminado de vinculación tardía para un atributo de tipo label. Un valor es "de vinculación tardía" si requiere que se compile la configuración antes de determinar el valor. Cualquier atributo que use esto como valor debe ser privado.

Ejemplo de uso:

Definición de un atributo de regla: 

'_foo': attr.label(default=configuration_field(fragment='java', name='toolchain'))

Acceso en la implementación de reglas: 

  def _rule_impl(ctx):
    foo_info = ctx.attr._foo
    ...

Parámetros

Parámetro Descripción
fragment string; obligatorio
Nombre de un fragmento de configuración que contiene el valor vinculado tardíamente.
name string; obligatorio
Nombre del valor que se obtendrá del fragmento de configuración.

deps

depset depset(direct=None, order="default", *, transitive=None)

Crea un depset. El parámetro direct es una lista de elementos directos del depset, y el parámetro transitive es una lista de depsets cuyos elementos se convierten en elementos indirectos del depset creado. El parámetro order especifica el orden en el que se muestran los elementos cuando el depset se convierte en una lista. Consulta la Descripción general de los depsets para obtener más información.

Todos los elementos (directos e indirectos) de un depset deben ser del mismo tipo, como se obtiene con la expresión type(x).

Dado que se usa un conjunto basado en hash para eliminar duplicados durante la iteración, todos los elementos de un depset deben ser hashables. Sin embargo, esta invariante no se verifica de manera coherente en todos los constructores. Usa la marca --incompatible_always_check_depset_elements para habilitar la verificación coherente. Este será el comportamiento predeterminado en versiones futuras. Consulta el problema 10313.

Además, los elementos deben ser inmutables, aunque esta restricción se flexibilizará en el futuro.

El orden del depset creado debe ser compatible con el orden de sus depsets de transitive. El orden "default" es compatible con cualquier otro orden, mientras que todos los demás órdenes solo son compatibles entre sí.

Parámetros

Parámetro Descripción
direct sequence o None; El valor predeterminado es None
Es una lista de elementos directos de un depset.
order string; el valor predeterminado es "default"
Estrategia de recorrido para el nuevo depset. Consulta aquí los valores posibles.
transitive sequence de depsets o None; el valor predeterminado es None
Es una lista de depsets cuyos elementos se convertirán en elementos indirectos del depset.

exec_group

exec_group exec_group(toolchains=[], exec_compatible_with=[])

Crea un grupo de ejecución que se puede usar para crear acciones para una plataforma de ejecución específica durante la implementación de la regla.

Parámetros

Parámetro Descripción
toolchains sequence; El valor predeterminado es []
Es el conjunto de cadenas de herramientas que requiere este grupo de ejecución. La lista puede contener objetos String, Label o StarlarkToolchainTypeApi, en cualquier combinación.
exec_compatible_with sequence de strings; el valor predeterminado es []
Es una lista de restricciones en la plataforma de ejecución.

exec_transition

transition exec_transition(implementation, inputs, outputs)

Es una versión especializada de transition() que se usa para definir la transición de ejecución. Consulta su documentación (o su implementación) para conocer las prácticas recomendadas. Solo se puede usar desde los elementos integrados de Bazel.

Parámetros

Parámetro Descripción
implementation callable; required
inputs secuencia de cadenas; obligatorio
outputs secuencia de cadenas; obligatorio

macro

macro macro(implementation, attrs={}, inherit_attrs=None, finalizer=False, doc=None)

Define una macro simbólica que se puede llamar en archivos o macros BUILD (heredados o simbólicos) para definir destinos, posiblemente varios.

El valor que devuelve macro(...) se debe asignar a una variable global en un archivo .bzl. El nombre de la variable global será el nombre del símbolo de la macro.

Consulta Macros para obtener una guía completa sobre cómo usar macros simbólicas.

Parámetros

Parámetro Descripción
implementation function; required
Es la función de Starlark que implementa esta macro. Los valores de los atributos de la macro se pasan a la función de implementación como argumentos de palabras clave. La función de implementación debe tener al menos dos parámetros con nombre, name y visibility, y, si la macro hereda atributos (consulta inherit_attrs a continuación), debe tener un parámetro de palabra clave residual **kwargs.

Por convención, la función de implementación debe tener un parámetro con nombre para cualquier atributo que la macro necesite examinar, modificar o pasar a destinos que no sean "principales", mientras que los atributos heredados "masivos" que se pasarán al destino "principal" sin cambios se pasan como **kwargs.

La función de implementación no debe devolver un valor. En cambio, la función de implementación declara destinos llamando a símbolos de reglas o macros.

El nombre de cualquier macro simbólica objetivo o interna declarada por una macro simbólica (incluida cualquier función de Starlark a la que llame de forma transitiva la función de implementación de la macro) debe ser igual a name (a esto se hace referencia como el objetivo "principal") o comenzar con name, seguido de un carácter separador ("_", "-" o ".") y un sufijo de cadena. (Se permite declarar destinos que incumplen este esquema de nombres, pero no se pueden compilar, configurar ni depender de ellos).

De forma predeterminada, los destinos declarados por una macro simbólica (incluidos los de cualquier función de Starlark a la que llame de forma transitiva la función de implementación de la macro) solo son visibles en el paquete que contiene el archivo .bzl que define la macro. Para declarar que los destinos son visibles de forma externa, incluso para el llamador de la macro simbólica, la función de implementación debe establecer visibility de forma adecuada, por lo general, pasando visibility = visibility al símbolo de regla o macro que se llama.

Las siguientes APIs no están disponibles dentro de una función de implementación de macros ni en ninguna función de Starlark a la que llame de forma transitiva:

attrs dict: El valor predeterminado es {}
Diccionario de los atributos que admite esta macro, análogo a rule.attrs. Las claves son nombres de atributos, y los valores son objetos de atributos, como attr.label_list(...) (consulta el módulo attr), o bien None. Una entrada None significa que la macro no tiene un atributo con ese nombre, incluso si, de lo contrario, habría heredado uno a través de inherit_attrs (consulta a continuación).

El atributo especial name se declara previamente y no debe incluirse en el diccionario. El nombre del atributo visibility está reservado y no debe incluirse en el diccionario.

Los atributos cuyos nombres comienzan con _ son privados, por lo que no se pueden pasar en el sitio de llamada de la regla. A estos atributos se les puede asignar un valor predeterminado (como en attr.label(default="//pkg:foo")) para crear una dependencia implícita en una etiqueta.

Para limitar el uso de memoria, hay un límite en la cantidad de atributos que se pueden declarar.

inherit_attrs rule, macro, string o None; El valor predeterminado es None
Símbolo de regla, símbolo de macro o nombre de una lista de atributos comunes integrada (consulta a continuación) de la que la macro debe heredar atributos.

Si inherit_attrs se establece en la cadena "common", la macro heredará las definiciones de atributos de reglas comunes que usan todas las reglas de Starlark.

Ten en cuenta que, si el valor de retorno de rule() o macro() no se asignó a una variable global en un archivo .bzl, ese valor no se registró como un símbolo de regla o macro y, por lo tanto, no se puede usar para inherit_attrs.

El mecanismo de herencia funciona de la siguiente manera:

  1. Los atributos especiales name y visibility nunca se heredan.
  2. Los atributos ocultos (aquellos cuyo nombre comienza con "_") nunca se heredan.
  3. Los atributos cuyos nombres ya están definidos en el diccionario attrs nunca se heredan (la entrada en attrs tiene prioridad; ten en cuenta que una entrada se puede establecer en None para garantizar que no se defina ningún atributo con ese nombre en la macro).
  4. Todos los demás atributos se heredan de la regla o macro y se combinan de manera efectiva en el diccionario attrs.

Cuando se hereda un atributo no obligatorio, se anula el valor predeterminado del atributo y se establece en None, independientemente de lo que se haya especificado en la regla o macro original. Esto garantiza que, cuando la macro reenvíe el valor del atributo a una instancia de la regla o macro encapsulada (por ejemplo, pasando el **kwargs sin modificar), un valor que estaba ausente en la llamada de la macro externa también estará ausente en la llamada de la regla o macro interna (ya que pasar None a un atributo se considera lo mismo que omitir el atributo). Esto es importante porque omitir un atributo tiene una semántica ligeramente diferente a la de pasar su valor predeterminado aparente. En particular, los atributos omitidos no se muestran en algunos formatos de salida de bazel query, y los valores predeterminados calculados solo se ejecutan cuando se omite el valor. Si la macro necesita examinar o modificar un atributo heredado (por ejemplo, para agregar un valor a un atributo tags heredado), debes asegurarte de controlar el caso None en la función de implementación de la macro.

Por ejemplo, la siguiente macro hereda todos los atributos de native.cc_library, excepto cxxopts (que se quita de la lista de atributos) y copts (que recibe una nueva definición). También se encarga de verificar el valor predeterminado None del atributo tags heredado antes de agregar una etiqueta adicional. 

def _my_cc_library_impl(name, visibility, tags, **kwargs):
    # Append a tag; tags attr was inherited from native.cc_library, and
    # therefore is None unless explicitly set by the caller of my_cc_library()
    my_tags = (tags or []) + ["my_custom_tag"]
    native.cc_library(
        name = name,
        visibility = visibility,
        tags = my_tags,
        **kwargs
    )

my_cc_library = macro(
    implementation = _my_cc_library_impl,
    inherit_attrs = native.cc_library,
    attrs = {
        "cxxopts": None,
        "copts": attr.string_list(default = ["-D_FOO"]),
    },
)

Si se configura inherit_attrs, la función de implementación de la macro debe tener un parámetro de palabra clave residual **kwargs.

Por convención, una macro debe pasar los atributos heredados y no anulados sin cambios al símbolo de regla o macro "principal" que la macro está encapsulando. Por lo general, la mayoría de los atributos heredados no tendrán un parámetro en la lista de parámetros de la función de implementación y simplemente se pasarán a través de **kwargs. Puede ser conveniente que la función de implementación tenga parámetros explícitos para algunos atributos heredados (más comúnmente, tags y testonly) si la macro necesita pasar esos atributos a los destinos "principales" y no "principales", pero si la macro también necesita examinar o manipular esos atributos, debes tener cuidado de controlar el valor predeterminado None de los atributos heredados no obligatorios.

finalizer bool; el valor predeterminado es False
Indica si esta macro es un finalizador de reglas, es decir, una macro que, independientemente de su posición en un archivo BUILD, se evalúa al final de la carga del paquete, después de que se hayan definido todos los destinos que no son finalizadores.

A diferencia de las macros simbólicas comunes, los finalizadores de reglas pueden llamar a native.existing_rule() y native.existing_rules() para consultar el conjunto de destinos de reglas no finalizadores definidos en el paquete actual. Ten en cuenta que native.existing_rule() y native.existing_rules() no pueden acceder a los destinos definidos por ningún finalizador de reglas, incluido este.

doc string o None; El valor predeterminado es None
Es una descripción de la macro que pueden extraer las herramientas de generación de documentación.

module_extension

unknown module_extension(implementation, *, tag_classes={}, doc=None, environ=[], os_dependent=False, arch_dependent=False)

Crea una extensión de módulo nueva. Almacénalo en un valor global para que se pueda exportar y usar en un archivo MODULE.bazel con use_extension.

Parámetros

Parámetro Descripción
implementation callable; required
La función que implementa esta extensión del módulo. Debe tomar un solo parámetro, module_ctx. Se llama a la función una vez al comienzo de una compilación para determinar el conjunto de repositorios disponibles.
tag_classes dict; El valor predeterminado es {}
Diccionario para declarar todas las clases de etiquetas que usa la extensión. Se asigna desde el nombre de la clase de la etiqueta a un objeto tag_class.
doc cadena o None; el valor predeterminado es None
Es una descripción de la extensión del módulo que pueden extraer las herramientas de generación de documentación.
environ sequence de strings; el valor predeterminado es []
Proporciona una lista de variables de entorno de las que depende esta extensión del módulo. Si cambia una variable de entorno en esa lista, se volverá a evaluar la extensión.
os_dependent bool; el valor predeterminado es False
Indica si esta extensión depende del SO o no
arch_dependent bool; el valor predeterminado es False
Indica si esta extensión depende de la arquitectura o no

proveedor

unknown provider(doc=None, *, fields=None, init=None)

Define un símbolo de proveedor. El resultado de esta función se debe almacenar en un valor global. Se puede crear una instancia del proveedor llamándolo o usándolo directamente como clave para recuperar una instancia de ese proveedor de un destino. Ejemplo:
MyInfo = provider()
...
def _my_library_impl(ctx):
    ...
    my_info = MyInfo(x = 2, y = 3)
    # my_info.x == 2
    # my_info.y == 3
    ...

Consulta Reglas (proveedores) para obtener una guía completa sobre cómo usar los proveedores.

Devuelve un valor invocable Provider si no se especifica init.

Si se especifica init, devuelve una tupla de 2 elementos: un valor invocable Provider y un valor invocable constructor sin procesar. Consulta Rules (Custom initialization of custom providers) y el análisis del parámetro init a continuación para obtener más detalles.

Parámetros

Parámetro Descripción
doc string o None; El valor predeterminado es None
Es una descripción del proveedor que pueden extraer las herramientas de generación de documentación.
fields sequence de strings, dict o None; el valor predeterminado es None
Si se especifica, restringe el conjunto de campos permitidos.
Los valores posibles son los siguientes:
  • Lista de campos:
    provider(fields = ['a', 'b'])

  • Nombre del campo del diccionario -> documentación:
    provider(
       fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })
Todos los campos son opcionales.
init callable; o None; el valor predeterminado es None
Es una devolución de llamada opcional para el procesamiento previo y la validación de los valores de los campos del proveedor durante la creación de instancias. Si se especifica init, provider() devuelve una tupla de 2 elementos: el símbolo del proveedor normal y un constructor sin procesar.

A continuación, se incluye una descripción precisa. Consulta Reglas (inicialización personalizada de proveedores) para obtener una explicación intuitiva y casos de uso.

Sea P el símbolo del proveedor creado llamando a provider(). Conceptualmente, se genera una instancia de P llamando a una función de constructor predeterminada c(*args, **kwargs), que hace lo siguiente:

  • Si args no está vacío, se produce un error.
  • Si se especificó el parámetro fields cuando se llamó a provider() y si kwargs contiene alguna clave que no se incluyó en fields, se produce un error.
  • De lo contrario, c devuelve una instancia nueva que tiene, para cada entrada k: v en kwargs, un campo llamado k con el valor v.
En el caso en que no se proporciona una devolución de llamada init, una llamada al símbolo P en sí actúa como una llamada a la función del constructor predeterminado c; en otras palabras, P(*args, **kwargs) devuelve c(*args, **kwargs). Por ejemplo:
MyInfo = provider()
m = MyInfo(foo = 1)
hará que m sea una instancia de MyInfo con m.foo == 1.

Sin embargo, en el caso en que se especifique init, la llamada P(*args, **kwargs) realizará los siguientes pasos:

  1. Se invoca la devolución de llamada como init(*args, **kwargs), es decir, con los mismos argumentos posicionales y de palabras clave que se pasaron a P.
  2. Se espera que el valor de retorno de init sea un diccionario, d, cuyas claves sean cadenas de nombres de campos. De lo contrario, se produce un error.
  3. Se genera una instancia nueva de P como si se llamara al constructor predeterminado con las entradas de d como argumentos de palabras clave, como en c(**d).

Nota: Los pasos anteriores implican que se produce un error si *args o **kwargs no coinciden con la firma de init, o si falla la evaluación del cuerpo de init (quizás de forma intencional a través de una llamada a fail()), o si el valor de devolución de init no es un diccionario con el esquema esperado.

De esta manera, la devolución de llamada init generaliza la construcción normal del proveedor, ya que permite argumentos posicionales y lógica arbitraria para el procesamiento previo y la validación. No permite eludir la lista de fields permitidos.

Cuando se especifica init, el valor que devuelve provider() se convierte en una tupla (P, r), en la que r es el constructor sin procesar. De hecho, el comportamiento de r es exactamente el de la función del constructor predeterminado c que se analizó anteriormente. Por lo general, r se vincula a una variable cuyo nombre tiene un guion bajo como prefijo, de modo que solo el archivo .bzl actual tenga acceso directo a ella:

MyInfo, _new_myinfo = provider(init = ...)

repository_rule

callable repository_rule(implementation, *, attrs=None, local=False, environ=[], configure=False, remotable=False, doc=None)

Crea una regla de repositorio nueva. Almacénalo en un valor global para que se pueda cargar y llamar desde una función de implementación de module_extension(), o bien para que lo use use_repo_rule().

Parámetros

Parámetro Descripción
implementation callable; required
la función que implementa esta regla. Debe tener un solo parámetro, repository_ctx. Se llama a la función durante la fase de carga para cada instancia de la regla.
attrs dict o None; valor predeterminado es None
Diccionario para declarar todos los atributos de la regla del repositorio. Se asigna desde un nombre de atributo a un objeto de atributo (consulta el módulo attr). Los atributos que comienzan con _ son privados y se pueden usar para agregar una dependencia implícita de una etiqueta a un archivo (una regla del repositorio no puede depender de un artefacto generado). El atributo name se agrega de forma implícita y no se debe especificar.

Los atributos declarados convertirán None al valor predeterminado.
local bool; el valor predeterminado es False
Indica que esta regla recupera todo del sistema local y se debe volver a evaluar en cada recuperación.
environ sequence de strings; el valor predeterminado es []
Obsoleto. Este parámetro ya no está disponible. Migra a repository_ctx.getenv en su lugar.
Proporciona una lista de las variables de entorno de las que depende esta regla del repositorio. Si cambia una variable de entorno en esa lista, se volverá a recuperar el repositorio.
configure bool; el valor predeterminado es False
Indica que el repositorio inspecciona el sistema con fines de configuración.
remotable bool; El valor predeterminado es False
Experimental. Este parámetro es experimental y puede cambiar en cualquier momento. No dependas de él. Se puede habilitar de forma experimental configurando --experimental_repo_remote_exec
Compatible con la ejecución remota
doc cadena o None; el valor predeterminado es None
Es una descripción de la regla del repositorio que pueden extraer las herramientas de generación de documentación.

regla

callable rule(implementation, *, test=unbound, attrs={}, outputs=None, executable=unbound, output_to_genfiles=False, fragments=[], host_fragments=[], _skylark_testable=False, toolchains=[], incompatible_use_toolchain_transition=False, doc=None, provides=[], dependency_resolution_rule=False, exec_compatible_with=[], analysis_test=False, build_setting=None, cfg=None, exec_groups=None, initializer=None, parent=None, extendable=None, subrules=[])

Crea una regla nueva, a la que se puede llamar desde un archivo BUILD o una macro para crear destinos.

Las reglas se deben asignar a variables globales en un archivo .bzl. El nombre de la variable global es el nombre de la regla.

Las reglas de prueba deben tener un nombre que termine en _test, mientras que todas las demás reglas no deben tener este sufijo. (Esta restricción solo se aplica a las reglas, no a sus destinos).

Parámetros

Parámetro Descripción
implementation function; obligatorio
La función de Starlark que implementa esta regla debe tener exactamente un parámetro: ctx. Se llama a la función durante la fase de análisis para cada instancia de la regla. Puede acceder a los atributos que proporciona el usuario. Debe crear acciones para generar todos los resultados declarados.
test bool; el valor predeterminado es unbound
Indica si esta regla es una regla de prueba, es decir, si puede ser objeto de un comando blaze test. Todas las reglas de prueba se consideran automáticamente ejecutables. No es necesario (y se desaconseja) establecer executable = True de forma explícita para una regla de prueba. El valor predeterminado es False. Consulta la página de reglas para obtener más información.
attrs dict; el valor predeterminado es {}
Es un diccionario para declarar todos los atributos de la regla. Se asigna desde un nombre de atributo a un objeto de atributo (consulta el módulo attr). Los atributos que comienzan con _ son privados y se pueden usar para agregar una dependencia implícita en una etiqueta. El atributo name se agrega de forma implícita y no se debe especificar. Los atributos visibility, deprecation, tags, testonly y features se agregan de forma implícita y no se pueden anular. La mayoría de las reglas solo necesitan unos pocos atributos. Para limitar el uso de memoria, hay un límite en la cantidad de atributos que se pueden declarar.

Los atributos declarados convertirán None al valor predeterminado.
outputs dict, None o function; el valor predeterminado es None
Obsoleto. Este parámetro está obsoleto y se quitará pronto. No dependas de él. Está inhabilitado con --incompatible_no_rule_outputs_param. Usa esta marca para verificar que tu código sea compatible con su eliminación inminente.
Este parámetro dejó de estar disponible. Migra las reglas para que usen OutputGroupInfo o attr.output en su lugar.

Es un esquema para definir salidas predeclaradas. A diferencia de los atributos output y output_list, el usuario no especifica las etiquetas de estos archivos. Consulta la página Reglas para obtener más información sobre los resultados predeclarados.

El valor de este argumento es un diccionario o una función de devolución de llamada que produce un diccionario. La devolución de llamada funciona de manera similar a los atributos de dependencia calculados: los nombres de los parámetros de la función se comparan con los atributos de la regla, por lo que, por ejemplo, si pasas outputs = _my_func con la definición def _my_func(srcs, deps): ..., la función tiene acceso a los atributos srcs y deps. Ya sea que el diccionario se especifique directamente o a través de una función, se interpreta de la siguiente manera.

Cada entrada del diccionario crea un resultado predeclarado en el que la clave es un identificador y el valor es una plantilla de cadena que determina la etiqueta del resultado. En la función de implementación de la regla, el identificador se convierte en el nombre del campo que se usa para acceder al File del resultado en ctx.outputs. La etiqueta del resultado tiene el mismo paquete que la regla, y la parte posterior al paquete se produce sustituyendo cada marcador de posición de la forma "%{ATTR}" por una cadena formada a partir del valor del atributo ATTR:

  • Los atributos de tipo cadena se sustituyen de forma literal.
  • Los atributos con tipo de etiqueta se convierten en parte de la etiqueta después del paquete, sin la extensión de archivo. Por ejemplo, la etiqueta "//pkg:a/b.c" se convierte en "a/b".
  • Los atributos con tipo de salida se convierten en parte de la etiqueta después del paquete, incluida la extensión del archivo (para el ejemplo anterior, "a/b.c").
  • Todos los atributos con tipo de lista (por ejemplo, attr.label_list) que se usan en marcadores de posición deben tener exactamente un elemento. Su conversión es la misma que la de la versión que no es de lista (attr.label).
  • Es posible que otros tipos de atributos no aparezcan en los marcadores de posición.
  • Los marcadores de posición especiales sin atributos %{dirname} y %{basename} se expanden a esas partes de la etiqueta de la regla, sin incluir su paquete. Por ejemplo, en "//pkg:a/b.c", dirname es a y basename es b.c.

En la práctica, el marcador de posición de sustitución más común es "%{name}". Por ejemplo, para un destino llamado "foo", el diccionario de salidas {"bin": "%{name}.exe"} predeclara una salida llamada foo.exe a la que se puede acceder en la función de implementación como ctx.outputs.bin.

executable bool; el valor predeterminado es unbound
Indica si esta regla se considera ejecutable, es decir, si puede ser el sujeto de un comando blaze run. El valor predeterminado es False. Consulta la página de reglas para obtener más información.
output_to_genfiles bool; El valor predeterminado es False
Si es verdadero, los archivos se generarán en el directorio genfiles en lugar del directorio bin. No establezcas esta marca, a menos que la necesites para la compatibilidad con reglas existentes (p.ej., cuando generes archivos de encabezado para C++).
fragments sequence de strings; el valor predeterminado es []
Lista de nombres de fragmentos de configuración que la regla requiere en la configuración de destino.
host_fragments sequence de strings; el valor predeterminado es []
Lista de nombres de fragmentos de configuración que la regla requiere en la configuración del host.
_skylark_testable bool; el valor predeterminado es False
(Experimental)

Si es verdadero, esta regla expondrá sus acciones para que las inspeccionen las reglas que dependen de ella a través de un proveedor de Actions. El proveedor también está disponible para la regla llamando a ctx.created_actions().

Esto solo se debe usar para probar el comportamiento en el tiempo de análisis de las reglas de Starlark. Es posible que esta marca se quite en el futuro.
toolchains sequence; el valor predeterminado es []
Si se configura, es el conjunto de cadenas de herramientas que requiere esta regla. La lista puede contener objetos String, Label o StarlarkToolchainTypeApi, en cualquier combinación. Las cadenas de herramientas se encontrarán verificando la plataforma actual y se proporcionarán a la implementación de la regla a través de ctx.toolchain.
incompatible_use_toolchain_transition bool; el valor predeterminado es False
Obsoleto. Ya no se usa y se debe quitar.
doc cadena o None; el valor predeterminado es None
Es una descripción de la regla que pueden extraer las herramientas de generación de documentación.
provides sequence; El valor predeterminado es []
Es una lista de proveedores que debe devolver la función de implementación.

Es un error si la función de implementación omite cualquiera de los tipos de proveedores que se enumeran aquí de su valor de devolución. Sin embargo, la función de implementación puede devolver proveedores adicionales que no se mencionan aquí.

Cada elemento de la lista es un objeto *Info que devuelve provider(), excepto que un proveedor heredado se representa con su nombre de cadena.Cuando un destino de la regla se usa como dependencia de un destino que declara un proveedor obligatorio, no es necesario especificar ese proveedor aquí. Es suficiente con que la función de implementación lo devuelva. Sin embargo, se considera una práctica recomendada especificarlo, aunque no sea obligatorio. Sin embargo, el campo required_providers de un aspecto requiere que los proveedores se especifiquen aquí.

dependency_resolution_rule bool; el valor predeterminado es False
Si se configura, la regla puede ser una dependencia a través de atributos también marcados como disponibles en los materializadores. Todos los atributos de las reglas con este parámetro de configuración deben marcarse como disponibles en los materializadores también. Esto se debe a que las reglas marcadas de esta manera no pueden depender de reglas que no estén marcadas de esta manera.
exec_compatible_with sequence de strings; el valor predeterminado es []
Es una lista de restricciones en la plataforma de ejecución que se aplican a todos los destinos de este tipo de regla.
analysis_test bool; el valor predeterminado es False
Si es verdadero, esta regla se trata como una prueba de análisis.

Nota: Las reglas de prueba de análisis se definen principalmente con la infraestructura que proporcionan las bibliotecas principales de Starlark. Consulta Pruebas para obtener orientación.

Si una regla se define como regla de prueba de análisis, se le permite usar transiciones de configuración definidas con analysis_test_transition en sus atributos, pero acepta algunas restricciones:

  • Los destinos de esta regla están limitados en la cantidad de dependencias transitivas que pueden tener.
  • La regla se considera una regla de prueba (como si se hubiera establecido test=True). Este parámetro anula el valor de test.
  • Es posible que la función de implementación de la regla no registre acciones. En cambio, debe registrar un resultado de aprobación o rechazo proporcionando AnalysisTestResultInfo.
build_setting BuildSetting o None; el valor predeterminado es None
Si se configura, describe qué tipo de build setting es esta regla. Consulta el módulo config. Si se configura, se agregará automáticamente a esta regla un atributo obligatorio llamado "build_setting_default", con un tipo que corresponda al valor que se pasó aquí.
cfg El valor predeterminado es None
. Si se configura, apunta a la transición de configuración que la regla aplicará a su propia configuración antes del análisis.
exec_groups dict o None; el valor predeterminado es None
Es un diccionario del nombre del grupo de ejecución (cadena) para exec_groups. Si se configura, permite que las reglas ejecuten acciones en varias plataformas de ejecución dentro de un solo destino. Consulta la documentación sobre grupos de ejecución para obtener más información.
initializer El valor predeterminado es None
. Experimental: Es la función de Stalark que inicializa los atributos de la regla.

Se llama a la función en el momento de la carga para cada instancia de la regla. Se llama con name y los valores de los atributos públicos definidos por la regla (no con atributos genéricos, por ejemplo, tags).

Debe devolver un diccionario desde los nombres de los atributos hasta los valores deseados. Los atributos que no se devuelven no se ven afectados. Si se devuelve None como valor, se usará el valor predeterminado especificado en la definición del atributo.

Los inicializadores se evalúan antes de los valores predeterminados especificados en una definición de atributo. Por lo tanto, si un parámetro en la firma del inicializador contiene valores predeterminados, estos anulan los valores predeterminados de la definición del atributo (excepto si se devuelve None).

Del mismo modo, si un parámetro en la firma del inicializador no tiene un valor predeterminado, el parámetro se volverá obligatorio. En esos casos, se recomienda omitir la configuración predeterminada o obligatoria en la definición de un atributo.

Es una buena práctica usar **kwargs para los atributos que no se controlan.

En el caso de las reglas extendidas, se llama a todos los inicializadores, comenzando por el elemento secundario y continuando con los elementos principales. Cada inicializador solo recibe los atributos públicos que conoce.

parent El valor predeterminado es None
. Experimental: Es la regla de Stalark que se extiende. Cuando se configura, se combinan los atributos públicos y los proveedores anunciados. La regla coincide con executable y test del elemento principal. Se combinan los valores de fragments, toolchains, exec_compatible_with y exec_groups. No se pueden establecer parámetros heredados ni obsoletos. La transición de configuración entrante cfg del elemento superior se aplica después de la configuración entrante de esta regla.
extendable bool, Label, string o None; el valor predeterminado es None
Experimental: Es una etiqueta de una lista de entidades permitidas que define qué reglas pueden extender esta regla. También se puede establecer en verdadero o falso para permitir o no la extensión. De forma predeterminada, Bazel siempre permite las extensiones.
subrules Secuencia de Subrules; el valor predeterminado es []
Experimental: Es la lista de subreglas que usa esta regla.

seleccionar

unknown select(x, no_match_error='')

select() es la función auxiliar que hace que un atributo de regla sea configurable. Consulta la enciclopedia de compilaciones para obtener más información.

Parámetros

Parámetro Descripción
x dict; required
Es un diccionario que asigna condiciones de configuración a valores. Cada clave es una Label o una cadena de etiqueta que identifica una instancia de config_setting o constraint_value. Consulta la documentación sobre macros para saber cuándo usar una etiqueta en lugar de una cadena.
no_match_error string; El valor predeterminado es ''
Es un error personalizado opcional que se informa si no coincide ninguna condición.

subregla

Subrule subrule(implementation, attrs={}, toolchains=[], fragments=[], subrules=[])

Construye una instancia nueva de una subregla. El resultado de esta función se debe almacenar en una variable global antes de que se pueda usar.

Parámetros

Parámetro Descripción
implementation function; required
La función de Starlark que implementa esta subregla
attrs dict; el valor predeterminado es {}
Es un diccionario para declarar todos los atributos (privados) de la regla secundaria.

Las subreglas solo pueden tener atributos privados que sean de tipo etiqueta (es decir, etiqueta o lista de etiquetas). Bazel pasa automáticamente los valores resueltos correspondientes a estas etiquetas a la función de implementación de la subregla como argumentos con nombre (por lo tanto, se requiere que la función de implementación acepte parámetros con nombre que coincidan con los nombres de los atributos). Los tipos de estos valores serán los siguientes:

  • FilesToRunProvider para atributos de etiqueta con executable=True
  • File para atributos de etiqueta con allow_single_file=True
  • Target para todos los demás atributos de la etiqueta
  • [Target] para todos los atributos de lista de etiquetas
toolchains sequence; el valor predeterminado es []
Si se configura, es el conjunto de cadenas de herramientas que requiere esta regla secundaria. La lista puede contener objetos String, Label o StarlarkToolchainTypeApi, en cualquier combinación. Las cadenas de herramientas se encontrarán verificando la plataforma actual y se proporcionarán a la implementación de la regla secundaria a través de ctx.toolchains. Ten en cuenta que los AEG deben estar habilitados en las reglas de consumo si se establece este parámetro. Si aún no migraste a los AEG, consulta https://bazel.build/extending/auto-exec-groups#migration-aegs.
fragments sequence de strings; el valor predeterminado es []
Lista de nombres de fragmentos de configuración que la subregla requiere en la configuración de destino.
subrules sequence de Subrules; el valor predeterminado es []
Lista de otras subreglas que necesita esta subregla.

tag_class

tag_class tag_class(attrs={}, *, doc=None)

Crea un objeto tag_class nuevo, que define un esquema de atributos para una clase de etiquetas, que son objetos de datos que puede usar una extensión de módulo.

Parámetros

Parámetro Descripción
attrs dict; El valor predeterminado es {}
Diccionario para declarar todos los atributos de esta clase de etiqueta. Se asigna desde un nombre de atributo a un objeto de atributo (consulta el módulo attr).

Ten en cuenta que, a diferencia de rule(), aspect() y repository_rule(), los atributos declarados no convertirán None al valor predeterminado. Para que se use el valor predeterminado, el llamador debe omitir el atributo por completo.
doc string o None; El valor predeterminado es None
Es una descripción de la clase de etiquetas que pueden extraer las herramientas de generación de documentación.

visibilidad

None visibility(value)

Establece la visibilidad de carga del módulo .bzl que se está inicializando.

La visibilidad de carga de un módulo rige si otros archivos BUILD y .bzl pueden cargarlo. (Esto es distinto de la visibilidad del destino del archivo fuente .bzl subyacente, que rige si el archivo puede aparecer como una dependencia de otros destinos). La visibilidad de carga funciona a nivel de paquetes: Para cargar un módulo, el archivo que realiza la carga debe residir en un paquete al que se le haya otorgado visibilidad del módulo. Un módulo siempre se puede cargar dentro de su propio paquete, independientemente de su visibilidad.

visibility() solo se puede llamar una vez por archivo .bzl y solo en el nivel superior, no dentro de una función. El estilo preferido es colocar esta llamada inmediatamente debajo de las instrucciones load() y cualquier lógica breve necesaria para determinar el argumento.

Si la marca --check_bzl_visibility se establece como falsa, los incumplimientos de visibilidad de carga emitirán advertencias, pero no fallará la compilación.

Parámetros

Parámetro Descripción
value obligatorio
Lista de cadenas de especificación de paquetes o una sola cadena de especificación de paquetes.

Las especificaciones de paquetes siguen el mismo formato que para package_group, excepto que no se permiten especificaciones de paquetes negativas. Es decir, una especificación puede tener las siguientes formas:

  • "//foo": El paquete //foo
  • "//foo/...": El paquete //foo y todos sus subpaquetes.
  • "public" o "private": Todos los paquetes o ninguno, respectivamente

No se permite la sintaxis "@"; todas las especificaciones se interpretan en relación con el repositorio del módulo actual.

Si value es una lista de cadenas, el conjunto de paquetes a los que se otorga visibilidad para este módulo es la unión de los paquetes representados por cada especificación. (Una lista vacía tiene el mismo efecto que private). Si value es una sola cadena, se trata como si fuera la lista singleton [value].

Ten en cuenta que las marcas --incompatible_package_group_has_public_syntax y --incompatible_fix_package_group_reporoot_syntax no tienen efecto en este argumento. Los valores "public" y "private" siempre están disponibles, y "//..." siempre se interpreta como "todos los paquetes del repositorio actual".