Pautas de empaquetado de Rust

Similarmente a otro ecosistema del lenguaje en Fedora, hay un conjunto estándar de indicadores de compilador que DEBE ser pasado al compilador de Rust.

Los valores predeterminados de Rust se definen en la macro %build_rustflags del paquete rust-srpm-macros. Forma parte del directorio raíz de compilación predeterminado en Fedora 39+, donde la macro %set_build_flags auto-establece la variable de entorno $RUSTFLAGS en función de esta macro.

Para compatibilidad con versiones anteriores o EPEL, esta variable de entorno se puede configurar manualmente al inicio de %build y %check en los archivos de especificaciones del paquete:

Esto no es necesario para paquetes que utilizan las macros %cargo_prep, %cargo_build, y %cargo_test, las cuales configuran cargo para utilizar directamente el %build_rustflags por defecto.

Las macros RPM que proporcionan funcionalidad básica para compilar código Rust están incluidas en rust-rpm-macros, la cual es parte de la raíz de construcción por defecto, como es una dependencia de redhat-rpm-config. Cuando compile para ELN o EPEL8, esto no es el caso, y los paquetes necesitan utilizar BuildRequires: rust-toolset.

Los paquetes que compilan código Rust con cargo, directa o indirectamente, o que invocan cualquiera de las macros %cargo_*, DEBEN agregar BuildRequires: cargo-rpm-macros, lo cual proporciona las implementaciones de todas las macros %cargo_*. Este paquete no forma parte del buildroot predeterminado, ya que incorpora dependencias adicionales (p.ej., un intérprete de Python).

Dado que el control de versiones semántico ("SemVer") es el único esquema de control de versiones compatible con los paquetes Rust, las dependencias de las bibliotecas Rust se especifican casi exclusivamente como "esta versión o cualquier versión más nueva que sea compatible con la API con ella", es decir, un rango de versiones compatibles.

Estos intervalos de versiones compatibles deben traducirse correctamente en dependencias de RPM; de lo contrario, es posible que se incluya una versión incorrecta de una dependencia para las compilaciones, lo que provocaría mensajes de error inútiles sobre dependencias ausentes.

Ya que las dependencias de los proyectos Rust cambian con frecuencia, los paquetes para proyectos que compilan código Rust con cargo DEBEN usar BuildRequires generados dinámicamente invocando a la macro %cargo_generate_buildrequires en el scriptlet %generate_buildrequires.

Por ejemplo, una dependencia en serde = "1.0.100" especificada en los metadatos Cargo.toml de un proyecto (una dependencia en el paquete nombrado “serde”, con la versión "1.0.100" o cualquier versión compatible con API con "1.0.100", con funciones predeterminadas habilitadas) haría que se genere una dependencia como esta para RPM:

Refiérete a la sección sobre macros de RPM para saber como pasar indicadores de características a esta macro.

Al igual que otros lenguajes que producen binarios enlazados estáticamente, los ejecutables de Rust (y bibliotecas compartidas) contienen código que se origina en otros paquetes (es decir, paquetes para otras cajas de Rust), que a su vez están cubiertos por diferentes términos de licencia.

Esto debe tenerse en cuenta manteniendo una etiqueta Licencia independiente para el subpaquete que contiene estos binarios. Puede encontrar más información sobre las etiquetas Licencia en Documentos legales de Fedora.

El paquete cargo-rpm-macros proporciona dos macros RPM que ayudan con rellenar la etiqueta License correctamente para proyectos que sean compilados con cargo:

Esta macro determina e imprime un resumen de todas las licencias de los crates de Rust que se enlazan estáticamente en los binarios finales (excluyendo correctamente las dependencias de solo compilación o de solo prueba). Este resumen puede copiarse del registro de compilación al archivo de especificaciones como comentario. El contenido real de la etiqueta License puede obtenerse mediante la construcción de una conjunción de estas licencias individuales (con los operadores AND de SPDX).

Esta macro determina e imprime un desglose completo de todos los crates de Rust que terminan enlazados estáticamente a los binarios finales (según la misma lógica que en la macro %cargo_license_summary), sus versiones y sus expresiones de licencia individuales. Generar esta lista dinámicamente durante la compilación garantiza que su contenido siempre coincida con las dependencias reales.

Ambas macros aceptan los mismos argumentos que otras macros %cargo_* (-a, -n, -f), y para que su salida coincida con los binarios reales, DEBEN pasarseles a ellas y a %cargo_build los mismos indicadores.

En general, los paquetes NO UTILIZARÍAN dependencias de cajas incluidas, siempre que sea posible.

Siempre que se utilicen dependencias de caja (independientemente del mecanismo utilizado), todas las dependencias de caja DEBEN declararse con Provides virtuales con el formato Provides: bundled(crate($crate)) = $version en el subpaquete que contiene el componente de Rust. Por ejemplo, estos Provides virtuales se utilizan para determinar el impacto de las vulnerabilidades de seguridad en los paquetes que utilizan dependencias de caja.

También hay dos situaciones en las que agrupar al menos algunas cajas de Rust suele ser inevitable:

La forma recomendada de escribir archivos de especificaciones para los paquetes Rust es usar rust2rpm y aplicar cualquier modificación necesaria sobre el archivo de especificaciones generado.

Hay algunas situaciones comunes en las que los archivos de especificaciones generados automáticamente necesitan cambios manuales:

Las cajas que proporcionan enlaces de Rust para bibliotecas de C generalmente requieren algunos cambios adicionales (si es posible):

Tenga en cuenta que la aplicación de parches a los archivos Cargo.toml (especialmente el cambio del conjunto de dependencias y características opcionales) DEBE realizarse ejecutando rust2rpm -p, ya que cambios como estos afectan la generación del archivo de especificaciones (es decir, la lista de subpaquetes generados), que solo se tiene en cuenta correctamente si el parche se crea antes de la generación del archivo de especificaciones.

Se recomienda rastrear los archivos de configuración rust2rpm.toml que no estén vacíos en el repositorio de paquetes junto con el archivo .spec generado.

Los paquetes para las cajas de Rust de crates.io DEBEN usar rust-$crate como el nombre del paquete fuente (donde $crate es el nombre del proyecto en crates.io).

Esto garantiza que no haya colisiones de nombres entre los paquetes de Rust publicados en crates.io y los paquetes de Rust empaquetados para Fedora.

Al generar un paquete para una caja de Rust que contiene destinos ejecutables, la convención que sigue rust2rpm es generar un subpaquete con un nombre que coincida con el nombre de la caja (es decir, el paquete fuente rust-$crate tendrá un subpaquete $crate). Si es necesario, este subpaquete se puede renombrar, por ejemplo, si el nombre no cumple con las expectativas o si entra en conflicto con otro paquete ya existente.

Los proyectos creados con cargo o publicados en crates.io siguen el control de versiones semántico (con pequeños ajustes específicos de cargo). Dado que las cadenas SemVer pueden contener caracteres no válidos en las cadenas de versión RPM, DEBEN traducirse para que sean compatibles con RPM.

Por ejemplo, las versiones preliminares se indican con el sufijo -<pre> en SemVer, pero el carácter - no es válido en las versiones RPM. Esto se puede solucionar reemplazando - por el carácter ~, que indica versiones preliminares en las cadenas de versiones RPM. Esta traducción se realiza automáticamente para la etiqueta Version al generar un archivo de especificaciones con rust2rpm, y la versión original se almacena en una macro independiente que puede usarse para referirse a la cadena de versión original.

Además, algunas cajas de Rust incluyen metadatos de compilación adicionales en sus versiones (un sufijo <build>`). Este formato se usa principalmente para incluir información sobre la versión de una biblioteca C incluida. Este sufijo `<build> DEBE eliminarse de los metadatos de la caja con un parche, ya que puede interferir con la resolución de dependencias/versiones de RPM. Esto ocurre automáticamente al usar rust2rpm versión 25 o posterior.

La fuente canónica de los crates de Rust es crates.io. Los proyectos de crates.io DEBEN empaquetarse desde las fuentes que se publican allí (es decir, utilizando la macro %{crates_source}).

Si las fuentes publicadas en crates.io no contienen todos los archivos necesarios para crear el paquete (por ejemplo, si falta el archivo .desktop o las páginas de manual), las fuentes originales pueden usarse como fuente adicional, pero NO DEBEN usarse para compilar el paquete. Se recomienda informar al proyecto original sobre la inclusión de estos archivos adicionales en los paquetes publicados.

Como alternativa, si el proyecto en cuestión no proporciona una interfaz de biblioteca Rust, se puede empaquetar como un enlace: #_non_crate_rust_projects[Proyecto Rust que no es un paquete] utilizando las fuentes ascendentes en su lugar.

La mayoría de las herramientas de soporte para determinar licencias requieren metadatos precisos sobre las licencias en los metadatos de la caja, incluidas las macros %cargo_license* y otras herramientas de terceros como cargo-license y cargo-deny.

Por esta razón, los metadatos de licencia de todos los crates de Rust empaquetados para Fedora DEBEN coincidir con la etiqueta de licencia del propio paquete de Fedora. Cualquier crate que configure package.license-file en sus metadatos (reservado para licencias no estándar/no SPDX) DEBE ser parcheado para que configure package.license en sus metadatos, y DEBE proporcionarse una expresión SPDX precisa en su lugar. Parches como este DEBEN enviarse al servidor original.

Las características/dependencias opcionales de los crates de Rust se traducen en subpaquetes RPM para facilitar la resolución de dependencias de características y dependencias opcionales de los crates. La lista de "características" del crate (incluidas las características definidas implícitamente para dependencias opcionales) DEBE mantenerse sincronizada con la lista de subpaquetes; es decir, para cada característica $foo del crate $crate, debe haber un subpaquete con el nombre rust-$crate+$foo-devel, y viceversa. Esto es necesario para que los generadores RPM de Provides y Requires funcionen correctamente.

Si las características opcionales que no forman parte del conjunto de características predeterminado no se utilizan y requieren dependencias adicionales (posiblemente no disponibles), el paquete PUEDE omitir subpaquetes para estos nombres de características específicos. Sin embargo, es importante asegurarse de que las características correspondientes a los subpaquetes omitidos no sean accesibles a través de subpaquetes que no se han omitido, ya que esto generaría paquetes con dependencias insatisfechas. La deshabilitación de características opcionales a veces no se puede gestionar correctamente simplemente omitiendo subpaquetes para características específicas. En estos casos, los metadatos de la caja en Cargo.toml deben parchearse como corresponde.

Tenga en cuenta que la característica "predeterminada" siempre está definida implícitamente por cargo, incluso si los metadatos del paquete no contienen una tabla [features] o una característica "predeterminada" definida explícitamente, por lo que el subpaquete para la característica "predeterminada" estará presente en todos los paquetes de paquetes de Rust con una interfaz de biblioteca.

El paquete cargo-rpm-macros incluye generadores de RPM para generar automáticamente Provides y Requires para las cajas de Rust que cumplen con las Pautas de empaquetado (es decir, instalan sus archivos en la ubicación correcta, %{crate_instdir}).

Se recomienda verificar que los Provides y Requires generados sean correctos; por ejemplo, los siguientes Provides y Requires deben estar presentes para garantizar dependencias correctas entre subpaquetes:

Además, las dependencias de los paquetes externos de Rust deben ser las esperadas:

En la mayoría de las circunstancias, la última versión de un paquete DEBERÍA estar empaquetada y, si es posible, los empaquetadores DEBERÍAN portar los paquetes para usar la última versión disponible de sus dependencias y enviar estos parches al proyecto original para limitar la divergencia entre el proyecto original y el paquete de Fedora.

Sin embargo, hay dos escenarios comunes en los que a menudo es necesario proporcionar paquetes para múltiples versiones de un paquete de biblioteca simultáneamente:

En estos casos, se puede crear un "paquete de compatibilidad" para la versión anterior (es decir, generalmente la versión actual) y el paquete sin sufijo se puede actualizar a la versión más nueva. rust2rpm admite la creación automática de "paquetes de compatibilidad" con nombres que cumplen con las Pautas de nomenclatura para este caso y compatibles con las restricciones del control de versiones semántico mediante el uso del indicador rust2rpm --compat.

Todos los "paquetes compatibles" para las cajas de Rust DEBEN seguir las pautas para las cajas de Rust, y se aplican dos reglas adicionales al crearlas:

El comportamiento de algunas macros RPM depende de la presencia y el valor de la macro _with_check, es decir, si se utilizan %bcond_without check o %bcond_with check en el archivo de especificaciones; en particular, la macro %cargo_generate_buildrequires solo incluye dev-dependencies (es decir, dependencias que solo se utilizan para compilar y/o ejecutar el conjunto de pruebas de un proyecto con cargo) si el bcond check está habilitado.

Además, los paquetes para cajas Rust generados por rust2rpm usan el valor de esta macro para determinar si se ejecuta el scriptlet %check.

Los paquetes para cajas Rust DEBEN establecer este bcond para evitar un comportamiento inesperado de las macros %cargo_*, ya sea habilitando o deshabilitando explícitamente las pruebas.

Las cajas de Rust pueden tener tres tipos diferentes de pruebas en sus conjuntos de pruebas:

By default, running cargo test (i.e. by calling the %cargo_test macro), all three kinds of tests are run. They can also be invoked separately (for example, because parts of the test suite or large data files are not included in published sources) by passing through filtering arguments to the underlying cargo test command:

This can be combined with additional flags to skip tests with specific names (or that contain a specific string in their name) by passing the --skip argument through to the test harness (can be specified multiple times):

By default, cargo uses substring matching to match --skip arguments and actual names of tests, which can be turned off by using the --exact flag.

If any tests are skipped or disabled, the package SHOULD include comments that explain why this is the case, and include links to upstream issues, if available.

Packages for non-crate Rust projects MUST be named according to the generic Naming Guidelines, i.e. they MUST NOT use a rust- prefix for the source package name.

The generic guidelines for referencing sources apply.

The %{crates_source} macro SHOULD NOT be used for packages like this, even when packaging a Rust crate that is also published on crates.io.

Any -a and -n flags or -f arguments that are passed to %cargo_generate_buildrequires are applied to all workspace members during dependency resolution.

The %cargo_install macro SHOULD NOT be used for packages like this. Instead, use install or cp to copy built executables or shared libraries from target/rpm/* into the buildroot explicltly, as needed.

Projects with build systems that call cargo internally to build Rust components MUST follow the same guidelines as other projects that build Rust code with cargo.

Packages MUST ensure that the cargo calls that are internal to the project’s build system do not pass flags or arguments that are incompatible with either the default compiler flags or cargo options that are set in the %cargo_build macro or configured by %cargo_prep.

Recent versions of meson have limited support for building crate dependencies without cargo. It is necessary to manually override crate sources with the local registry to use packaged crate dependencies.

Verify that project license file(s) and the LICENSE.dependencies file are included in built packages as expected (rpm -qL -p <path to RPM>) when using %pyproject_save_files -l.