Módulos de vinculações bindgen

O sistema de build possibilita gerar vinculações bindgen usando o tipo de módulo rust_bindgen. A bindgen fornece vinculações de FFI do Rust às bibliotecas C com suporte para código C++ limitado, o que exige a definição da propriedade cppstd.

Uso básico do rust_bindgen

Veja abaixo um exemplo de como definir um módulo que usa a bindgen e aprenda a usar esse módulo como uma caixa. Se você precisar usar vinculações bindgen com uma macro include!(), como para o código externo, consulte a página Geradores de origem.

Exemplo de uma biblioteca C para chamadas do Rust

Veja um exemplo de biblioteca C que define uma estrutura e uma função para uso com o Rust abaixo.

external/rust/libbuzz/libbuzz.h

typedef struct foo {
    int x;
} foo;

void fizz(int i, foo* cs);

external/rust/libbuzz/libbuzz.c

#include <stdio.h>
#include "libbuzz.h"

void fizz(int i, foo* my_foo){
    printf("hello from c! i = %i, my_foo->x = %i\n", i, my_foo->x);
}

Como definir um módulo rust_bindgen

Defina um cabeçalho do wrapper external/rust/libbuzz/libbuzz_wrapper.h, que inclui todos os cabeçalhos relevantes:

// Include headers that are required for generating bindings in a wrapper header.
#include "libbuzz.h"

Importante: por padrão, o sistema de build presume que o cabeçalho é C, a menos que a extensão seja .hpp ou o valor cpp_std esteja definido. Isso determina qual flag -std será transmitida ao Clang. Consulte a documentação das propriedades do módulo abaixo para saber mais.

Defina o arquivo Android.bp como external/rust/libbuzz/Android.bp:

cc_library {
    name: "libbuzz",
    srcs: ["libbuzz.c"],
}

rust_bindgen {
     name: "libbuzz_bindgen",

     // Crate name that's used to generate the rust_library variants.
     crate_name: "buzz_bindgen",

     // Path to the wrapper source file.
     wrapper_src: "libbuzz_wrapper.h",

     // 'source_stem' controls the output filename.
     // This is the filename that's used in an include! macro.
     //
     // In this case, we just use "bindings", which produces
     // "bindings.rs".
     source_stem: "bindings",

     // Bindgen-specific flags and options to customize the bindings.
     // See the bindgen manual for more information.
     bindgen_flags: ["--verbose"],

     // Clang flags to be used when generating the bindings.
     cflags: ["-DSOME_FLAG"],

     // Shared, static, and header libraries which export the necessary
     // include directories must be specified.
     //
     // These libraries will also be included in the crate if static,
     // or propagated to dependents if shared.
     // static_libs: ["libbuzz"]
     // header_libs: ["libbuzz"]
     shared_libs: ["libbuzz"],
}

Para saber mais sobre o uso de sinalizações bindgen, consulte a seção do manual da bindgen em Como personalizar vinculações geradas (link em inglês).

Se você usou esta seção para definir um módulo rust_bindgen como pré-requisito para usar a macro include!(), volte para a seção Pré-requisito na página de Geradores de origem. Caso contrário, prossiga para as próximas seções.

Como usar vinculações como uma caixa

Crie external/rust/hello_bindgen/Android.bp com este conteúdo:

rust_binary {
   name: "hello_bindgen",
   srcs: ["main.rs"],

   // Add the rust_bindgen module as if it were a rust_library dependency.
   rustlibs: ["libbuzz_bindgen"],
}

Crie external/rust/hello_bindgen/src/main.rs com este conteúdo:

//! Example crate for testing bindgen bindings

fn main() {
    let mut x = buzz_bindgen::foo { x: 2 };
    unsafe { buzz_bindgen::fizz(1, &mut x as *mut buzz_bindgen::foo) }
}

Por fim, chame m hello_bindgen para criar o binário.

Observação: o uso de vinculações bindgen como uma caixa é o método recomendado para que o código da plataforma utilize vinculações. Se quiser ver um exemplo de como fornecer vinculações para serem usadas com a macro include!() (normalmente para código em external/), consulte Como usar include!() para incluir a origem gerada.

Como testar vinculações bindgen

As vinculações bindgen geralmente contêm vários testes de layout gerados para evitar incompatibilidades de layout na memória. O AOSP recomenda que você defina um módulo para esses testes e que eles sejam executados como parte do pacote normal do projeto.

Um binário para esses testes pode ser facilmente produzido definindo um módulo rust_test em external/rust/hello_bindgen/Android.bp:

rust_test {
    name: "bindings_test",
    srcs: [
        ":libbuzz_bindgen",
    ],
    crate_name: "buzz_bindings_test",
    test_suites: ["general-tests"],
    auto_gen_config: true,

    // Be sure to disable lints as the generated source
    // is not guaranteed to be lint-free.
    clippy_lints: "none",
    lints: "none",
}

Visibilidade e vinculação

As vinculações geradas tendem a ser muito pequenas, já que consistem em definições de tipo, assinaturas de funções e constantes relacionadas. Como resultado, não vale a pena vincular essas bibliotecas dinamicamente. Desativamos a vinculação dinâmica para esses módulos. Assim, o uso com rustlibs vai selecionar automaticamente uma variante estática.

Por padrão, os módulos rust_bindgen têm uma propriedade visibility de [":__subpackages__"], que só vai permitir módulos no mesmo arquivo Android.bp ou abaixo dele na hierarquia do diretório. Isso tem dois propósitos:

• Evitar o uso de vinculações C brutas em outros lugares da árvore.
• Evitar problemas de vinculação de diamantes com uma combinação de vinculações estáticas e dinâmicas.

Normalmente, você precisa fornecer uma biblioteca de wrapper segura em torno do módulo gerado que foi adicionado na mesma árvore de diretórios das vinculações, destinadas ao uso por outros desenvolvedores. Se isso não funcionar no seu caso de uso, adicione outros pacotes à visibilidade. Ao adicionar outros escopos de visibilidade, tome cuidado para não adicionar dois escopos que podem ser vinculados ao mesmo processo no futuro, porque isso pode causar uma falha.

Propriedades rust_bindgen importantes

As propriedades definidas abaixo são adicionadas a propriedades comuns importantes que se aplicam a todos os módulos. Elas são particularmente importantes para os módulos bindgen do Rust ou têm um comportamento único específico para o tipo de módulo rust_bindgen.

stem, name, crate_name

A rust_bindgen produz variantes de biblioteca. Portanto, elas compartilham os mesmos requisitos com os módulos rust_library para as propriedades stem, name e crate_name. Consulte as propriedades Rust importantes da biblioteca para referência.

wrapper_src

Esse é o caminho relativo para um arquivo de cabeçalho do wrapper que inclui os cabeçalhos necessários para essas vinculações. A extensão de arquivo determina como interpretar o cabeçalho e qual sinalização -std usar por padrão. Ela é considerada um cabeçalho C, a menos que a extensão seja .hh ou .hpp. Se o cabeçalho C++ precisar de outra extensão, defina a propriedade cpp_std para substituir o comportamento padrão que pressupõe que o arquivo é um arquivo C.

source_stem

Esse é o nome do arquivo de origem gerado. Esse campo precisa ser definido, mesmo se você estiver usando as vinculações como uma caixa, já que a propriedade stem controla apenas o nome do arquivo de saída das variantes de biblioteca geradas. Se um módulo depende de vários geradores de origem (por exemplo, bindgen e protobuf) como origem, e não como caixas usando rustlibs, você precisa garantir que todos os geradores de origem que são dependências desse módulo tenham valores source_stem exclusivos. Módulos dependentes copiam origens de todas as dependências SourceProvider (definidas em srcs) para um diretório OUT_DIR comum. Portanto, as colisões em source_stem resultariam nos arquivos da origem gerada sendo substituídos no diretório OUT_DIR.

c_std

Essa é uma string que representa a versão padrão do C que será usada. Veja abaixo os valores válidos:

• Uma versão específica, como "gnu11".
• "experimental", que é um valor definido pelo sistema de compilação em build/soong/cc/config/global.go, pode usar versões de rascunho, como C++1z, quando disponíveis.
• Valor não definido ou "", o que indica que o padrão do sistema de compilação vai ser usado.

Se um valor não for definido, a extensão de arquivo vai ser ignorada e o cabeçalho será considerado como C. Isso não pode ser definido ao mesmo tempo que cpp_std.

cpp_std

cpp_std é uma string que representa qual versão padrão do C será usada. Valores válidos:

• Uma versão específica, como "gnu++11".
• "experimental", que é um valor definido pelo sistema de compilação em build/soong/cc/config/global.go, pode usar versões de rascunho, como C++1z, quando disponíveis.
• Valor não definido ou "", o que indica que o padrão do sistema de compilação vai ser usado.

Se um desses valores for definido, a extensão de arquivo vai ser ignorada e o cabeçalho será considerado como C++. Isso não pode ser definido ao mesmo tempo que c_std.

cflags

cflags fornece uma lista de strings de sinalizações do Clang necessárias para interpretar corretamente os cabeçalhos.

custom_bindgen

Para casos de uso avançados, a bindgen pode ser usada como uma biblioteca, fornecendo uma API que pode ser manipulada como parte de um binário personalizado do Rust. O campo custom_bindgen recebe o nome do módulo de um módulo rust_binary_host, que usa a API bindgen em vez do binário bindgen normal.

Esse binário personalizado precisa esperar argumentos de forma parecida à bindgen, como

$ my_bindgen [flags] wrapper_header.h -o [output_path] -- [clang flags]

A maior parte desse processo ocorre na própria biblioteca bindgen. Para conferir um exemplo desse uso, acesse external/rust/crates/libsqlite3-sys/android/build.rs.

Além disso, o conjunto completo de propriedades de biblioteca está disponível para controlar a compilação, embora elas raramente precisem ser definidas ou mudadas.