| 1 | .. _Supported-build-platforms: |
| 2 | |
| 3 | Supported build platforms |
| 4 | ========================= |
| 5 | |
| 6 | QEMU aims to support building and executing on multiple host OS |
| 7 | platforms. This appendix outlines which platforms are the major build |
| 8 | targets. These platforms are used as the basis for deciding upon the |
| 9 | minimum required versions of 3rd party software QEMU depends on. The |
| 10 | supported platforms are the targets for automated testing performed by |
| 11 | the project when patches are submitted for review, and tested before and |
| 12 | after merge. |
| 13 | |
| 14 | If a platform is not listed here, it does not imply that QEMU won't |
| 15 | work. If an unlisted platform has comparable software versions to a |
| 16 | listed platform, there is every expectation that it will work. Bug |
| 17 | reports are welcome for problems encountered on unlisted platforms |
| 18 | unless they are clearly older vintage than what is described here. |
| 19 | |
| 20 | Note that when considering software versions shipped in distros as |
| 21 | support targets, QEMU considers only the version number, and assumes the |
| 22 | features in that distro match the upstream release with the same |
| 23 | version. In other words, if a distro backports extra features to the |
| 24 | software in their distro, QEMU upstream code will not add explicit |
| 25 | support for those backports, unless the feature is auto-detectable in a |
| 26 | manner that works for the upstream releases too. |
| 27 | |
| 28 | The `Repology`_ site is a useful resource to identify |
| 29 | currently shipped versions of software in various operating systems, |
| 30 | though it does not cover all distros listed below. |
| 31 | |
| 32 | You can find how to install build dependencies for different systems on the |
| 33 | :ref:`setup-build-env` page. |
| 34 | |
| 35 | Supported host architectures |
| 36 | ---------------------------- |
| 37 | |
| 38 | Those hosts are officially supported, with various accelerators: |
| 39 | |
| 40 | .. list-table:: |
| 41 | :header-rows: 1 |
| 42 | |
| 43 | * - CPU Architecture |
| 44 | - Accelerators |
| 45 | * - Arm |
| 46 | - hvf, kvm, tcg, whpx, xen |
| 47 | * - PPC |
| 48 | - kvm, tcg |
| 49 | * - RISC-V |
| 50 | - kvm, tcg |
| 51 | * - s390x |
| 52 | - kvm, tcg |
| 53 | * - SPARC |
| 54 | - tcg |
| 55 | * - x86 |
| 56 | - hvf, mshv, kvm, nvmm, tcg, whpx, xen |
| 57 | |
| 58 | Other host architectures are not supported. It is possible to build QEMU system |
| 59 | emulation on an unsupported host architecture using the configure |
| 60 | ``--enable-tcg-interpreter`` option to enable the TCI support, but note that |
| 61 | this is very slow and is not recommended for normal use. QEMU user emulation |
| 62 | requires host-specific support for signal handling, therefore TCI won't help |
| 63 | on unsupported host architectures. |
| 64 | |
| 65 | Non-supported architectures may be removed in the future following the |
| 66 | :ref:`deprecation process<Deprecated features>`. |
| 67 | |
| 68 | Linux OS, macOS, FreeBSD, NetBSD, OpenBSD |
| 69 | ----------------------------------------- |
| 70 | |
| 71 | The project aims to support the most recent major version at all times for |
| 72 | up to five years after its initial release. Support |
| 73 | for the previous major version will be dropped 2 years after the new major |
| 74 | version is released or when the vendor itself drops support, whichever comes |
| 75 | first. In this context, third-party efforts to extend the lifetime of a distro |
| 76 | are not considered, even when they are endorsed by the vendor (eg. Debian LTS); |
| 77 | the same is true of repositories that contain packages backported from later |
| 78 | releases (e.g. Debian backports). Within each major release, only the most |
| 79 | recent minor release is considered. |
| 80 | |
| 81 | For the purposes of identifying supported software versions available on Linux, |
| 82 | the project will look at CentOS, Debian, Fedora, openSUSE, RHEL, SLES and |
| 83 | Ubuntu LTS. Other distros will be assumed to ship similar software versions. |
| 84 | |
| 85 | For FreeBSD and OpenBSD, decisions will be made based on the contents of the |
| 86 | respective ports repository, while NetBSD will use the pkgsrc repository. |
| 87 | |
| 88 | For macOS, `Homebrew`_ will be used, although `MacPorts`_ is expected to carry |
| 89 | similar versions. |
| 90 | |
| 91 | Some build dependencies may follow less conservative rules: |
| 92 | |
| 93 | Python runtime |
| 94 | Distributions with long-term support often provide multiple versions |
| 95 | of the Python runtime. While QEMU will initially aim to support the |
| 96 | distribution's default runtime, it may later increase its minimum version |
| 97 | to any newer python that is available as an option from the vendor. |
| 98 | In this case, it will be necessary to use the ``--python`` command line |
| 99 | option of the ``configure`` script to point QEMU to a supported |
| 100 | version of the Python runtime. |
| 101 | |
| 102 | As of QEMU |version|, the minimum supported version of Python is 3.9. |
| 103 | |
| 104 | Python build dependencies |
| 105 | Some of QEMU's build dependencies are written in Python. Usually these |
| 106 | are only packaged by distributions for the default Python runtime. |
| 107 | If QEMU bumps its minimum Python version and a non-default runtime is |
| 108 | required, it may be necessary to fetch python modules from the Python |
| 109 | Package Index (PyPI) via ``pip``, in order to build QEMU. |
| 110 | |
| 111 | Rust build dependencies |
| 112 | QEMU is generally conservative in adding new Rust dependencies, and all |
| 113 | of them are included in the distributed tarballs. One exception is the |
| 114 | bindgen tool, which is too big to package and distribute. The minimum |
| 115 | supported version of bindgen is 0.60.x. For distributions that do not |
| 116 | include bindgen or have an older version, it is recommended to install |
| 117 | a newer version using ``cargo install --locked bindgen-cli``. |
| 118 | |
| 119 | QEMU requires Rust 1.83.0. This is available on all supported platforms |
| 120 | except for the ``mips64el`` architecture on Debian bookworm. For all other |
| 121 | architectures, Debian bookworm provides a new-enough Rust compiler |
| 122 | in the ``rustc-web`` package. |
| 123 | |
| 124 | For Ubuntu 22.04 ("Jammy") and 24.04 ("Noble") updated versions of |
| 125 | Rust are available through packages such as ``rustc-1.83`` package; |
| 126 | the path to ``rustc`` and ``rustdoc`` has to be provided manually to |
| 127 | the configure script. |
| 128 | |
| 129 | Some distros prefer to avoid vendored crate sources, and instead use |
| 130 | local sources from e.g. ``/usr/share/cargo/registry``. QEMU includes a |
| 131 | script, ``scripts/update-cargo-wraps.py``, that automatically |
| 132 | performs this task. The script is meant to be invoked after unpacking |
| 133 | the QEMU tarball. QEMU also includes ``rust/Cargo.toml`` and |
| 134 | ``rust/Cargo.lock`` files that can be used to compute QEMU's build |
| 135 | dependencies, e.g. using ``cargo2rpm -p rust/Cargo.toml buildrequires``. |
| 136 | |
| 137 | Optional build dependencies |
| 138 | Build components whose absence does not affect the ability to build QEMU |
| 139 | may not be available in distros, or may be too old for our requirements. |
| 140 | Many of these, such as additional modules for the functional testing |
| 141 | framework or various linters, are written in Python and therefore can |
| 142 | also be installed using ``pip``. Cross compilers are another example |
| 143 | of optional build-time dependency; in this case it is possible to |
| 144 | download them from repositories such as EPEL, to use container-based |
| 145 | cross compilation using ``docker`` or ``podman``, or to use pre-built |
| 146 | binaries distributed with QEMU. |
| 147 | |
| 148 | Windows |
| 149 | ------- |
| 150 | |
| 151 | The project aims to support the two most recent versions of Windows that are |
| 152 | still supported by the vendor. The minimum Windows API that is currently |
| 153 | targeted is "Windows 8", so theoretically the QEMU binaries can still be run |
| 154 | on older versions of Windows, too. However, such old versions of Windows are |
| 155 | not tested anymore, so it is recommended to use one of the latest versions of |
| 156 | Windows instead. |
| 157 | |
| 158 | The project supports building QEMU with current versions of the MinGW |
| 159 | toolchain, either hosted on Linux (Debian/Fedora) or via `MSYS2`_ on Windows. |
| 160 | A more recent Windows version is always preferred as it is less likely to have |
| 161 | problems with building via MSYS2. The building process of QEMU involves some |
| 162 | Python scripts that call os.symlink() which needs special attention for the |
| 163 | build process to successfully complete. On newer versions of Windows 10, |
| 164 | unprivileged accounts can create symlinks if Developer Mode is enabled. |
| 165 | When Developer Mode is not available/enabled, the SeCreateSymbolicLinkPrivilege |
| 166 | privilege is required, or the process must be run as an administrator. |
| 167 | |
| 168 | Only 64-bit Windows is supported. |
| 169 | |
| 170 | .. _Homebrew: https://brew.sh/ |
| 171 | .. _MacPorts: https://www.macports.org/ |
| 172 | .. _MSYS2: https://www.msys2.org/ |
| 173 | .. _Repology: https://repology.org/ |