Archivos .bzl

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.

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.

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.

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í.

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.

• 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.

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.

MyInfo = provider()
m = MyInfo(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 = ...)

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.

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í.

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.

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.

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

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".