Bibliotecas externas y FFI

seed interopera con las bibliotecas de la plataforma a través de declaraciones explícitas extern y entradas del vinculador. Las llamadas al exterior no son seguras hasta que un contenedor seed auditado establezca su tipo, propiedad, duración, error y contratos de sincronización.

Declaraciones extranjeras

La sintaxis limpia es:

extern "c" fn c_sqrt(value: f64) -> f64 link_name "sqrt";

pub fn sqrt_value(value: f64) -> f64 {
    unsafe { c_sqrt(value) }
}

La cadena opcional después extern selecciona la convención de llamada. link_name selecciona el símbolo extranjero cuando difiere del seed nombre de la declaración. Las declaraciones pueden terminar con punto y coma.

Una declaración extern no identifica ni carga una biblioteca compartida por sí sola. Las compilaciones directas del compilador proporcionan entradas nativas explícitamente:

seed/compiler/llvm/build/seed \
  --emit-binary app \
  --link-library /usr/lib/x86_64-linux-gnu/libm.so.6 \
  app.sd

La ruta de la biblioteca del sistema es específica del host y debe descubrirse mediante el procedimiento package/install en lugar de codificarla como un valor portátil. --link-library acepta una ruta a un object/archive compartido o el nombre de un paquete seed instalado en niveles de destino que admiten la vinculación. --link-object agrega un archivo de objeto. El iniciador del repositorio reenvía indicadores del compilador directo admitidos cuando una aplicación necesita entradas nativas explícitas.

Requisitos del paquete

Un paquete que contiene declaraciones extern debe:

declarar [package].platforms en seed.toml;
proporcione una raíz no vacía INSTALL.md que describa los paquetes del sistema, necesarios ABI versiones y configuración sin pkg-config para cada plataforma;
mantenga la selección de target/library consistente con la matriz objetivo canónica;
pase seed publish --check antes de los flujos de trabajo de publicación o instalación.

Fragmento de manifiesto de ejemplo:

[package]
name = "math-wrapper"
version = "0.1.0"
kind = "lib"
platforms = ["linux-x86-64", "linux-aarch64"]

La declaración de plataforma son metadatos de validación y compatibilidad. No instala la dependencia del sistema operativo.

Lista de verificación del envoltorio seguro

Exponga un pub fn seguro ordinario solo cuando su implementación aplique todas las condiciones previas externas relevantes para las personas que llaman:

no nulidad del puntero, alineación, extensión inicializada y validez del puntero;
longitud del buffer y mutabilidad;
manejar la propiedad y exacta acquire/release emparejamiento;
duración del almacenamiento prestado durante la llamada y después de cualquier vista devuelta;
manejo de estado, error y operación parcial;
duración de la devolución de llamada, convención de llamadas y thread/synchronization reglas;
compatibilidad del dominio del asignador para valores que cruzan el ABI;
diseño específico del objetivo y ABI suposiciones.

Si el contenedor no puede establecer estas condiciones, expóngalo como unsafe fn y documente las obligaciones de la persona que llama.

Punteros y manijas

Los punteros sin formato utilizan mutabilidad de punta explícita:

extern "c" fn foreign_open() -> *mut u8;
extern "c" fn foreign_close(handle: *mut u8);

Verificar un valor bruto no crea una procedencia segura. Prefiera un propietario nominal auditado que almacene el identificador, rechace nulo durante la construcción, llame a la función de liberación externa desde su destructor y exponga solo operaciones cuyas condiciones previas pueda mantener.

No represente un identificador de propiedad extranjera como un número entero copiable simplemente por conveniencia. Eso pierde la limpieza exacta y permite la liberación de duplicados.

Vistas extranjeras prestadas

Un puntero externo ordinario o un retorno de segmento no tienen una prueba segura de por vida. @static_view está disponible sólo en un extern cuyo ABI garantiza que la devolución str o rebanada tiene process/static vida:

@static_view extern "c" fn foreign_version() -> str;

Este atributo es una afirmación de procedencia confiable, no una extensión de vida, y la llamada sigue siendo insegura. Las vistas externas derivadas de entradas o de identificadores deben mantenerse detrás de un propietario de contenedor en lugar de etiquetarse incorrectamente como estáticas.

Recursos en todo seed bibliotecas

Nativo seed las bibliotecas utilizan un perfil calificado runtime/allocator identidad. pasando string, bytes, shared_bytes, o valores propiedad del destructor en un seed El límite de la biblioteca solo se admite cuando los artefactos del productor y del consumidor tienen un objetivo compatible. ABI, perfil de compilación, perfil de tiempo de ejecución, funciones de tiempo de ejecución e identidad de interfaz.

Una biblioteca C arbitraria no comprende esos diseños de propiedad. Prefiere estructura escalar, de diseño C simple, puntero y pointer/length ABI en límites de terceros, con conversión y propiedad retenidas dentro del seed envoltorio.

Limitaciones de objetivos

La emisión de objetos no es prueba de FFI o de enlaces alojados. Consulte seed/compiler/llvm/tests/GATE14_TARGET_MATRIX.tsv antes de documentar que un paquete externo es compatible con un destino. En particular, la fila actual wasm32-wasi es solo de objeto y no proporciona un WASI FFI ni un tiempo de ejecución operativo.

Grove nota de compatibilidad

Muchos envoltorios bajo el nivel superior. grove/ El árbol utiliza sintaxis foránea reemplazada, tipos en mayúscula, ayudantes de tiempo de ejecución implícitos o convenciones de propiedad manual. Su presencia no es evidencia de que cumplan con las normas operativas. LLVM idioma. Portar y verificar un contenedor antes de incluirlo como biblioteca externa actual.