Derleme sistemi, rust_bindgen modül türü aracılığıyla bindgen bağlamalarını oluşturmayı destekler. Bindgen, C kitaplıklarına Rust FFI bağlamaları sağlar (cppstd mülkünün ayarlanmasını gerektiren sınırlı C++ desteğiyle).

Temel rust_bindgen kullanımı

Aşağıda, bindgen kullanan bir modülün nasıl tanımlanacağı ve bu modülün paket olarak nasıl kullanılacağıyla ilgili bir örnek verilmiştir. Harici kod için olduğu gibi bir include!() makrosu aracılığıyla bindgen bağlamalarını kullanmanız gerekiyorsa Kaynak Oluşturucular sayfasına bakın.

Rust'tan çağrılacak örnek C kitaplığı

Aşağıda, Rust'ta kullanılmak üzere bir yapı ve işlev tanımlayan örnek bir C kitaplığı verilmiştir.

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);
}

rust_bindgen modülü tanımlama

Alakalı tüm üstbilgileri içeren bir sarmalayıcı üstbilgisi (external/rust/libbuzz/libbuzz_wrapper.h) tanımlayın:

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

Android.bp dosyasını external/rust/libbuzz/Android.bp olarak tanımlayın:

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"],
}

bindgen işaretlerini kullanma hakkında daha fazla bilgi edinmek için Oluşturulan Bağlantıları Özelleştirme başlıklı bindgen kılavuz bölümüne bakın.

include!() makrosunu kullanmanın ön koşulu olarak bir rust_bindgen modülü tanımlamak için bu bölümü kullandıysanız Kaynak Oluşturucular sayfasındaki Ön koşul'a dönün. Aksi takdirde sonraki bölümlere geçin.

Bağlamaları paket olarak kullanma

Aşağıdaki içeriği kullanarak external/rust/hello_bindgen/Android.bp oluşturun:

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

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

Aşağıdaki içeriği kullanarak external/rust/hello_bindgen/src/main.rs oluşturun:

//! 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) }
}

Son olarak, ikili dosyayı oluşturmak için m hello_bindgen işlevini çağırın.

Bindgen bağlamalarını test etme

Bindgen bağlamaları genellikle, bellek düzeni uyuşmazlıklarını önlemek için oluşturulmuş bir dizi düzen testi içerir. AOSP, bu testler için bir test modülü tanımlamanızı ve testlerin projenizin normal test paketi kapsamında çalıştırılmasını önerir.

Bunlar için bir test ikili dosyası, external/rust/hello_bindgen/Android.bp içinde bir rust_test modülü tanımlanarak kolayca oluşturulabilir:

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",
}

Görünürlük ve bağlantı

Oluşturulan bağlamalar, tür tanımlarından, işlev imzalarından ve ilgili sabitlerden oluştuğu için genellikle çok küçüktür. Bu nedenle, bu kitaplıkları dinamik olarak bağlamak genellikle gereksizdir. Bu modülleri rustlibs üzerinden kullanırken otomatik olarak statik bir varyantın seçilmesi için dinamik bağlantıyı devre dışı bıraktık.

Varsayılan olarak rust_bindgen modülleri, [":__subpackages__"] değerine sahip bir visibility mülküne sahiptir. Bu mülk, yalnızca aynı Android.bp dosyasındaki veya dizin hiyerarşisinde bu dosyanın altındaki modüllerin bu mülkü görmesine izin verir. Bu işlem iki amaca hizmet eder:

• Ağacın başka yerlerinde ham C bağlamalarının kullanılması önerilmez.
• Statik ve dinamik bağlantıların bir karışımıyla elmas bağlantı sorunlarını önler.

Genellikle, diğer geliştiricilerin kullanması için oluşturulan modülün etrafına, bağlamalarla aynı dizin ağacına eklediğiniz güvenli bir sarmalayıcı kitaplığı sağlamanız gerekir. Bu, kullanım alanınız için uygun değilse görünürlük için başka paketler ekleyebilirsiniz. Ek görünürlük kapsamları eklerken, bağlantı oluşturma işleminin başarısız olabileceği için gelecekte aynı işleme bağlanabilecek iki kapsam eklemediğinizden emin olun.

Önemli rust_bindgen özellikleri

Aşağıda tanımlanan özellikler, tüm modüller için geçerli olan önemli ortak özelliklere ek olarak verilmiştir. Bunlar, Rust bindgen modülleri için özellikle önemlidir veya rust_bindgen modülü türüne özgü benzersiz bir davranış sergiler.

stem, name, crate_name

rust_bindgen, kitaplık varyantları oluşturduğundan stem, name ve crate_name mülkleri için rust_library modülleriyle aynı koşulları paylaşır. Referans olarak Önemli Rust kitaplığı özellikleri bölümüne bakın.

wrapper_src

Bu, bu bağlamalar için gereken üstbilgileri içeren bir sarmalayıcı üstbilgi dosyasının göreli yoludur. Dosya uzantısı, üstbilginin nasıl yorumlanacağını ve varsayılan olarak hangi -std işaretinin kullanılacağını belirler. Uzantısı .hh veya .hpp olmadığı sürece bunun bir C başlığı olduğu varsayılır. C++ başlığınızın başka bir uzantısı olması gerekiyorsa cpp_std mülkünü, dosyanın C dosyası olduğunu varsayılan davranışı geçersiz kılacak şekilde ayarlayın.

source_stem

Bu, oluşturulan kaynak dosyanın dosya adıdır. stem mülkü yalnızca oluşturulan kitaplık varyantlarının çıkış dosya adını kontrol ettiğinden, bağlamaları paket olarak kullanıyor olsanız bile bu alan tanımlanmalıdır. Bir modül, rustlibs aracılığıyla kutu yerine kaynak olarak birden fazla kaynak oluşturucuya (bindgen ve protobuf gibi) bağlıysa söz konusu modülün bağımlılıkları olan tüm kaynak oluşturucuların benzersiz source_stem değerlerine sahip olduğundan emin olmanız gerekir. Bağımlı modüller, srcs içinde tanımlanan tüm SourceProvider bağımlılıklarının kaynaklarını ortak bir OUT_DIR dizine kopyalar. Bu nedenle, source_stem'da çakışmalar olması durumunda, oluşturulan kaynak dosyaların OUT_DIR dizininde üzerine yazılır.

c_std

Bu, kullanılacak C standardı sürümünü temsil eden bir dizedir. Geçerli değerler aşağıda listelenmiştir:

• "gnu11" gibi belirli bir sürüm.
• build/soong/cc/config/global.go'ta derleme sistemi tarafından tanımlanan bir değer olan "experimental", mevcut olduğunda C++1z gibi taslak sürümleri kullanabilir.
• Ayarlanmamış veya "" (derleme sisteminin varsayılanının kullanılacağını belirtir).

Bu ayar yapılırsa dosya uzantısı yoksayılır ve üstbilginin C üstbilgisi olduğu varsayılır. Bu, cpp_std ile aynı anda ayarlanamaz.

cpp_std

cpp_std, kullanılacak C standart sürümünü temsil eden bir dizedir. Geçerli değerler:

• "gnu++11" gibi belirli bir sürüm
• build/soong/cc/config/global.go'ta derleme sistemi tarafından tanımlanan bir değer olan "experimental", mevcut olduğunda C++1z gibi taslak sürümleri kullanabilir.
• Ayarlanmamış veya "" (derleme sistemi varsayılanının kullanılacağını belirtir).

Bu ayar yapılırsa dosya uzantısı yoksayılır ve başlığın C++ başlığı olduğu varsayılır. Bu, c_std ile aynı anda ayarlanamaz.

cflags

cflags, başlıkları doğru şekilde yorumlamak için gereken Clang işaretlerinin dize listesini sağlar.

custom_bindgen

Gelişmiş kullanım alanları için bindgen, kitaplık olarak kullanılabilir. Bu kitaplık, özel bir Rust ikili dosyası kapsamında değiştirilebilecek bir API sağlar. custom_bindgen alanı, normal bindgen ikili dosyası yerine bindgen API'yi kullanan bir rust_binary_host modülünün modül adını alır.

Bu özel ikili, bindgen'e benzer şekilde bağımsız değişkenler beklemelidir. Örneğin:

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

Bunların çoğu bindgen kitaplığı tarafından yönetilir. Bu kullanıma dair bir örnek görmek için external/rust/crates/libsqlite3-sys/android/build.rs adresini ziyaret edin.

Ayrıca, kitaplığın derlenmesini kontrol etmek için kitaplık özelliklerinin tamamı kullanılabilir. Ancak bu özelliklerin nadiren tanımlanması veya değiştirilmesi gerekir.

handle_static_inline ve static_inline_library

Bu iki özelliğin birlikte kullanılması amaçlanmıştır ve dışa aktarılan bindgen bağlamalarına dahil edilebilecek statik satır içi işlevler için sarmalayıcılar üretilmesine olanak tanır.

Bunları kullanmak için handle_static_inline: true ve static_inline_library'yi, rust_bindgen modülünü kaynak girişi olarak tanımlayan ilgili bir cc_library_static olarak ayarlayın.

Örnek kullanım:

    rust_bindgen {
        name: "libbindgen",
        wrapper_src: "src/any.h",
        crate_name: "bindgen",
        stem: "libbindgen",
        source_stem: "bindings",

        // Produce bindings for static inline fucntions
        handle_static_inline: true,
        static_inline_library: "libbindgen_staticfns"
    }

    cc_library_static {
        name: "libbindgen_staticfns",

        // This is the rust_bindgen module defined above
        srcs: [":libbindgen"],

        // The include path to the header file in the generated c file is
        // relative to build top.
        include_dirs: ["."],
    }