Rust Modul

(neu seit 0.57.0) (Stabil seit 1.0.0)

Das rust-Modul stellt Hilfsmittel zur Integration von Rust-Code in Meson bereit. Ziel ist es, die Verwendung von Rust in Meson angenehmer zu gestalten, während es mesonic bleibt. Das bedeutet, es wird versucht, Rust mehr wie Meson funktionieren zu lassen, anstatt Meson mehr wie Rust.

Funktionen

test()

rustmod.test(name, target, ...)

Diese Funktion erstellt ein neues Rust-Unittest-Ziel aus einem bestehenden Rust-basierten Ziel, das eine Bibliothek oder eine ausführbare Datei sein kann. Dies geschieht durch Kopieren der Quellen und Argumente, die an das ursprüngliche Ziel übergeben wurden, und Hinzufügen des Arguments --test zur Kompilierung. Anschließend wird ein neues Testziel erstellt, das diese ausführbare Datei unter Verwendung des Rust-Testprotokolls aufruft.

Diese Funktion nimmt zwei Positionsargumente entgegen. Das erste ist der Name des Tests und das zweite die Bibliothek oder ausführbare Datei, die das Rust-basierte Ziel darstellt. Sie nimmt auch die folgenden Schlüsselwortargumente entgegen:

• dependencies: eine Liste von Test-spezifischen Abhängigkeiten
• link_with: eine Liste zusätzlicher Build-Ziele, mit denen gelinkt werden soll (seit 1.2.0)
• rust_args: eine Liste zusätzlicher Argumente, die an den Rust-Compiler übergeben werden (seit 1.2.0)

Diese Funktion akzeptiert auch alle Schlüsselwortargumente, die von der test() Funktion akzeptiert werden, mit Ausnahme von protocol, das automatisch gesetzt wird.

bindgen()

Diese Funktion wickelt bindgen ein, um die Erstellung von Rust-Bindungen um C-Bibliotheken zu vereinfachen. Dies hat zwei Vorteile gegenüber dem Aufruf von bindgen mit einem generator oder custom_target:

• Sie behandelt include_directories, sodass man sie nicht manuell in -I... umwandeln muss.
• Sie richtet automatisch eine Depfile ein, was die Ergebnisse zuverlässiger macht.
• Sie behandelt automatisch Assertions und synchronisiert Rust und C/C++, um das gleiche Verhalten zu erzielen.

Es nimmt die folgenden Schlüsselwortargumente entgegen:

• input: eine Liste von Files, Strings oder CustomTargets. Das erste Element ist die Header-Datei, die bindgen parsen wird, zusätzliche Elemente sind Abhängigkeiten.
• output: der Name der Ausgabedatei im Rust-Format.
• output_inline_wrapper: der Name der optionalen Ausgabedatei in C, die Wrapper für statische Inline-Funktionen enthält. Dies erfordert bindgen-0.65 oder neuer (seit 1.3.0).
• include_directories: Eine Liste von include_directories oder string Objekten. Diese werden an clang als -I Argumente übergeben (string seit 1.0.0)
• c_args: eine Liste von String-Argumenten, die unverändert an clang übergeben werden.
• args: eine Liste von String-Argumenten, die unverändert an bindgen übergeben werden.
• dependencies: eine Liste von Dependency Objekten, die an den zugrundeliegenden clang-Aufruf übergeben werden (seit 1.0.0)
• language: Ein wörtlicher String-Wert von c oder cpp. Wenn gesetzt, zwingt dies bindgen, eine Quelle als die angegebene Sprache zu behandeln. Standardmäßig wird dies anhand der Dateierweiterung des Eingabefiles überprüft. (seit 1.4.0)
• bindgen_version: eine Liste von String-Versionswerten. Wenn gesetzt, muss die gefundene bindgen-Binärdatei diesen Einschränkungen entsprechen. (seit 1.4.0)

rust = import('unstable-rust')

inc = include_directories('..'¸ '../../foo')

generated = rust.bindgen(
    input : 'myheader.h',
    output : 'generated.rs',
    include_directories : [inc, include_directories('foo')],
    args : ['--no-rustfmt-bindings'],
    c_args : ['-DFOO=1'],
)

Wenn der Header von generierten Headern abhängt, müssen diese ebenfalls an bindgen übergeben werden, um eine ordnungsgemäße Abhängigkeitsreihenfolge zu gewährleisten. Statische Header müssen nicht übergeben werden, da eine ordnungsgemäße Depfile generiert wird.

h1 = custom_target(...)
h2 = custom_target(...)

r1 = rust.bindgen(
  input : [h1, h2],  # h1 includes h2,
  output : 'out.rs',
)

Seit 1.1.0 synchronisiert Meson Assertions für Rust und C/C++, wenn die Option b_ndebug gesetzt ist (über -DNDEBUG für C/C++ und -C debug-assertions=on für Rust) und übergibt -DNDEBUG als zusätzliches Argument an clang. Dies ermöglicht ein zuverlässiges Wrapping von -DNDEBUG gesteuertem Verhalten mit #[cfg(debug_asserions)] und/oder cfg!(). Vor 1.1.0 wurden Assertions für Rust von Meson nie aktiviert.

Seit 1.2.0 können zusätzliche Argumente für clang in einer *Machine-Datei im Abschnitt properties angegeben werden.

[properties]
bindgen_clang_arguments = ['-target', 'x86_64-linux-gnu']

proc_macro()

rustmod.proc_macro(name, sources, ...)

Seit 1.3.0

Diese Funktion erstellt ein Rust proc-macro-Crate, ähnlich wie

shared_library()(name, sources,
  rust_crate_type: 'proc-macro',
  native: true)

proc-macro-Ziele können dem Schlüsselwortargument link_with anderer Rust-Ziele übergeben werden.

Nur eine Teilmenge der Schlüsselwortargumente von shared_library() ist erlaubt.

• rust_args
• rust_dependency_map
• sources
• dependencies
• extra_files
• link_args
• link_depends
• link_with
• override_options