Archivos .bzl

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

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

Los atributos declarados convertirán None al valor predeterminado.

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

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

Una lista de proveedores no anidada se convertirá automáticamente en una lista que contiene una lista de proveedores. Es decir, [FooInfo, BarInfo] se convertirá automáticamente a [[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 BazInfo y QuxInfo.

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

Cada elemento de la lista es un objeto *Info que devuelve provider(), excepto que un proveedor heredado está representado por su nombre de cadena.Cuando un objetivo de la regla se usa como dependencia para un objetivo que declara un proveedor obligatorio, no es necesario especificar ese proveedor aquí. Es suficiente que la función de implementación la 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 se especifiquen los proveedores aquí.

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

Es falso de forma predeterminada.

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 "en bloque" que se pasarán al destino "principal" sin cambios se pasan como **kwargs.

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

El nombre de cualquier macro simbólica interna o de destino declarada por una macro simbólica (incluida cualquier función de Starlark a la que la función de implementación de la macro llame de forma transitiva) debe ser igual a name (se conoce como el objetivo "principal") o comenzar con name, seguido de un carácter separador ("_", "-" o ".") y un sufijo de cadena. (Se pueden declarar objetivos que infrinjan 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 (incluida cualquier función de Starlark a la que la función de implementación de la macro llame de forma transitiva) solo son visibles en el paquete que contiene el archivo .bzl que define la macro. Para declarar destinos visibles de forma externa, incluidos los del llamador de la macro simbólica, la función de implementación debe establecer visibility de forma adecuada, por lo general, pasando visibility = visibility a la regla o al símbolo de macro al que se llama.

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

• package(), licenses()
• environment_group()
• native.glob(). En su lugar, puedes pasar una glob a la macro a través de un atributo de lista de etiquetas.
• native.subpackages()
• (solo se permite en los finalizadores de reglas, consulta finalizer a continuación) native.existing_rules(), native.existing_rule()
• (para subprocesos WORKSPACE) workspace(), register_toolchains(), register_execution_platforms(), bind(), creación de instancias de reglas de repositorio

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

Los atributos cuyos nombres comienzan con _ son privados y 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, existe un límite en la cantidad de atributos que se pueden declarar.

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 que se muestra de rule() o macro() no se asignó a una variable global en un archivo .bzl, ese valor no se registró como una regla o un símbolo de 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 se puede establecer una entrada 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 eficaz en el diccionario attrs.

Cuando se hereda un atributo no obligatorio, se anula el valor predeterminado del atributo para que sea None, independientemente de lo que se especifique 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 ajustada, como pasar el **kwargs sin modificar, un valor que no estaba presente 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 trata de la misma manera que omitir el atributo). Esto es importante porque omitir un atributo tiene una semántica sutilmente diferente 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 definición nueva). También se encarga de verificar el valor None predeterminado 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 establece 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 que no se anularon sin cambios a la regla "principal" o al símbolo de macro que une la macro. 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 objetivos "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.

A diferencia de las macros simbólicas ordinarias, 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 objetivos definidos por ningún finalizador de reglas, incluido este.

• lista de campos:
  

  provider(fields = ['a', 'b'])

• nombre del campo del diccionario -> documentación:
  

  provider(
         fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })

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.

Supongamos que P es el símbolo del proveedor creado con una llamada 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 muestra una instancia nueva que tiene, para cada entrada k: v en kwargs, un campo llamado k con el valor v.

MyInfo = provider()
m = MyInfo(foo = 1)

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

1. La devolución de llamada se invoca 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 que se muestra de init sea un diccionario, d, cuyas claves son cadenas de nombres de campo. 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 (tal vez de forma intencional a través de una llamada a fail()), o si el valor que se muestra 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 permitidas.

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

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

Los atributos declarados convertirán None al valor predeterminado.

Los atributos declarados convertirán None al valor predeterminado.

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

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 coinciden 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 declarado previamente 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 a File del resultado en ctx.outputs. La etiqueta del resultado tiene el mismo paquete que la regla, y la parte posterior del paquete se produce sustituyendo cada marcador de posición del formulario "%{ATTR}" por una cadena formada a partir del valor del atributo ATTR:

• Los atributos de tipo cadena se sustituyen literalmente.
• Los atributos de tipo de etiqueta se convierten en la parte de la etiqueta después del paquete, menos la extensión del archivo. Por ejemplo, la etiqueta "//pkg:a/b.c" se convierte en "a/b".
• Los atributos de tipo de salida se convierten en la parte de la etiqueta después del paquete, incluida la extensión del archivo (en el ejemplo anterior, "a/b.c").
• Todos los atributos de tipo lista (por ejemplo, attr.label_list) que se usan en los marcadores de posición deben tener exactamente un elemento. Su conversión es la misma que su versión no 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 que no son de 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 resultados {"bin": "%{name}.exe"} declara previamente un resultado llamado foo.exe al que se puede acceder en la función de implementación como ctx.outputs.bin.

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

Cada elemento de la lista es un objeto *Info que devuelve provider(), excepto que un proveedor heredado está representado por su nombre de cadena.Cuando un objetivo de la regla se usa como dependencia para un objetivo que declara un proveedor obligatorio, no es necesario especificar ese proveedor aquí. Es suficiente que la función de implementación la 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 se especifiquen los proveedores aquí.

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

Si una regla se define como una regla de prueba de análisis, se permite usar transiciones de configuración definidas con analysis_test_transition en sus atributos, pero se habilitan 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). Esta acción reemplaza el valor de test.
• Es posible que la función de implementación de reglas no registre acciones. En su lugar, debe registrar un resultado de aprobado o reprobado a través de AnalysisTestResultInfo.

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

Debe mostrar un diccionario de los nombres de los atributos a los valores deseados. Los atributos que no se muestran no se ven afectados. Si devuelves None como valor, se usará el valor predeterminado especificado en la definición del atributo.

Los inicializadores se evalúan antes que los valores predeterminados especificados en una definición de atributo. En consecuencia, si un parámetro en la firma del inicializador contiene valores predeterminados, reemplaza el valor predeterminado de la definición del atributo (excepto si muestra None).

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

Se recomienda usar **kwargs para los atributos que no se controlan.

En el caso de las reglas extendidas, se llama a todos los inicializadores desde los secundarios hasta los superiores. A cada inicializador se le pasan solo los atributos públicos que conoce.

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, la función de implementación debe aceptar 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 etiqueta
• [Target] para todos los atributos de lista de etiquetas

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.

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 los siguientes formatos:

• "//foo": El paquete //foo
• "//foo/...": Es el paquete //foo y todos sus subpaquetes.
• "public" o "private": Todos los paquetes o ningún paquete, 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 que le otorga visibilidad a 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".