aac1b59b85 · samitouri/QOSamiQemu · siGit Code & Deploy

@@ -21,15 +21,11 @@ invokes rustc directly, building static libraries that are then linked

21 together with the C code. This is completely automatic when you run

22 ``make`` or ``ninja``.

23

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.

26 -In particular:

27 -

28 -* the set of warnings and lints that are used to build QEMU always

29 - comes from the ``Cargo.toml`` workspace file

30 -

31 -* it is also possible to use ``cargo`` for common Rust-specific coding

32 - tasks, in particular to invoke ``clippy``, ``rustfmt`` and ``rustdoc``.

24 +However, Meson is able to consume ``Cargo.toml`` files and tries

25 +to be easy to use for people who are accustomed to the more "normal"

26 +Cargo-based development workflow. In the case of QEMU, in addition,

27 +it is possible to use ``cargo`` for common Rust-specific coding

28 +tasks, in particular to invoke ``clippy``, ``rustfmt`` and ``rustdoc``.

29

30 To this end, QEMU includes a ``build.rs`` build script that picks up

31 generated sources from QEMU's build directory and puts it in Cargo's

@@ -466,63 +462,38 @@ Adding dependencies

462 Generally, the set of dependent crates is kept small. Think twice before

463 adding a new external crate, especially if it comes with a large set of

464 dependencies itself. Sometimes QEMU only needs a small subset of the

469 -functionality; see for example QEMU's ``assertions`` module.

465 +functionality; see for example QEMU's ``assertions`` module. Also,

466 +choose a version of the crate that works with QEMU's minimum supported

467 +Rust version (|msrv|).

468

469 On top of this recommendation, adding external crates to QEMU is a

470 slightly complicated process, mostly due to the need to teach Meson how

473 -to build them. While Meson has initial support for parsing ``Cargo.lock``

474 -files, it is still highly experimental and is therefore not used.

475 -

476 -Therefore, external crates must be added as subprojects for Meson to

477 -learn how to build them, as well as to the relevant ``Cargo.toml`` files.

478 -The versions specified in ``Cargo.lock`` must be the same as the

479 -subprojects; note that the QEMU source tree forms a Cargo `workspace`__,

480 -and therefore there is a single lock file for the whole build.

481 -

482 -__ https://doc.rust-lang.org/cargo/reference/workspaces.html#virtual-workspace

471 +to download them. While QEMU uses Meson's support for parsing ``Cargo.toml``

472 +files, it ships ``.wrap`` files instead of using ``Cargo.lock``; this way,

473 +distros can adjust the set of dependencies to the exact versions they use.

474 +The versions specified in QEMU's ``Cargo.lock`` must be the same as the

475 +one in the wrap file.

476

484 -Choose a version of the crate that works with QEMU's minimum supported

485 -Rust version (|msrv|).

486 -

487 -Second, a new ``wrap`` file must be added to teach Meson how to download the

488 -crate. The wrap file must be named ``NAME-SEMVER-rs.wrap``, where ``NAME``

477 +The wrap file must be named ``NAME-SEMVER-rs.wrap``, where ``NAME``

478 is the name of the crate and ``SEMVER`` is the version up to and including the

479 first non-zero number. For example, a crate with version ``0.2.3`` will use

480 ``0.2`` for its ``SEMVER``, while a crate with version ``1.0.84`` will use ``1``.

481

493 -Third, the Meson rules to build the crate must be added at

494 -``subprojects/NAME-SEMVER-rs/meson.build``. Generally this includes:

495 -

496 -* ``subproject`` and ``dependency`` lines for all dependent crates

497 -

498 -* a ``static_library`` or ``rust.proc_macro`` line to perform the actual build

499 -

500 -* ``declare_dependency`` and a ``meson.override_dependency`` lines to expose

501 - the result to QEMU and to other subprojects

502 -

503 -Remember to add ``native: true`` to ``dependency``, ``static_library`` and

504 -``meson.override_dependency`` for dependencies of procedural macros.

505 -If a crate is needed in both procedural macros and QEMU binaries, everything

506 -apart from ``subproject`` must be duplicated to build both native and

507 -non-native versions of the crate.

508 -

509 -It's important to specify the right compiler options. These include:

510 -

511 -* the language edition (which can be found in the ``Cargo.toml`` file)

512 -

513 -* the ``--cfg`` (which have to be "reverse engineered" from the ``build.rs``

514 - file of the crate).

515 -

516 -* usually, a ``--cap-lints allow`` argument to hide warnings from rustc

517 - or clippy.

518 -

519 -After every change to the ``meson.build`` file you have to update the patched

520 -version with ``meson subprojects update --reset ``NAME-SEMVER-rs``. This might

521 -be automated in the future.

522 -

523 -Also, after every change to the ``meson.build`` file it is strongly suggested to

524 -do a dummy change to the ``.wrap`` file (for example adding a comment like

525 -``# version 2``), which will help Meson notice that the subproject is out of date.

482 +Usually, Meson is able to figure out how to build the crate, and also handles

483 +cross compilation correctly. For crates that have a ``build.rs`` file,

484 +equivalent rules must be added to

485 +``subprojects/packagefiles/NAME-SEMVER-rs/meson/meson.build``.

486 +The file can modify the ``extra_args`` and ``extra_deps`` variables,

487 +which contain respectively the compiler arguments and external dependencies

488 +for the crate.

489 +

490 +After every change to the ``meson/meson.build`` file you have to update the

491 +patched version with ``meson subprojects update --reset ``NAME-SEMVER-rs``.

492 +This might be automated in the future.

493 +

494 +Also, after every change to the file it is strongly suggested to do a dummy

495 +change to the ``.wrap`` file (for example adding a comment like ``# version 2``),

496 +which will help Meson notice that the subproject is out of date.

497

498 As a last step, add the new subproject to ``scripts/archive-source.sh``,

499 ``scripts/make-release`` and ``subprojects/.gitignore``.

docs: rust: update for new-style build rules