docs/about/build-platforms.rst

   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 Supported host architectures
  33 ----------------------------
  34
  35 Those hosts are officially supported, with various accelerators:
  36
  37   .. list-table::
  38    :header-rows: 1
  39
  40    * - CPU Architecture
  41      - Accelerators
  42    * - Arm
  43      - kvm (64 bit only), tcg, xen
  44    * - MIPS (little endian only)
  45      - kvm, tcg
  46    * - PPC
  47      - kvm, tcg
  48    * - RISC-V
  49      - kvm, tcg
  50    * - s390x
  51      - kvm, tcg
  52    * - SPARC
  53      - tcg
  54    * - x86
  55      - hax, hvf (64 bit only), kvm, nvmm, tcg, whpx (64 bit only), xen
  56
  57 Other host architectures are not supported. It is possible to build QEMU system
  58 emulation on an unsupported host architecture using the configure
  59 ``--enable-tcg-interpreter`` option to enable the TCI support, but note that
  60 this is very slow and is not recommended for normal use. QEMU user emulation
  61 requires host-specific support for signal handling, therefore TCI won't help
  62 on unsupported host architectures.
  63
  64 Non-supported architectures may be removed in the future following the
  65 :ref:`deprecation process<Deprecated features>`.
  66
  67 Linux OS, macOS, FreeBSD, NetBSD, OpenBSD
  68 -----------------------------------------
  69
  70 The project aims to support the most recent major version at all times for
  71 up to five years after its initial release. Support
  72 for the previous major version will be dropped 2 years after the new major
  73 version is released or when the vendor itself drops support, whichever comes
  74 first. In this context, third-party efforts to extend the lifetime of a distro
  75 are not considered, even when they are endorsed by the vendor (eg. Debian LTS);
  76 the same is true of repositories that contain packages backported from later
  77 releases (e.g. Debian backports). Within each major release, only the most
  78 recent minor release is considered.
  79
  80 For the purposes of identifying supported software versions available on Linux,
  81 the project will look at CentOS, Debian, Fedora, openSUSE, RHEL, SLES and
  82 Ubuntu LTS. Other distros will be assumed to ship similar software versions.
  83
  84 For FreeBSD and OpenBSD, decisions will be made based on the contents of the
  85 respective ports repository, while NetBSD will use the pkgsrc repository.
  86
  87 For macOS, `Homebrew`_ will be used, although `MacPorts`_ is expected to carry
  88 similar versions.
  89
  90 Some build dependencies may follow less conservative rules:
  91
  92 Python runtime
  93   Distributions with long-term support often provide multiple versions
  94   of the Python runtime.  While QEMU will initially aim to support the
  95   distribution's default runtime, it may later increase its minimum version
  96   to any newer python that is available as an option from the vendor.
  97   In this case, it will be necessary to use the ``--python`` command line
  98   option of the ``configure`` script to point QEMU to a supported
  99   version of the Python runtime.
 100
 101   As of QEMU |version|, the minimum supported version of Python is 3.7.
 102
 103 Python build dependencies
 104   Some of QEMU's build dependencies are written in Python.  Usually these
 105   are only packaged by distributions for the default Python runtime.
 106   If QEMU bumps its minimum Python version and a non-default runtime is
 107   required, it may be necessary to fetch python modules from the Python
 108   Package Index (PyPI) via ``pip``, in order to build QEMU.
 109
 110 Optional build dependencies
 111   Build components whose absence does not affect the ability to build
 112   QEMU may not be available in distros, or may be too old for QEMU's
 113   requirements.  Many of these, such as the Avocado testing framework
 114   or various linters, are written in Python and therefore can also
 115   be installed using ``pip``.  Cross compilers are another example
 116   of optional build-time dependency; in this case it is possible to
 117   download them from repositories such as EPEL, to use container-based
 118   cross compilation using ``docker`` or ``podman``, or to use pre-built
 119   binaries distributed with QEMU.
 120
 121
 122 Windows
 123 -------
 124
 125 The project aims to support the two most recent versions of Windows that are
 126 still supported by the vendor. The minimum Windows API that is currently
 127 targeted is "Windows 8", so theoretically the QEMU binaries can still be run
 128 on older versions of Windows, too. However, such old versions of Windows are
 129 not tested anymore, so it is recommended to use one of the latest versions of
 130 Windows instead.
 131
 132 The project supports building QEMU with current versions of the MinGW
 133 toolchain, either hosted on Linux (Debian/Fedora) or via `MSYS2`_ on Windows.
 134 A more recent Windows version is always preferred as it is less likely to have
 135 problems with building via MSYS2. The building process of QEMU involves some
 136 Python scripts that call os.symlink() which needs special attention for the
 137 build process to successfully complete. On newer versions of Windows 10,
 138 unprivileged accounts can create symlinks if Developer Mode is enabled.
 139 When Developer Mode is not available/enabled, the SeCreateSymbolicLinkPrivilege
 140 privilege is required, or the process must be run as an administrator.
 141
 142 .. _Homebrew: https://brew.sh/
 143 .. _MacPorts: https://www.macports.org/
 144 .. _MSYS2: https://www.msys2.org/
 145 .. _Repology: https://repology.org/