docs/devel/rust.rst

14 __ https://doc.rust-lang.org/nomicon/meet-safe-and-unsafe.html
17 ------------------------------
20 invokes rustc directly, building static libraries that are then linked
24 However, QEMU's build system also tries to be easy to use for people who
25 are accustomed to the more "normal" Cargo-based development workflow.
28 * the set of warnings and lints that are used to build QEMU always
31 * it is also possible to use ``cargo`` for common Rust-specific coding
34 To this end, QEMU includes a ``build.rs`` build script that picks up
35 generated sources from QEMU's build directory and puts it in Cargo's
46 A target for ``rustfmt`` is also declared in ``rust/meson.build``:
53     pyvenv/bin/meson devenv -w ../rust cargo clippy --tests
54     pyvenv/bin/meson devenv -w ../rust cargo fmt
61 * by pointing the ``MESON_BUILD_ROOT`` to the top of your QEMU build
62   tree.  This third method is useful if you are using ``rust-analyzer``;
64   ``rust-analyzer.cargo.extraEnv`` setting.
66 As shown above, you can use the ``--tests`` option as usual to operate on test
67 code.  Note however that you cannot *build* or run tests via ``cargo``, because
71    make check-rust
73 Note that doctests require all ``.o`` files from the build to be available.
84 * associated constants have to be explicitly marked ``'static`` (`changed in
99 * NUL-terminated file names with ``#[track_caller]`` are scheduled for
102   ``util/error.c`` to support non-NUL-terminated file names.
108 __ https://github.com/rust-lang/rust/pull/125258
111 ``--generate-cstr``.  This option requires version 0.66.x and will
116 -------------------------
141 - *complete*: ready for use in new devices; if applicable, the API supports the
144 - *stable*: ready for production use, the API is safe and should not undergo
147 - *proof of concept*: the API is subject to change but allows working with safe
150 - *initial*: the API is in its initial stages; it requires large amount of
151   unsafe code; it might have soundness or type-safety issues
217 provide extra compile-time checking; the basic *realize* functionality
252 __ https://github.com/rust-lang/miri
277 also be provided for ``AioContext``-based locking as well.
282 crate, which is able to "look inside" them when building an in-memory
298 the wrapper to be declared thread-safe::
319   (either a builtin one or a user-defined one) in order to pass it to C
328   in Rust, they can be stored in traits and then turned into ``static``
361     pub fn derive_object(input: TokenStream) -> TokenStream {
373     fn derive_object_or_error(input: DeriveInput) ->
407 ``cargo fmt --check``, maintainers can fix this for you when applying patches.
413 -------------------
422 to build them.  While Meson has initial support for parsing ``Cargo.lock``
426 learn how to build them, as well as to the relevant ``Cargo.toml`` files.
429 and therefore there is a single lock file for the whole build.
431 __ https://doc.rust-lang.org/cargo/reference/workspaces.html#virtual-workspace
437 crate.  The wrap file must be named ``NAME-SEMVER-rs.wrap``, where ``NAME``
439 first non-zero number.  For example, a crate with version ``0.2.3`` will use
442 Third, the Meson rules to build the crate must be added at
443 ``subprojects/NAME-SEMVER-rs/meson.build``.  Generally this includes:
447 * a ``static_library`` or ``rust.proc_macro`` line to perform the actual build
455 apart from ``subproject`` must be duplicated to build both native and
456 non-native versions of the crate.
462 * the ``--cfg`` (which have to be "reverse engineered" from the ``build.rs``
465 * usually, a ``--cap-lints allow`` argument to hide warnings from rustc
468 After every change to the ``meson.build`` file you have to update the patched
469 version with ``meson subprojects update --reset ``NAME-SEMVER-rs``.  This might
472 Also, after every change to the ``meson.build`` file it is strongly suggested to
476 As a last step, add the new subproject to ``scripts/archive-source.sh``,
477 ``scripts/make-release`` and ``subprojects/.gitignore``.