docs/devel/rust.rst

11 to write other kinds of devices (e.g. PCI devices that can do DMA),
14 __ https://doc.rust-lang.org/nomicon/meet-safe-and-unsafe.html
17 ------------------------------
25 are accustomed to the more "normal" Cargo-based development workflow.
31 * it is also possible to use ``cargo`` for common Rust-specific coding
49     pyvenv/bin/meson devenv -w ../rust cargo clippy --tests
50     pyvenv/bin/meson devenv -w ../rust cargo fmt
58   tree.  This third method is useful if you are using ``rust-analyzer``;
60   ``rust-analyzer.cargo.extraEnv`` setting.
62 As shown above, you can use the ``--tests`` option as usual to operate on test
67    make check-rust
69 Building Rust code with ``--enable-modules`` is not supported yet.
89   the pinned-init create).
126 __ https://github.com/rust-lang/rust/pull/125258
130 for that right now are Debian bookworm and 32-bit MIPS processors.
135 ``--generate-cstr``.  This option requires version 0.66.x and will
140 -------------------------
166 - *complete*: ready for use in new devices; if applicable, the API supports the
169 - *stable*: ready for production use, the API is safe and should not undergo
172 - *proof of concept*: the API is subject to change but allows working with safe
175 - *initial*: the API is in its initial stages; it requires large amount of
176   unsafe code; it might have soundness or type-safety issues
243 provide extra compile-time checking; the basic *realize* functionality
253 Rust has very strict rules with respect to how you get an exclusive (``&mut``)
278 __ https://github.com/rust-lang/miri
303 also be provided for ``AioContext``-based locking as well.
308 crate, which is able to "look inside" them when building an in-memory
324 the wrapper to be declared thread-safe::
337   or ``vmstate``.  If the C code has a complex const struct, look at
345   (either a builtin one or a user-defined one) in order to pass it to C
347   The ``vmstate`` module has examples of how to retrieve type information
387     pub fn derive_object(input: TokenStream) -> TokenStream {
394 The ``qemu_api_macros`` crate has utility functions to examine a
399     fn derive_object_or_error(input: DeriveInput) ->
412   that the structure has ``#[repr[C])`` and that the type of the first field
433 ``cargo fmt --check``, maintainers can fix this for you when applying patches.
439 -------------------
448 to build them.  While Meson has initial support for parsing ``Cargo.lock``
457 __ https://doc.rust-lang.org/cargo/reference/workspaces.html#virtual-workspace
463 crate.  The wrap file must be named ``NAME-SEMVER-rs.wrap``, where ``NAME``
465 first non-zero number.  For example, a crate with version ``0.2.3`` will use
469 ``subprojects/NAME-SEMVER-rs/meson.build``.  Generally this includes:
482 non-native versions of the crate.
488 * the ``--cfg`` (which have to be "reverse engineered" from the ``build.rs``
491 * usually, a ``--cap-lints allow`` argument to hide warnings from rustc
495 version with ``meson subprojects update --reset ``NAME-SEMVER-rs``.  This might
502 As a last step, add the new subproject to ``scripts/archive-source.sh``,
503 ``scripts/make-release`` and ``subprojects/.gitignore``.