Hosts/Linux: Difference between revisions

From QEMU
(Build instructions for Debian and related Linux distributions)
 
(Improve recommended additional packages section)
 
(19 intermediate revisions by 11 users not shown)
Line 14: Line 14:
so you have to install some additional packages before you can build QEMU.
so you have to install some additional packages before you can build QEMU.


=== Debian GNU Linux / Ubuntu Linux / Linux Mint ===
=== Fedora Linux / Debian GNU Linux / Ubuntu Linux / Linux Mint distributions ===


Debian and Debian based or similar distributions normally include
Fedora, Debian and Debian based or similar distributions normally include
compiler and compilation tools (gcc, make, ...) in their default installation.
compiler and compilation tools (gcc, make, ...) in their default installation.


Line 23: Line 23:
* git (30 MiB), version manager
* git (30 MiB), version manager
* glib2.0-dev (9 MiB), this automatically includes zlib1g-dev
* glib2.0-dev (9 MiB), this automatically includes zlib1g-dev
* libfdt-devel
For Ubuntu LTS (and maybe other Debian based distributions),
all required additional packages can be installed like this:
sudo apt-get install git libglib2.0-dev libfdt-dev libpixman-1-dev zlib1g-dev ninja-build
For Red Hat Enterprise Linux 8 or CentOS 8 all required additional packages can be installed like this:
yum install git glib2-devel libfdt-devel pixman-devel zlib-devel bzip2 ninja-build python3


==== Recommended additional packages ====
==== Recommended additional packages ====


Package names are for Debian (Red Hat/Fedora in parentheses).
* git-email, used for sending patches
* git-email, used for sending patches
* libsdl1.2-dev (23 MiB), needed for the SDL based graphical user interface
* libsdl2-dev (libsdl2-devel), needed for the SDL based graphical user interface
* libgtk-3-dev (gtk3-devel), for a simple UI instead of VNC
* libvte-dev (vte291-devel), for access to QEMU monitor and serial/console devices via the GTK interface
* libcapstone-dev (capstone-devel), for disassembling CPU instructions
 
The above list is far from being complete. For maximum code coverage, as many QEMU features as possible should be enabled.
When running configure, you should get many lines with "yes" and only a few with "no".
For Ubuntu (and maybe other Debian based distributions),
most of the recommended additional packages for maximum code coverage can be installed like this:
sudo apt-get install git-email
sudo apt-get install libaio-dev libbluetooth-dev libcapstone-dev libbrlapi-dev libbz2-dev
sudo apt-get install libcap-ng-dev libcurl4-gnutls-dev libgtk-3-dev
sudo apt-get install libibverbs-dev libjpeg8-dev libncurses5-dev libnuma-dev
sudo apt-get install librbd-dev librdmacm-dev
sudo apt-get install libsasl2-dev libsdl2-dev libseccomp-dev libsnappy-dev libssh-dev
sudo apt-get install libvde-dev libvdeplug-dev libvte-2.91-dev libxen-dev liblzo2-dev
sudo apt-get install valgrind xfslibs-dev
Newer versions of Debian / Ubuntu might also try these additional packages:
sudo apt-get install libnfs-dev libiscsi-dev
 
For Red Hat Enterprise Linux or CentOS some of the additional recommended packages can be installed like this:
sudo yum install libaio-devel libcap-ng-devel libiscsi-devel capstone-devel \
                  gtk3-devel libsdl2-devel vte291-devel ncurses-devel \
                  libseccomp-devel nettle-devel libattr-devel libjpeg-devel \
                  brlapi-devel libgcrypt-devel lzo-devel snappy-devel \
                  librdmacm-devel libibverbs-devel cyrus-sasl-devel libpng-devel \
                  libuuid-devel pulseaudio-libs-devel curl-devel libssh-devel \
                  systemtap-sdt-devel libusbx-devel
 
=== SUSE-based distributions ===
 
This section refers to SUSE Linux Enterprise, openSUSE Leap, openSUSE Tumbleweed, Gecko and other SUSE-based Linux distributions.
 
The following command line will provide conditions for building QEMU using its default compiler gcc:
 
sudo zypper install git-core gcc-c++ make qemu glib2-devel libpixman-1-0-devel
 
If one wants to build QEMU using clang, the following line must be run as well:
 
sudo zypper install clang
 
Some additional debugging tools may be installed using:
 
sudo zypper install perf valgrind
 
The command lines from this section are tested on openSUSE Tumbleweed 32-bit fresh installation on an Intel host on March 14th, 2020.


=== Getting the source code ===
=== Getting the source code ===
Line 37: Line 93:
Get the code like this:
Get the code like this:


  git clone git://git.qemu.org/qemu.git
  git clone git://git.qemu-project.org/qemu.git


The resulting directory qemu is your QEMU root directory.
The resulting directory qemu is your QEMU root directory.
Note that when building QEMU from GIT, 'make' will attempt to checkout various [[Documentation/GitSubmodules|GIT submodules]].
=== Simple build and test ===
QEMU supports builds in this directory (not recommended) or
QEMU supports builds in this directory (not recommended) or
in an extra directory (out-of-tree builds, recommended).
in an extra directory (out-of-tree builds, recommended). There can be
any number of out-of-tree builds, so if you plan to make cross builds,
debug and release builds, out-of-tree builds are what you need.


There can be any number of out-of-tree builds, so if you plan
'''Here is my typical build scenario:'''
to make cross builds, debug and release builds, out-of-tree builds
are what you need.
 
Here is my typical build scenario:


  # Switch to the QEMU root directory.
  # Switch to the QEMU root directory.
Line 60: Line 119:
  cd ../../..
  cd ../../..


Now let's start a simple test:
'''Now let's start a simple test:'''


  bin/debug/native/x86_64-softmmu/qemu-system-x86_64 -L pc-bios
  bin/debug/native/x86_64-softmmu/qemu-system-x86_64 -L pc-bios


This test runs the QEMU system emulation which boots a PC BIOS.
This test runs the QEMU system emulation which boots a PC BIOS.
=== Simple build and test with KVM ===
This example will show an in-tree build.
# Switch to the QEMU root directory
cd qemu
# Configure QEMU for x86_64 only - faster build
./configure --target-list=x86_64-softmmu --enable-debug
# Build in parallel - my system has 4 CPUs
make -j4
'''Getting ready to install a guest OS in a VM:'''
# Create a disk for the VM
./qemu-img create -f qcow2 test.qcow2 16G
# Download an install ISO - I have Fedora 20
ls -la Fedora-Live-Desktop-x86_64-20-1.iso
-rwxr-xr-x. 1 xxxxx xxxxx 999292928 May  4 16:32
'''Run QEMU with KVM enabled (w/o VNC):'''
If you have gtk2-devel installed, this will launch a simple UI
and you can install your OS.
x86_64-softmmu/qemu-system-x86_64 -m 1024 -enable-kvm \
-drive if=virtio,file=test.qcow2,cache=none \
-cdrom Fedora-Live-Desktop-x86_64-20-1.iso
'''Run QEMU with KVM enabled (with VNC):'''
If you you prefer VNC, try this:
x86_64-softmmu/qemu-system-x86_64 -m 1024 -enable-kvm \
-drive if=virtio,file=test.qcow2,cache=none \
-cdrom Fedora-Live-Desktop-x86_64-20-1.iso \
-vnc :1
Connect using your favorite VNC viewer to localhost:1 and install your OS.


=== Cross builds ===
=== Cross builds ===


Cross building for non-native architectures is quite common.
Cross building for non-native architectures is quite common. [[Hosts/W32#Cross builds|Hosts/W32]] contains a description of cross building for Windows (32 and 64 bit) on Linux hosts.
TODO: add description.
TODO: add more descriptions (32 bit Linux target on a 64 bit Linux host would be useful for build bots).
 
=== Docker build ===
 
The QEMU build system supports compiling a git clone inside a docker container. With docker installed, for example, it can be started with "make docker-test-quick@ubuntu", to build x86_64-softmmu and aarch64-softmmu targets in a ubuntu instance.


=== Native builds ===
See also [[Testing/DockerBuild]] for more information.


== Running QEMU on Linux ==
== Running QEMU on Linux ==

Latest revision as of 13:31, 6 October 2022

QEMU on Linux hosts

This documentation is work in progress - more information needs to be added for different Linux distributions.

Linux is QEMU's main host platform. Therefore it is the platform which gets most support. Both 32 and 64 bit Linux hosts are supported. Most of the following instructions are valid for both variants.

Building QEMU for Linux

Most Linux distributions already provide binary packages for QEMU (or KVM).

Usually they also include all packages which are needed to compile QEMU for Linux. The default installation of most distributions will not include everything, so you have to install some additional packages before you can build QEMU.

Fedora Linux / Debian GNU Linux / Ubuntu Linux / Linux Mint distributions

Fedora, Debian and Debian based or similar distributions normally include compiler and compilation tools (gcc, make, ...) in their default installation.

Required additional packages

  • git (30 MiB), version manager
  • glib2.0-dev (9 MiB), this automatically includes zlib1g-dev
  • libfdt-devel

For Ubuntu LTS (and maybe other Debian based distributions), all required additional packages can be installed like this:

sudo apt-get install git libglib2.0-dev libfdt-dev libpixman-1-dev zlib1g-dev ninja-build

For Red Hat Enterprise Linux 8 or CentOS 8 all required additional packages can be installed like this:

yum install git glib2-devel libfdt-devel pixman-devel zlib-devel bzip2 ninja-build python3

Recommended additional packages

Package names are for Debian (Red Hat/Fedora in parentheses).

  • git-email, used for sending patches
  • libsdl2-dev (libsdl2-devel), needed for the SDL based graphical user interface
  • libgtk-3-dev (gtk3-devel), for a simple UI instead of VNC
  • libvte-dev (vte291-devel), for access to QEMU monitor and serial/console devices via the GTK interface
  • libcapstone-dev (capstone-devel), for disassembling CPU instructions

The above list is far from being complete. For maximum code coverage, as many QEMU features as possible should be enabled. When running configure, you should get many lines with "yes" and only a few with "no".

For Ubuntu (and maybe other Debian based distributions), most of the recommended additional packages for maximum code coverage can be installed like this:

sudo apt-get install git-email
sudo apt-get install libaio-dev libbluetooth-dev libcapstone-dev libbrlapi-dev libbz2-dev
sudo apt-get install libcap-ng-dev libcurl4-gnutls-dev libgtk-3-dev
sudo apt-get install libibverbs-dev libjpeg8-dev libncurses5-dev libnuma-dev
sudo apt-get install librbd-dev librdmacm-dev
sudo apt-get install libsasl2-dev libsdl2-dev libseccomp-dev libsnappy-dev libssh-dev
sudo apt-get install libvde-dev libvdeplug-dev libvte-2.91-dev libxen-dev liblzo2-dev
sudo apt-get install valgrind xfslibs-dev 

Newer versions of Debian / Ubuntu might also try these additional packages:

sudo apt-get install libnfs-dev libiscsi-dev

For Red Hat Enterprise Linux or CentOS some of the additional recommended packages can be installed like this:

sudo yum install libaio-devel libcap-ng-devel libiscsi-devel capstone-devel \
                 gtk3-devel libsdl2-devel vte291-devel ncurses-devel \
                 libseccomp-devel nettle-devel libattr-devel libjpeg-devel \
                 brlapi-devel libgcrypt-devel lzo-devel snappy-devel \
                 librdmacm-devel libibverbs-devel cyrus-sasl-devel libpng-devel \
                 libuuid-devel pulseaudio-libs-devel curl-devel libssh-devel \
                 systemtap-sdt-devel libusbx-devel

SUSE-based distributions

This section refers to SUSE Linux Enterprise, openSUSE Leap, openSUSE Tumbleweed, Gecko and other SUSE-based Linux distributions.

The following command line will provide conditions for building QEMU using its default compiler gcc:

sudo zypper install git-core gcc-c++ make qemu glib2-devel libpixman-1-0-devel

If one wants to build QEMU using clang, the following line must be run as well:

sudo zypper install clang

Some additional debugging tools may be installed using:

sudo zypper install perf valgrind

The command lines from this section are tested on openSUSE Tumbleweed 32-bit fresh installation on an Intel host on March 14th, 2020.

Getting the source code

If you want the latest code, follow the development of the code, work with several versions or maybe even contribute to the code, you will need a local copy of the QEMU code repository which is managed using git.

Get the code like this:

git clone git://git.qemu-project.org/qemu.git

The resulting directory qemu is your QEMU root directory.

Note that when building QEMU from GIT, 'make' will attempt to checkout various GIT submodules.

Simple build and test

QEMU supports builds in this directory (not recommended) or in an extra directory (out-of-tree builds, recommended). There can be any number of out-of-tree builds, so if you plan to make cross builds, debug and release builds, out-of-tree builds are what you need.

Here is my typical build scenario:

# Switch to the QEMU root directory.
cd qemu
# Prepare a native debug build.
mkdir -p bin/debug/native
cd bin/debug/native
# Configure QEMU and start the build.
../../../configure --enable-debug
make
# Return to the QEMU root directory.
cd ../../..

Now let's start a simple test:

bin/debug/native/x86_64-softmmu/qemu-system-x86_64 -L pc-bios

This test runs the QEMU system emulation which boots a PC BIOS.

Simple build and test with KVM

This example will show an in-tree build.

# Switch to the QEMU root directory
cd qemu
# Configure QEMU for x86_64 only - faster build
./configure --target-list=x86_64-softmmu --enable-debug
# Build in parallel - my system has 4 CPUs
make -j4

Getting ready to install a guest OS in a VM:

# Create a disk for the VM
./qemu-img create -f qcow2 test.qcow2 16G
# Download an install ISO - I have Fedora 20
ls -la Fedora-Live-Desktop-x86_64-20-1.iso
-rwxr-xr-x. 1 xxxxx xxxxx 999292928 May  4 16:32

Run QEMU with KVM enabled (w/o VNC):

If you have gtk2-devel installed, this will launch a simple UI and you can install your OS.

x86_64-softmmu/qemu-system-x86_64 -m 1024 -enable-kvm \
-drive if=virtio,file=test.qcow2,cache=none \
-cdrom Fedora-Live-Desktop-x86_64-20-1.iso

Run QEMU with KVM enabled (with VNC):

If you you prefer VNC, try this:

x86_64-softmmu/qemu-system-x86_64 -m 1024 -enable-kvm \
-drive if=virtio,file=test.qcow2,cache=none \
-cdrom Fedora-Live-Desktop-x86_64-20-1.iso \
-vnc :1

Connect using your favorite VNC viewer to localhost:1 and install your OS.

Cross builds

Cross building for non-native architectures is quite common. Hosts/W32 contains a description of cross building for Windows (32 and 64 bit) on Linux hosts. TODO: add more descriptions (32 bit Linux target on a 64 bit Linux host would be useful for build bots).

Docker build

The QEMU build system supports compiling a git clone inside a docker container. With docker installed, for example, it can be started with "make docker-test-quick@ubuntu", to build x86_64-softmmu and aarch64-softmmu targets in a ubuntu instance.

See also Testing/DockerBuild for more information.

Running QEMU on Linux

System emulation

All QEMU system emulation should be working.

User mode emulation

User mode emulation is also supported.

Links