QEMU is the emulator underneath libvirt, and this GitHub mirror takes no patches

Pull requests are disabled here, so the git history on GitHub is not the source of truth

This repository is a mirror and says so plainly: pull requests are disabled, changes are submitted through the process described at qemu.org/contribute, and the only releases to use are tarballs from the QEMU website. The canonical tree lives on GitLab:

git clone https://gitlab.com/qemu-project/qemu.git

Patches are not sent to a web form. The common route is git format-patch and git send-email to the [email protected] mailing list, every patch must carry a Signed-off-by line from its author, and the code must follow the style section of the Developers Guide. The website is under source control as well, in a separate repository:

git clone https://gitlab.com/qemu-project/qemu-web.git

The practical consequence for anyone evaluating the project is that GitHub here is a read window. A fork on GitHub is not a contribution path, and there are no GitHub releases to install from, so a consumer who wants a binary has to go to qemu.org.

git publish tags every revision of a patch series as my-feature-v1, then v2

Sending a multi-patch series by hand is fiddly enough that the project ships a helper for it. The git-publish utility is described as the recommended way to send regular contributions or successive revisions of one series, it needs a working git send-email setup, and by default it does not automate everything, so the manual steps are worth doing once first. Install instructions are at github.com/stefanha/git-publish. The workflow is short:

$ git checkout master -b my-feature
$ # work on new commits, add your 'Signed-off-by' lines to each
$ git publish

The series lands tagged as my-feature-v1. To send a second round you check out the same topic branch, make changes to the commits (with git rebase, for example), and run git publish again; the series arrives with a v2 tag in the subject and the git tip is tagged my-feature-v2. That versioning is a review convention, not a release mechanism: it tells the maintainers which revision of a proposal they are looking at, and nothing here decides what a released QEMU contains.

Three ways in: direct command line, libvirt, or a userspace ABI translator

QEMU presents itself in three distinct shapes, and confusing them is the usual source of confusion about the project. Run directly, it gives the user full control over behaviour and settings. Run indirectly, it exposes a stable command line interface and monitor API so higher level management layers can drive it, which is the path used by oVirt, OpenStack and virt-manager through libvirt. And separately, it virtualizes the userspace API for Linux and BSD kernel interfaces, letting a binary compiled against one architecture ABI, such as the Linux PPC64 ABI, run on a host with a different one, such as Linux x86_64. That last mode involves no hardware emulation at all, only CPU and syscall emulation, and it is the mode an engineer wants for cross-architecture build tooling rather than for running an operating system.

Without KVM or Xen, CPU work is software translation, not near native

The performance story has two halves and the README keeps them apart. QEMU is capable of emulating a complete machine in software with no need for hardware virtualization support, and it does that with dynamic translation, which the README calls very good performance. Separately, QEMU can integrate with the Xen and KVM hypervisors to provide emulated hardware while the hypervisor manages the CPU, and with that hypervisor support it reaches near native performance for CPUs. So the near-native claim belongs to the KVM and Xen path only. A team that measured nothing and assumed hardware speed will be wrong on a host without either hypervisor, and a CI box that must run a guest will inherit the software path. Full machine emulation also buys portability of a different kind: an OS built for one machine, an ARMv7 board for instance, runs on a different one, an x86_64 PC board.

mkdir build, cd build, ../configure, make, and a Makefile that rejects paths with spaces

Building is four steps:

mkdir build
cd build
../configure
make

The project is meant to be buildable on all modern Linux platforms, OS-X, Win32 through the Mingw64 toolchain, and a variety of other UNIX targets, with per-host notes at wiki.qemu.org/Hosts/Linux, /Hosts/Mac and /Hosts/W32. The Makefile is fussy in ways that surface as errors rather than warnings: it needs GNU make, it sets BUILD_DIR to the current directory, and it fails outright if the main directory contains spaces or colons. It also disables implicit rules with MAKEFLAGS += -rR and runs recipes through bash -o pipefail. Two further guards catch the mistakes newcomers make. Makefile and configure are marked as never regenerated, and an out-of-tree build that finds config-host.mak in what it thinks is the source tree aborts with an error about a tree that seems to have been configured for in-tree builds. The Makefile includes config-host.mak once it exists. Documentation follows the same generate-then-publish shape: the released text is hosted at qemu.org/documentation/ and the development text at qemu.org/docs/master/, both built with Sphinx from the docs/ folder in the source tree.

Three Rust crates sit inside the C tree, with rust-version pinned at 1.83.0

QEMU is written in C, but the root Cargo.toml declares a workspace of three members: rust/hw/char/pl011, rust/hw/timer/hpet and rust/tests. The workspace pins edition 2021 and rust-version 1.83.0, and the file carries a comment reminding contributors to update the msrv in docs/devel/rust.rst. Shared dependencies are thin: anyhow around 1.0, foreign around 0.4.0, libc 0.2.162 and glib-sys 0.21.2 with the v2_66 feature. The lint configuration is strict by default, denying things like unsafe_op_in_unsafe_fn and a long list of clippy and rustdoc rules, with a comment explaining that unknown_lints is allowed because warnings from newer compilers would otherwise break the build, and that a CI job with rust_strict_lints == true catches misspelled allow attributes. Building the Rust crates therefore needs a Rust toolchain alongside the C toolchain.

Where a bug goes depends on who compiled your binary

QEMU tracks bugs in GitLab issues at gitlab.com/qemu-project/qemu/-/issues, and that is the route for problems found in code built from QEMU git or from upstream released sources. The routing rule for the other case is explicit: if you are using a pre-built binary package from an operating system vendor, report to that vendor's own bug tracker first, and only file upstream as well if the bug is also known to affect latest upstream code. That saves contributors from triaging distribution patches. For version history the project points at the ChangeLog wiki page or, for more detail, the git history itself. Communication runs through email and IRC: the qemu-devel mailing list on lists.nongnu.org, and the #qemu channel on irc.oftc.net.

COPYING and COPYING.LIB sit side by side, and the license metadata is empty

The README states that QEMU as a whole is released under the GNU General Public License, version 2, and points at the LICENSE file for the full details. The Rust workspace metadata agrees in a slightly different form, declaring GPL-2.0-or-later as the workspace license. Two license texts sit at the top level of the tree, COPYING and COPYING.LIB, and the repository's own license field is left unset. Anyone vendoring QEMU into a product has to read both files and establish which parts fall under which text before making a decision. What can be said plainly is that the README states GPL version 2 for QEMU as a whole, the Rust workspace declares GPL-2.0-or-later, and the boundary between the two texts is recorded in the tree rather than in a single summary.

Editorial conclusion

Use QEMU when you need a machine emulator you can drive directly or hand to libvirt, and accept that CPU speed without a hypervisor comes from software translation rather than from hardware acceleration. Do not treat this GitHub repository as a development site: pull requests are disabled, so a patch goes to [email protected] with a Signed-off-by line, and the artifact you install should come from a QEMU release tarball, not from a clone of the mirror. Before you build, confirm your build directory path has no spaces or colons, because the Makefile refuses it outright, and check that your Rust toolchain is at least 1.83.0 if you intend to compile the three crates in the workspace.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. qemu/qemu on GitHub
4. README