This Docker image sets up a container to build QEMU AppImages.
To use docker-qemu-appimage, run the container. Any argument will be passed
to the configure script before compiling QEMU:
-
Clone and start the container:
docker run -v "${PWD}"/output:/output \ docker.io/aguslr/qemu-appimage:latest --target-list=i386-softmmu -
Run the generated AppImage in
./output:./output/qemu-system-i386-*.AppImage --version
There are two flavors for this docker container:
-
full,latest: Provides libraries to enable most QEMU features. To disable any unwanted feature, arguments (e.g.--disable-gtk) must be passed to the container image. -
slim: Provides libraries to enable basic QEMU functionality (e.g., graphics, audio, networking, USB, SPICE/VNC server, etc.)
The image is configured using environment variables passed at runtime:
| Variable | Function | Default | Required |
|---|---|---|---|
APP_NAME |
Name of the app to package | qemu-system-* |
N |
QEMU_VER |
Version of QEMU to compile | 8.2.0 |
N |
QEMU_OPTS |
Custom QEMU runtime options | EMPTY | N |
Here's an example to create an AppImage for a Pentium 3 machine with 64 MB of RAM:
docker run --rm -e APP_NAME='Pentium 3' -e QEMU_VER='7.2.1' \
-e QEMU_OPTS='qemu-system-i386 -cpu pentium 3 -m 64' \
-v "${PWD}"/output:/output \
docker.io/aguslr/qemu-appimage:latest --target-list=i386-softmmu && \
./output/qemu-system-i386-7.2.1-x86_64.AppImage --help
Any argument for the container image will be passed to the configure
script used to enable or disable QEMU features at build time. For QEMU
version 8.2.0, these are the available options:
Options
Usage: configure [options]
Options: [defaults in brackets after descriptions]
Standard options:
--help print this message
--target-list=LIST set target list (default: build all)
Available targets: aarch64-softmmu alpha-softmmu
arm-softmmu avr-softmmu cris-softmmu hppa-softmmu
i386-softmmu loongarch64-softmmu m68k-softmmu
microblaze-softmmu microblazeel-softmmu mips-softmmu
mips64-softmmu mips64el-softmmu mipsel-softmmu
nios2-softmmu or1k-softmmu ppc-softmmu ppc64-softmmu
riscv32-softmmu riscv64-softmmu rx-softmmu
s390x-softmmu sh4-softmmu sh4eb-softmmu
sparc-softmmu sparc64-softmmu tricore-softmmu
x86_64-softmmu xtensa-softmmu xtensaeb-softmmu
--target-list-exclude=LIST exclude a set of targets from the default target-list
Advanced options (experts only):
-Dmesonoptname=val passthrough option to meson unmodified
--cross-prefix=PREFIX use PREFIX for compile tools, PREFIX can be blank []
--cc=CC use C compiler CC [cc]
--host-cc=CC when cross compiling, use C compiler CC for code run
at build time [cc]
--cxx=CXX use C++ compiler CXX [c++]
--objcc=OBJCC use Objective-C compiler OBJCC [cc]
--extra-cflags=CFLAGS append extra C compiler flags CFLAGS
--extra-cxxflags=CXXFLAGS append extra C++ compiler flags CXXFLAGS
--extra-objcflags=OBJCFLAGS append extra Objective C compiler flags OBJCFLAGS
--extra-ldflags=LDFLAGS append extra linker flags LDFLAGS
--cross-cc-ARCH=CC use compiler when building ARCH guest test cases
--cross-cc-cflags-ARCH= use compiler flags when building ARCH guest tests
--cross-prefix-ARCH=PREFIX cross compiler prefix when building ARCH guest test cases
--python=PYTHON use specified python [/usr/bin/python3]
--ninja=NINJA use specified ninja []
--static enable static build [no]
--without-default-features default all --enable-* options to "disabled"
--without-default-devices do not include any device that is not needed to
start the emulator (only use if you are including
desired devices in configs/devices/)
--with-devices-ARCH=NAME override default configs/devices
--enable-debug enable common debug build options
--cpu=CPU Build for host CPU [x86_64]
--disable-containers don't use containers for cross-building
--container-engine=TYPE which container engine to use [auto]
--gdb=GDB-path gdb to use for gdbstub tests []
--audio-drv-list=CHOICES Set audio driver list [default] (choices: alsa/co
reaudio/default/dsound/jack/oss/pa/pipewire/sdl/s
ndio)
--bindir=VALUE Executable directory [bin]
--block-drv-ro-whitelist=VALUE
set block driver read-only whitelist (by default
affects only QEMU, not tools like qemu-img)
--block-drv-rw-whitelist=VALUE
set block driver read-write whitelist (by default
affects only QEMU, not tools like qemu-img)
--datadir=VALUE Data file directory [share]
--disable-coroutine-pool coroutine freelist (better performance)
--disable-debug-info Enable debug symbols and other information
--disable-hexagon-idef-parser
use idef-parser to automatically generate TCG
code for the Hexagon frontend
--disable-install-blobs install provided firmware blobs
--disable-qom-cast-debug cast debugging support
--disable-relocatable toggle relocatable install
--docdir=VALUE Base directory for documentation installation
(can be empty) [share/doc]
--enable-block-drv-whitelist-in-tools
use block whitelist also in tools instead of only
QEMU
--enable-cfi Control-Flow Integrity (CFI)
--enable-cfi-debug Verbose errors in case of CFI violation
--enable-debug-graph-lock
graph lock debugging support
--enable-debug-mutex mutex debugging support
--enable-debug-stack-usage
measure coroutine stack usage
--enable-debug-tcg TCG debugging
--enable-fdt[=CHOICE] Whether and how to find the libfdt library
(choices: auto/disabled/enabled/internal/system)
--enable-fuzzing build fuzzing targets
--enable-gcov Enable coverage tracking.
--enable-lto Use link time optimization
--enable-malloc=CHOICE choose memory allocator to use [system] (choices:
jemalloc/system/tcmalloc)
--enable-module-upgrades try to load modules from alternate paths for
upgrades
--enable-rng-none dummy RNG, avoid using /dev/(u)random and
getrandom()
--enable-safe-stack SafeStack Stack Smash Protection (requires
clang/llvm and coroutine backend ucontext)
--enable-sanitizers enable default sanitizers
--enable-strip Strip targets on install
--enable-tcg-interpreter TCG with bytecode interpreter (slow)
--enable-trace-backends=CHOICES
Set available tracing backends [log] (choices:
dtrace/ftrace/log/nop/simple/syslog/ust)
--enable-tsan enable thread sanitizer
--firmwarepath=VALUES search PATH for firmware files [share/qemu-
firmware]
--iasl=VALUE Path to ACPI disassembler
--includedir=VALUE Header file directory [include]
--interp-prefix=VALUE where to find shared libraries etc., use %M for
cpu name [/usr/gnemul/qemu-%M]
--libdir=VALUE Library directory [system default]
--libexecdir=VALUE Library executable directory [libexec]
--localedir=VALUE Locale data directory [share/locale]
--localstatedir=VALUE Localstate data directory [/var/local]
--mandir=VALUE Manual page directory [share/man]
--prefix=VALUE Installation prefix [/usr/local]
--qemu-ga-distro=VALUE second path element in qemu-ga registry entries
[Linux]
--qemu-ga-manufacturer=VALUE
"manufacturer" name for qemu-ga registry entries
[QEMU]
--qemu-ga-version=VALUE version number for qemu-ga installer
--smbd=VALUE Path to smbd for slirp networking
--sysconfdir=VALUE Sysconf data directory [etc]
--tls-priority=VALUE Default TLS protocol/cipher priority string
[NORMAL]
--with-coroutine=CHOICE coroutine backend to use (choices:
auto/sigaltstack/ucontext/windows)
--with-pkgversion=VALUE use specified string as sub-version of the
package
--with-suffix=VALUE Suffix for QEMU data/modules/config directories
(can be empty) [qemu]
--with-trace-file=VALUE Trace file prefix for simple backend [trace]
Optional features, enabled with --enable-FEATURE and
disabled with --disable-FEATURE, default is enabled if available
(unless built with --without-default-features):
af-xdp AF_XDP network backend support
alsa ALSA sound support
attr attr/xattr support
auth-pam PAM access control
avx2 AVX2 optimizations
avx512bw AVX512BW optimizations
avx512f AVX512F optimizations
blkio libblkio block device driver
bochs bochs image format support
bpf eBPF support
brlapi brlapi character device driver
bzip2 bzip2 support for DMG images
canokey CanoKey support
cap-ng cap_ng support
capstone Whether and how to find the capstone library
cloop cloop image format support
cocoa Cocoa user interface (macOS only)
colo-proxy colo-proxy support
coreaudio CoreAudio sound support
crypto-afalg Linux AF_ALG crypto backend driver
curl CURL block device driver
curses curses UI
dbus-display -display dbus support
dmg dmg image format support
docs Documentations build support
dsound DirectSound sound support
fuse FUSE block device export
fuse-lseek SEEK_HOLE/SEEK_DATA support for FUSE exports
gcrypt libgcrypt cryptography support
gettext Localization of the GTK+ user interface
gio use libgio for D-Bus support
glusterfs Glusterfs block device driver
gnutls GNUTLS cryptography support
gtk GTK+ user interface
gtk-clipboard clipboard support for the gtk UI (EXPERIMENTAL, MAY HANG)
guest-agent Build QEMU Guest Agent
guest-agent-msi Build MSI package for the QEMU Guest Agent
hv-balloon hv-balloon driver (requires Glib 2.68+ GTree API)
hvf HVF acceleration support
iconv Font glyph conversion support
jack JACK sound support
keyring Linux keyring support
kvm KVM acceleration support
l2tpv3 l2tpv3 network backend support
libdaxctl libdaxctl support
libdw debuginfo support
libiscsi libiscsi userspace initiator
libkeyutils Linux keyutils support
libnfs libnfs block device driver
libpmem libpmem support
libssh ssh block device support
libudev Use libudev to enumerate host devices
libusb libusb support for USB passthrough
libvduse build VDUSE Library
linux-aio Linux AIO support
linux-io-uring Linux io_uring support
live-block-migration
block migration in the main migration stream
lzfse lzfse support for DMG images
lzo lzo compression support
malloc-trim enable libc malloc_trim() for memory optimization
membarrier membarrier system call (for Linux 4.14+ or Windows
modules modules support (non Windows)
mpath Multipath persistent reservation passthrough
multiprocess Out of process device emulation support
netmap netmap network backend support
nettle nettle cryptography support
numa libnuma support
nvmm NVMM acceleration support
opengl OpenGL support
oss OSS sound support
pa PulseAudio sound support
parallels parallels image format support
pipewire PipeWire sound support
pixman pixman support
plugins TCG plugins via shared library loading
png PNG support with libpng
pvrdma Enable PVRDMA support
qcow1 qcow1 image format support
qed qed image format support
qga-vss build QGA VSS support (broken with MinGW)
rbd Ceph block device driver
rdma Enable RDMA-based migration
replication replication support
rutabaga-gfx rutabaga_gfx support
sdl SDL user interface
sdl-image SDL Image support for icons
seccomp seccomp support
selinux SELinux support in qemu-nbd
slirp libslirp user mode network backend support
slirp-smbd use smbd (at path --smbd=*) in slirp networking
smartcard CA smartcard emulation support
snappy snappy compression support
sndio sndio sound support
sparse sparse checker
spice Spice server support
spice-protocol Spice protocol support
stack-protector compiler-provided stack protection
tcg TCG support
tools build support utilities that come with QEMU
tpm TPM support
u2f U2F emulation support
usb-redir libusbredir support
vde vde network backend support
vdi vdi image format support
vduse-blk-export
VDUSE block export support
vfio-user-server
vfio-user server support
vhdx vhdx image format support
vhost-crypto vhost-user crypto backend support
vhost-kernel vhost kernel backend support
vhost-net vhost-net kernel acceleration support
vhost-user vhost-user backend support
vhost-user-blk-server
build vhost-user-blk server
vhost-vdpa vhost-vdpa kernel backend support
virglrenderer virgl rendering support
virtfs virtio-9p support
virtfs-proxy-helper
virtio-9p proxy helper support
vmdk vmdk image format support
vmnet vmnet.framework network backend support
vnc VNC server
vnc-jpeg JPEG lossy compression for VNC server
vnc-sasl SASL authentication for VNC server
vpc vpc image format support
vte vte support for the gtk UI
vvfat vvfat image format support
werror Treat warnings as errors
whpx WHPX acceleration support
xen Xen backend support
xen-pci-passthrough
Xen PCI passthrough support
xkbcommon xkbcommon support
zstd zstd compression support
system all system emulation targets
user supported user emulation targets
linux-user all linux usermode emulation targets
bsd-user all BSD usermode emulation targets
pie Position Independent Executables
NOTE: The object files are built at the place where configure is launched
The generated AppImages accept these arguments:
| Option | Function |
|---|---|
--command=list |
List available binaries inside AppImage |
--command=<command> |
Run specific binary inside AppImage |
Additionally, AppImages accept a few options by default:
| Option | Function |
|---|---|
--appimage-extract [<pattern>] |
Extract content from embedded filesystem image. If pattern is passed, only extract matching files |
--appimage-help |
Print this help |
--appimage-mount |
Mount embedded filesystem image and print mount point and wait for kill with Ctrl-C |
--appimage-offset |
Print byte offset to start of embedded image |
--appimage-portable-home |
Create a portable home folder to use as $HOME |
--appimage-portable-config |
Create a portable config folder to use as $XDG_CONFIG_HOME |
--appimage-signature |
Print digital signature embedded in AppImage |
--appimage-updateinfo[rmation] |
Print update info embedded in AppImage |
--appimage-version |
Print version of AppImageKit |
Any other argument will be passed directly to the QEMU binary (e.g.,
qemu-system-x86_64).
We can place disk images (QCOW2, ISO, raw images, etc.) or BIOS files (BIN, ROM)
in an input directory and they will be copied and loaded at runtime:
| Filename | Function | Device |
|---|---|---|
bios.rom |
BIOS file | -bios |
fda.img |
Floppy disk | -fda |
cdrom.iso |
CD-ROM | -cdrom |
hda.qcow2 |
Hard drive | -hda |
Note: The hard drive file will be read-only therefore, unless we pass the
-snapshot argument to the AppImage, changes to the disk will be saved to
a QCOW2 image in a directory named after the AppImage inside
${XDG_DATA_HOME}/qemu.appimage (usually ~/.local/share/qemu.appimage).
-
Disable VNC support in QEMU and create an AppImage for a Sun Solaris 9 disk (
./input/hda.qcow2):docker run --rm -e APP_NAME='Solaris 9' \ -e QEMU_OPTS='qemu-system-sparc -M SS-5 -m 256 -vga cg3 -g 1024x768' \ -v "${PWD}"/input:/input -v "${PWD}"/output:/output \ docker.io/aguslr/qemu-appimage:latest \ --target-list=sparc-softmmu --disable-vnc && \ ./output/Solaris_9-8.2.0-x86_64.AppImage -snapshot -monitor stdio
-
Disable PulseAudio and SLiRP support in QEMU and create an AppImage for a Mac OS 9 disk (
./input/hda.qcow2):docker run --rm -e APP_NAME='Mac OS 9.2' \ -e QEMU_OPTS='qemu-system-ppc -machine mac99 -m 256 -nic none -g 1024x768x32' \ -v "${PWD}"/input:/input -v "${PWD}"/output:/output \ docker.io/aguslr/qemu-appimage:latest \ --target-list=ppc-softmmu --disable-pa --disable-slirp && \ ./output/Mac_OS_9.2-8.2.0-x86_64.AppImage -snapshot -vnc :0
Instead of pulling the image from a remote repository, you can build it locally:
-
Clone the repository:
git clone https://github.com/aguslr/docker-qemu-appimage.git -
Change into the newly created directory and use
docker-composeto build and launch the container:cd docker-qemu-appimage && docker-compose up --build -d