This series adds a prelude module to all crates, so that
it becomes possible to import from each crate with either
of the following

   use XYZ::prelude::*;
   use XYZ::{self, prelude::*};

The latter is used for items that have a "too common"
name to be put in the prelude: util::Error, util::Result,
migration::Infallible.

Thanks,

Paolo

Paolo Bonzini (8):
  util: add prelude
  common: add prelude
  hwcore: add prelude
  migration: add prelude
  chardev: add prelude
  bql: add prelude
  system: add prelude
  qom: add more to the prelude

 rust/bql/meson.build              |  1 +
 rust/bql/src/lib.rs               |  5 +++++
 rust/bql/src/prelude.rs           |  4 ++++
 rust/chardev/meson.build          |  1 +
 rust/chardev/src/chardev.rs       |  2 +-
 rust/chardev/src/lib.rs           |  5 +++++
 rust/chardev/src/prelude.rs       |  5 +++++
 rust/common/meson.build           | 13 +------------
 rust/common/src/lib.rs            |  5 +++++
 rust/common/src/prelude.rs        |  9 +++++++++
 rust/hw/char/pl011/src/device.rs  | 22 ++++++++--------------
 rust/hw/core/meson.build          |  1 +
 rust/hw/core/src/lib.rs           |  5 +++++
 rust/hw/core/src/prelude.rs       | 14 ++++++++++++++
 rust/hw/core/src/qdev.rs          |  2 +-
 rust/hw/core/src/sysbus.rs        |  2 +-
 rust/hw/core/tests/tests.rs       |  8 ++++----
 rust/hw/timer/hpet/src/device.rs  | 26 +++++++++-----------------
 rust/hw/timer/hpet/src/fw_cfg.rs  |  2 +-
 rust/migration/meson.build        |  1 +
 rust/migration/src/lib.rs         |  5 +++++
 rust/migration/src/migratable.rs  |  2 +-
 rust/migration/src/prelude.rs     | 19 +++++++++++++++++++
 rust/qom/src/prelude.rs           |  4 ++++
 rust/system/meson.build           |  1 +
 rust/system/src/lib.rs            |  5 +++++
 rust/system/src/prelude.rs        |  8 ++++++++
 rust/tests/tests/vmstate_tests.rs |  7 +++----
 rust/util/meson.build             |  1 +
 rust/util/src/lib.rs              |  5 +++++
 rust/util/src/prelude.rs          | 11 +++++++++++
 31 files changed, 145 insertions(+), 56 deletions(-)
 create mode 100644 rust/bql/src/prelude.rs
 create mode 100644 rust/chardev/src/prelude.rs
 create mode 100644 rust/common/src/prelude.rs
 create mode 100644 rust/hw/core/src/prelude.rs
 create mode 100644 rust/migration/src/prelude.rs
 create mode 100644 rust/system/src/prelude.rs
 create mode 100644 rust/util/src/prelude.rs

-- 
2.51.1

Hi

On Mon, Nov 17, 2025 at 11:43 AM Paolo Bonzini <pbonzini@redhat.com> wrote:
>
> This series adds a prelude module to all crates, so that
> it becomes possible to import from each crate with either
> of the following
>
>    use XYZ::prelude::*;
>    use XYZ::{self, prelude::*};
>
> The latter is used for items that have a "too common"
> name to be put in the prelude: util::Error, util::Result,
> migration::Infallible.

In my experience, "preludes" are not so ubiquitous (except the std
library). The use of wildcard imports is not encouraged, and may
result in conflicts. Also, it's often subjective what you put there or
not.

I don't think we should encourage it, having explicit import of what
is used is often clearer.

>
> Thanks,
>
> Paolo
>
> Paolo Bonzini (8):
>   util: add prelude
>   common: add prelude
>   hwcore: add prelude
>   migration: add prelude
>   chardev: add prelude
>   bql: add prelude
>   system: add prelude
>   qom: add more to the prelude
>
>  rust/bql/meson.build              |  1 +
>  rust/bql/src/lib.rs               |  5 +++++
>  rust/bql/src/prelude.rs           |  4 ++++
>  rust/chardev/meson.build          |  1 +
>  rust/chardev/src/chardev.rs       |  2 +-
>  rust/chardev/src/lib.rs           |  5 +++++
>  rust/chardev/src/prelude.rs       |  5 +++++
>  rust/common/meson.build           | 13 +------------
>  rust/common/src/lib.rs            |  5 +++++
>  rust/common/src/prelude.rs        |  9 +++++++++
>  rust/hw/char/pl011/src/device.rs  | 22 ++++++++--------------
>  rust/hw/core/meson.build          |  1 +
>  rust/hw/core/src/lib.rs           |  5 +++++
>  rust/hw/core/src/prelude.rs       | 14 ++++++++++++++
>  rust/hw/core/src/qdev.rs          |  2 +-
>  rust/hw/core/src/sysbus.rs        |  2 +-
>  rust/hw/core/tests/tests.rs       |  8 ++++----
>  rust/hw/timer/hpet/src/device.rs  | 26 +++++++++-----------------
>  rust/hw/timer/hpet/src/fw_cfg.rs  |  2 +-
>  rust/migration/meson.build        |  1 +
>  rust/migration/src/lib.rs         |  5 +++++
>  rust/migration/src/migratable.rs  |  2 +-
>  rust/migration/src/prelude.rs     | 19 +++++++++++++++++++
>  rust/qom/src/prelude.rs           |  4 ++++
>  rust/system/meson.build           |  1 +
>  rust/system/src/lib.rs            |  5 +++++
>  rust/system/src/prelude.rs        |  8 ++++++++
>  rust/tests/tests/vmstate_tests.rs |  7 +++----
>  rust/util/meson.build             |  1 +
>  rust/util/src/lib.rs              |  5 +++++
>  rust/util/src/prelude.rs          | 11 +++++++++++
>  31 files changed, 145 insertions(+), 56 deletions(-)
>  create mode 100644 rust/bql/src/prelude.rs
>  create mode 100644 rust/chardev/src/prelude.rs
>  create mode 100644 rust/common/src/prelude.rs
>  create mode 100644 rust/hw/core/src/prelude.rs
>  create mode 100644 rust/migration/src/prelude.rs
>  create mode 100644 rust/system/src/prelude.rs
>  create mode 100644 rust/util/src/prelude.rs
>
> --
> 2.51.1
>
>


-- 
Marc-André Lureau

On Mon, Nov 17, 2025 at 9:03 AM Marc-André Lureau
<marcandre.lureau@gmail.com> wrote:
>
> Hi
>
> On Mon, Nov 17, 2025 at 11:43 AM Paolo Bonzini <pbonzini@redhat.com> wrote:
> >
> > This series adds a prelude module to all crates, so that
> > it becomes possible to import from each crate with either
> > of the following
> >
> >    use XYZ::prelude::*;
> >    use XYZ::{self, prelude::*};
> >
> > The latter is used for items that have a "too common"
> > name to be put in the prelude: util::Error, util::Result,
> > migration::Infallible.
>
> In my experience, "preludes" are not so ubiquitous (except the std
> library). The use of wildcard imports is not encouraged, and may
> result in conflicts.

Yes, I agree with this.  On the other hand, we already have lists of
imports that are two-three lines long and I'm afraid that people would
prefer to just import migration::* for example.  While we can block
them with -Dclippy::wildcard_imports, the problem is real.

So I was a bit undecided and went looking for examples of crates that
do have a prelude. I first noticed that bevy has a similar system,
with each of its crates providing a prelude.  IMO QEMU is a similar
case to bevy, where most of the code will use structs from the QEMU
crates more than std, so it makes sense to have them. Futures and
Tokio also have a prelude, and they also fit the idea of crates that
provide a programming environment.

Preludes let you import libraries with a level of detail similar to C
includes.  For simple library crates that offer two-three types it's
not necessary to have one, but as the complexity and number of crates
increase, they provide more clarity.

Another thing to notice is that the QOM bindings work a lot with
extension traits implemented on all types.  There should be no need
for users to know the difference between DeviceState, DeviceMethods
and DeviceClassMethods. Preludes help with that.

> Also, it's often subjective what you put there or not.

Right - for now I just defined what should *never* be in a prelude:
the rule was simply "do not include anything that can conflict with
std".  This should not be that bad, otherwise we'd have similar
problems with C includes as mentioned above.

Another thing that should not be in the preludes without extremely
good reasons is enum variants; Ok/Err and Some/None are the only
exceptions in the standard library prelude, and they should probably
remain the only ones.

Paolo