Bibliotecas Externas e FFI

seed interopera com bibliotecas de plataforma por meio de declarações extern explícitas e entradas de vinculador. As chamadas externas não são seguras até que um wrapper seed auditado estabeleça seus contratos de tipo, propriedade, vida útil, erro e sincronização.

Declarações estrangeiras

A sintaxe limpa é:

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

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

A string opcional após extern seleciona a convenção de chamada. link_name seleciona o símbolo estrangeiro quando ele difere do seed nome da declaração. As declarações podem terminar com ponto e vírgula.

Uma declaração extern não identifica nem carrega uma biblioteca compartilhada por si só. As compilações diretas do compilador fornecem entradas nativas explicitamente:

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

O caminho da biblioteca do sistema é específico do host e deve ser descoberto pelo procedimento package/install em vez de codificado como um valor portátil. --link-library aceita um caminho para um object/archive compartilhado ou o nome de um pacote seed instalado em níveis de destino que suportam vinculação. --link-object adiciona um arquivo objeto. O inicializador de repositório encaminha sinalizadores de compilador diretos suportados quando um aplicativo precisa de entradas nativas explícitas.

Requisitos do pacote

Um pacote que contém declarações extern deve:

declare [package].platforms em seed.toml;
forneça uma raiz não vazia INSTALL.md descrevendo os pacotes do sistema, necessários ABI versões e configuração não-pkg-config para cada plataforma;
manter a seleção target/library consistente com a matriz de destino canônica;
passe seed publish --check antes dos fluxos de trabalho de publicação ou instalação.

Exemplo de fragmento de manifesto:

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

A declaração da plataforma são metadados de validação e compatibilidade. Ele não instala a dependência do sistema operacional.

Lista de verificação do invólucro seguro

Exponha um pub fn seguro comum somente quando sua implementação aplicar todas as pré-condições estrangeiras relevantes para os chamadores:

não nulidade do ponteiro, alinhamento, extensão inicializada e validade da ponta;
comprimento e mutabilidade do buffer;
lidar com a propriedade e o emparelhamento acquire/release exato;
vida útil do armazenamento emprestado durante a chamada e após qualquer visualização retornada;
tratamento de status, errno e operação parcial;
tempo de vida do retorno de chamada, convenção de chamada e thread/synchronization regras;
compatibilidade do domínio do alocador para valores que cruzam o ABI;
layout específico do alvo e ABI suposições.

Se o wrapper não puder estabelecer essas condições, exponha-o como unsafe fn e documente as obrigações do chamador.

Ponteiros e alças

Ponteiros brutos usam mutabilidade explícita de ponta:

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

A verificação de um valor bruto não cria uma proveniência segura. Prefira um proprietário nominal auditado que armazene o identificador, rejeite nulo durante a construção, chame a função de liberação estrangeira de seu destruidor e exponha apenas as operações cujas pré-condições ele pode manter.

Não represente um identificador de propriedade estrangeira como um número inteiro copiável apenas por conveniência. Isso perde a limpeza exata e permite a liberação duplicada.

Vistas estrangeiras emprestadas

Um ponteiro estrangeiro comum ou retorno de fatia não tem prova vitalícia segura. @static_view está disponível apenas em um extern cujo ABI garante que o retorno str ou fatia tem process/static vida útil:

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

Este atributo é uma afirmação de origem confiável, não uma extensão da vida útil, e a chamada permanece insegura. Visualizações estrangeiras derivadas de entrada ou derivadas de identificador devem ser mantidas atrás de um proprietário de wrapper, em vez de estáticas rotuladas incorretamente.

Recursos em seed bibliotecas

Nativo seed bibliotecas usam um perfil qualificado runtime/allocator identidade. Passando string, bytes, shared_bytes, ou valores de propriedade do destruidor em um seed o limite da biblioteca é suportado apenas quando os artefatos produtor e consumidor têm destino compatível, ABI, perfil de construção, perfil de tempo de execução, recursos de tempo de execução e identidade de interface.

Uma biblioteca C arbitrária não entende esses layouts próprios. Prefira estrutura de layout C simples e escalar, ponteiro e pointer/length ABIs em fronteiras de terceiros, com conversão e propriedade retidas dentro do seed invólucro.

Limitações de destino

A emissão de objetos não é prova de FFI ou link hospedado. Consulte seed/compiler/llvm/tests/GATE14_TARGET_MATRIX.tsv antes de documentar um pacote externo como suportado em um destino. Em particular, a linha wasm32-wasi atual é somente de objeto e não fornece um WASI FFI operacional ou tempo de execução.

Grove nota de compatibilidade

Muitos wrappers abaixo do nível superior grove/ árvore usa sintaxe estrangeira substituída, tipos em letras maiúsculas, auxiliares de tempo de execução implícitos ou convenções de propriedade manual. A sua presença não é prova de que cumpram com o LLVM linguagem. Porte e verifique um wrapper antes de listá-lo como uma biblioteca externa atual.