MegaZeux Development VMs

This page contains VM images for testing MegaZeux (and potentially other software) for non-x86 architectures via QEMU. Each image contains a cloned copy of the MegaZeux Git repository, all tools required to build a local copy of MegaZeux, and a minimalist window environment (i3 in Debian or CTWM in NetBSD) to run MegaZeux in.

The login for all VMs is mzx with the password mzx. The MegaZeux Git repository is located at ~/megazeux (or /megazeux in older images).

This page is currently a work-in-progress. Because of this, they are behind a password; ask Lachesis for it on Discord.

Linux/BSD

About these images

• "Main" architectures usually correspond to existing or future MegaZeux ports and are fairly well-supported by Linux and/or BSD distributions. Linux and BSD ports are omitted from the table for obvious reasons. RISC-V is included in this group, as it is an increasingly relevant Linux (and eventually Android) target.
• "Secondary" architectures do not correspond to existing or future MegaZeux ports, and (with the exception of m68k) are/were primarily used for business servers and workstations. While it's unlikely that MegaZeux will be run natively on most of these platforms, testing on these platforms improves MegaZeux's portability.
• Some VMs do not have working video, or even when they do, will not display anything helpful until late in boot. Switching to the serial console with the menu or Ctrl+Alt+3 helps.
• Compilation and package installation is faster under user emulation (chroot.sh) rather than system emulation (run.sh).
• Some system emulators do not work properly or at all under Windows hosts, or in rare cases even under Linux hosts running via a Windows hypervisor (s390x). Running system emulation via Linux is usually preferable. User emulation only works in Linux.
• Some systems can run images matching their architecture with -enable-kvm to vastly speed things up e.g. an x86_64 system can use this option with the x86 and x86_64 VMs.
• Build times provided were observed using an i7-7700 running QEMU from a hypervisor guest, and are mainly intended to give a sense of scale. These may vary significantly depending on your machine and setup. For platforms where -enable-kvm is relevant, it was not used.
• The current head in ~/megazeux should be the most recent head a full build was tested with.

x86/ARM and other Alpine architectures

This group includes the most common architectures that MegaZeux is run on, x86 and ARM. Secondary architectures that Alpine Linux provides install media for are also included for convenience (loongarch64, ppc64le, and s390x). Aside from ARMel, all of these images are Alpine Linux based.

The RISC-V RV64GC architecture will probably move to this group in the future.

Architecture	Related Ports	Distribution	Options	make unit testworlds	Fails	Other Issues	Image	Links
x86 qemu-system-i386 8.2.7	Windows Mac OS X Android	Alpine Linux 3.20	-m 2048 -smp 4 -hda [...]	4m20s (-j4) 2m11s (-j4) 32s	—	—	243MiB
x86_64 qemu-system-x86_64 8.2.7	Windows macOS Android	Alpine Linux 3.20	-m 2048 -smp 4 -hda [...]	2m59s (-j4) 1m31s (-j4) 21s	—	—	288MiB
ARMel qemu-system-arm 5.2.0	Nintendo DS Nintendo 3DS Raspberry Pi GP2X	Debian Unstable	-M versatilepb -m 256M -cpu arm1176 -kernel [...] -dtb [...] -append "root=/dev/sda1 panic=10" -hda [...] -no-reboot	9m24s 2m44s 27s	—	Testing MZX should be done in system emulation, as several vio tests and the test worlds fail with chroot.sh due to a QEMU bug. The red and blue video components are reversed.	340MiB	QEMU Raspberry Pi kernels and scripts.
ARMv7 qemu-system-arm 8.2.7	Android Raspberry Pi PlayStation Vita Pandora	Alpine Linux 3.20	-M virt -m 2048 -cpu cortex-a15 -smp 4 -kernel [...] -initrd [...] -append "root=/dev/vda3 rootfstype=ext4" -hda [...] -boot c -netdev user,id=eth0 -device virtio-net-device,netdev=eth0 -device virtio-gpu -usb -device usb-ehci,id=ehci -device usb-mouse,bus=ehci.0 -device usb-kbd,bus=ehci.0	3m40s (-j4) 2m34s (-j4) 34s	—	SMP makes boot very slow for some reason. For faster boot (but slower compilation), disable it. Alpine armv7 is equivalent to Debian armhf.	243MiB	See ARM64.
ARM64 qemu-system-aarch64 8.2.7	macOS Android Raspberry Pi Nintendo Switch	Alpine Linux 3.20	-M virt -m 2048 -cpu cortex-a72 -smp 4 -kernel [...] -initrd [...] -append "root=/dev/vda3 rootfstype=ext4" -hda [...] -boot c -netdev user,id=eth0 -device virtio-net-device,netdev=eth0 -device VGA -usb -device usb-ehci,id=ehci -device usb-mouse,bus=ehci.0 -device usb-kbd,bus=ehci.0	4m01s (-j4) 1m54s (-j4) 28s	—	—	286MiB	Debian Wiki (archived) Blog post with more detailed info. (archived) Both of these are outdated; the BIOS image seems to be included out of the box in newer QEMU versions.
LoongArch64 qemu-system-loongarch64 9.1.3	—	Alpine Linux 3.21	-m 2048 -machine virt,pflash0=rom,pflash1=efivars -blockdev node-name=rom,driver=file,read-only=true,filename=/usr/share/edk2/loongarch64/QEMU_EFI.fd -blockdev node-name=efivars,driver=file,filename=efivars.fd -smp cpus=4 -netdev user,id=eth0,hostfwd=tcp::5900-:5900 -net nic,netdev=eth0 -device nec-usb-xhci,id=xhci,addr=0x1b -device usb-tablet,id=tablet,bus=xhci.0,port=1 -device usb-kbd,id=keyboard,bus=xhci.0,port=2 -device virtio-gpu-gl,xres=1280,yres=800 -display gtk,gl=on -drive file=loongarch64.alpine.qcow2,format=qcow2,media=disk	FIXME (-j4) FIXME (-j4) FIXME	—	Slightly slow boot is normal.	276MiB	OpenSUSE LoongArch64 Portal (archived) (archived)
PowerPC 64 LE qemu-system-ppc64 8.2.7	—	Alpine Linux 3.20	-M pseries-8.2 -m 2048 -smp 4,sockets=4,cores=1,threads=1 -hda [...] -device virtio-net-pci,netdev=net0 -netdev user,id=net0	2m09s (-j4) 1m20s (-j4) 22s	—	Video freezes mid-boot, so adding -nographic may be preferable.	257MiB
s390x (IBM Z) qemu-system-s390x 8.2.7	—	Alpine Linux 3.20	-M s390-ccw-virtio -m 4096 -smp 4 -hda [...] -device virtio-net-pci -nographic	FIXME (-j4) FIXME (-j4) FIXME	—	No video. This emulator seems very fragile for some systems/environments.	235MiB

Other main architectures

This group contains all other "main" architectures. Debian is used for these images.

Architecture	Related Ports	Distribution	Options	make unit testworlds	Fails	Other Issues	Image	Links
MIPSeb qemu-system-mips 8.2.7	—	Debian 10.13	-M malta -m 256 -kernel [...] -initrd [...] -append "root=/dev/sda1" -drive [...] -device usb-mouse -device usb-kbd -vga std	45m49s 37m22s 1m20s	—	Use chroot.sh for compilation. Likely the last image for this architecture, as Debian discontinued it.	373MiB	Setup (archived)
MIPSel qemu-system-mipsel 8.2.7	PlayStation Portable	Debian 12.7	-M malta -m 256 -kernel [...] -initrd [...] -append "root=/dev/sda1" -device usb-mouse -device usb-kbd -vga std	76m04s 45m08s 1m26s	—	Use chroot.sh for compilation.	420MiB	Setup (archived)
MIPS64el qemu-system-mips64el 8.2.7	—	Debian 12.7	-M malta -m 2048 -cpu 5KEc -kernel [...] -initrd [...] -append "root=/dev/sda1" -device usb-mouse -device usb-kbd -vga std	111m53s 149m38s 53s	—	Use chroot.sh for compilation.	421MiB	Setup (archived) More info (archived)
PowerPC qemu-system-ppc 6.0.0	Mac OS X Nintendo Wii Nintendo Wii U	Debian Unstable 10.0	-L pc-bios -boot c -M mac99,via=pmu -m 1G -prom-env "boot-device=hd:,\yaboot" -prom-env "boot-args=conf=hd:,\yaboot.conf" -drive [...] -serial stdio -g 1024x768x32	4m50s 1m26s 17s	—	—	459MiB	QEMU Wiki (archived)
PowerPC 64 qemu-system-ppc64 6.0.0	Mac OS X	Debian Unstable 10.0	-L pc-bios -boot c -M mac99,via=pmu -m 2048 -cpu 970fx -prom-env "boot-device=hd:,\yaboot" -prom-env "boot-args=conf=hd:,\yaboot.conf" -drive [...] -serial stdio -g 1024x768x32	3m36s 59s 14s	—	—	483MiB	QEMU Wiki (archived)
RISC-V RV64GC qemu-system-riscv64 8.2.7	—	Debian Unstable	-M virt -smp 4 -m 2048M -kernel uboot.elf -append "console=ttyS0 rw root=/dev/vda1" -object rng-random,filename=/dev/urandom,id=rng0 -device virtio-rng-device,rng=rng0 -device virtio-blk-device,drive=hd0 -drive file=[...],format=qcow2,id=hd0 -device virtio-net-device,netdev=usernet -netdev user,id=usernet,hostfwd=tcp::22222-:22 -device VGA -usb -device usb-ehci,id=ehci -device usb-mouse,bus=ehci.0 -device usb-kbd,bus=ehci.0	3m36s (-j4) 2m59s (-j4) 32s	—	—	542MiB	Debian Wiki RISC-V article (archived)
SuperH SH-4 qemu-sh4 8.2.7 (binfmt-misc)	Sega Dreamcast	Debian Unstable	n/a	2m00s (-j4) 1m05s (-j4) 36s	—	Only works using user emulation right now; use chroot.sh. Since this VM does boot it might be an issue with newer kernels.	283MiB	Building Debian VMs with debootstrap (archived)

Secondary architectures

These architectures do not correspond to any current MegaZeux ports. MegaZeux will probably never run on actual hardware several of these architectures.

Architecture	Related Ports	Distribution	Options	make unit testworlds	Fails	Other Issues	Image	Links
DEC Alpha qemu-system-alpha 5.2.0	—	Debian Unstable 2021-04-17	-m 2048 -kernel [...] -initrd [...] -append "root=/dev/sda3 rw" -drive [...] -device VGA	4m15s 1m09s 14s	—	Use --disable-stack-protector. D-Bus and X11 currently do not work correctly due to alignment issues, so use run.serial.sh.	455MiB	QEMU Wiki (archived)
Motorola 68000 qemu-system-m68k 5.2.0	—	Debian Unstable 2021-04-17	-M q800 -m 1000M -kernel [...] -initrd [...] -append "root=/dev/sda1 rw console=ttyS0 console=tty" -drive [...] -net nic,model=dp83932 -net user -g 800x600x16	4m34s 1m20s 20s	—	—	355MiB	QEMU Wiki (archived)
PA-RISC qemu-system-hppa 5.2.0	—	Debian Unstable 10.0	-m 2048 -accel tcg,thread=multi -smp 4 -drive [...] -global artist.width=800 -global artist.height=600 -serial mon:stdio	34m51s (-j4) 13m02s (-j4) 1m51s	—	Use --disable-stack-protector. Emulation is SLOW! Video doesn't work yet; use run.serial.sh (see setup notes).	432MiB	QEMU Wiki (archived) PA-RISC Linux Wiki - QEMU (archived)
SPARC qemu-system-sparc 6.0.0	—	NetBSD 9.2	-M SS-20 -m 512M -drive [...] -net nic -net user	5m50s 1m26s 25s (a173946a)	—	Use --prefix /usr/pkg --disable-libsdl2. SDL2 works headless but can't find a texture format and is missing -Wl,-rpath. force_bpp=16 will match colors to the nearest indexed colors. May hang during IO operations, but so far this has only happened with pkgsrc.	358MiB	QEMU Wiki (archived)
SPARC64 qemu-system-sparc64 6.0.0	—	NetBSD 9.2	-m 2048M -drive [...] -serial mon:stdio	14m50s 3m38s 33s (a173946a)	—	Use --prefix /usr/pkg --disable-libsdl2. SDL2 works headless but can't find a texture format and is missing -Wl,-rpath. force_bpp=16 will match colors to the nearest indexed colors.	439MiB	QEMU Wiki (archived)

Setup

If (for whatever reason) you want to set up your own VM images or a similarly configured machine, this is how the VM images above were generated.

Base image

Alpine Linux or Debian GNU/Linux are assumed in most of these steps, but they can be adapted to other distros. If one of the alternate setups is required, skip the installer steps in this section. NetBSD, which can be used for some architectures, is covered separately.

1. Set up initial QEMU disk image.

   qemu-img create -f qcow2 arch.debian10.qcow2 20G
   

2. Extract installation media vmlinux/initrd from ISO (if needed) and set up initial install.sh script.
3. Run installer. Leave root password blank, create user mzx with password mzx and sudo/doas access. Do not install a desktop environment.
4. If needed, extract runtime vmlinux/vmlinuz/initrd from the virtual machine (required for ARM, MIPS, RISC-V, Alpha, m68k, and SH-4). The easiest way to do this is to use the guestfish utility from libguestfs.

   guestfish --ro -a arch.debian10.qcow2 -i
   

   Then:

   copy-out /boot/vmlinux-X.XX.X-X-ARCH .
   copy-out /boot/initrd.img-X.XX.X-X-ARCH .
   

5. Set up a shell script to run the VM with QEMU, if you haven't already. The older development VM images have separate run.serial.sh and run.sh scripts as needed, but it is now preferred to have one run.sh script that can run on serial when provided -nographic. This script should not use the option -enable-kvm by default; this should be provided by the user.

Environment setup

1. Set up basic editing utils (these may be preinstalled):

   # Debian
   sudo apt install nano
   

   # Alpine
   doas apk add nano
   

2. Set up /bin/l (chmod +x).

   #!/bin/sh
   
   LC_COLLATE="C" \
   ls -la --color=always --group-directories-first "$@"
   

3. Enable the community repository in Alpine Linux by editing /etc/apk/repositories and uncommenting the community repository URL.
4. Update packages.

   # Debian
   sudo apt update
   sudo apt upgrade
   

   # Alpine
   doas apk update
   doas apk upgrade
   

Setup MegaZeux

1. Install packages for the tools and dependencies required to build MegaZeux:

   # Debian
   sudo apt install build-essential pkgconf gdb git zlib1g-dev libpng-dev libogg-dev libvorbis-dev libsdl2-dev
   

   # Alpine
   doas apk add build-base pkgconf gdb git zlib-dev libpng-dev libogg-dev libvorbis-dev sdl2-dev
   

2. Set up MegaZeux repository:

   cd ~
   git clone https://github.com/AliceLR/megazeux
   

3. Build MegaZeux and run the tests. Debug builds are used to measure the times in the table above, as release builds can be quite slow to make in these VMs. Video is not required for any of these steps. The times in the table above were measured without the -enable-kvm option.

   ./config.sh --platform unix-devel --enable-fps [any other flags here]
   time make [use -jX with -smp]
   time make unittest [use -jX with -smp]
   time testworlds/run.sh unix-devel
   

Packaging the VM image

If preparing a VM tarball, some steps should be taken to reduce the size of the image.

1. From the guest OS, clear the apt package cache:

   # Debian
   sudo apt clean
   

   # Alpine
   doas apk cache clean
   

2. Using guestfish from the host OS, fill all unused space in the image with 0s. This will increase the size of the image to its maximum size. (This method seems to be faster than using the dd if=/dev/zero trick some places cite or using zerofree from a guest rescue disk.)

   guestfish --rw -a arch.debian10.qcow2 -i
   

   zero-free-space /
   

3. To shrink your working copy of the image, compact it using qemu-img (and then test it):

   mv arch.debian10.qcow2 arch.debian10.old.qcow2
   qemu-img convert -O qcow2 arch.debian10.old.qcow2 arch.debian10.qcow2
   

4. Finally, generate a compressed tarball containing the image and scripts:

   mkdir arch/
   cp *.sh arch.debian10.qcow2 arch/
   
   # -T1 forces xz to use single-threaded mode, which produces
   # smaller tarballs. This was the default prior to xz 5.6.
   XZ_OPT="-T1 -9" tar -cJf vm-mzx-arch-debian-10.0.tar.xz arch/
   
   # If you have several cores and don't mind using them all, this
   # makes xz use parallel compression to speed things up.
   # The resulting tarball may be significantly larger, though.
   # -T0 is the default as of xz 5.6.
   XZ_OPT="-T0 -9" tar -cJf vm-mzx-arch-debian-10.0.tar.xz arch/
   

Extra software

The following packages might be useful depending on the platform and setup:

• Console utilities:

  # Debian
  sudo apt install dialog screen lm-sensors lynx
  

  # Alpine
  doas apk add bash dialog screen lm-sensors lynx
  

• Extra tools for building libxmp and xmp-cli from source.

  # Debian
  sudo apt install autoconf automake libtool
  

  # Alpine
  doas apk add autoconf automake libtool
  

• clang may be useful for its sanitizers and built-in fuzzer, but it is quite large. It is better to install this after preparing and archiving the initial VM image.

  # Debian
  sudo apt install clang clang-tools llvm
  

  # Alpine
  doas apk add clang clang-tools llvm compiler-rt
  

• If this machine or VM is going to be shelled into:

  # Debian
  sudo apt install openssh-server
  

  # Alpine (note: you can just set this up during setup-alpine)
  doas apk add openssh-server
  

• If memory compression is required:

  # Debian
  sudo apt install zram-tools
  

Graphical environment

Most architectures should use Sway as it is modern, has a smaller disk footprint, and seems more responsive in QEMU. For real hardware with very old integrated graphics, Sway may not work at all, and i3 should be used instead.

MIPSeb, MIPSel, and MIPS64el: the bochs-drm driver has a bug that prevents Sway from working. Use i3 instead.

1. Debian only: block the installation of dmenu. This is an unnecessary application launcher that will be replaced by wmenu or rofi. This is done by:

   echo '
   Package: suckless-tools
   Pin: origin *
   Pin-Priority: -1
   ' | sudo tee /etc/apt/preferences.d/no_goosesteppers
   

2. Sway is the preferred graphical environment for these virtual machines, as it is fairly lightweight and runs well in a VM. In some hardware cases it may be less buggy than X11 (encountered on AML-S905X-CC v1). For Alpine Linux, please follow their detailed setup guide for setting up eudev, seatd, and $XDG_RUNTIME_DIR. Do not use the setup-desktop script, as it will install unnecessary software such as Firefox which will bloat the image (remember, there are nearly 20 of these images).

   # Debian
   sudo apt install sway xwayland foot wmenu i3status fonts-dejavu
   
   # wmenu is only present in Debian 13+. For Debian 12, use rofi instead:
   sudo apt install rofi
   

   # Alpine
   doas apk add sway xwayland foot wmenu swaylock swaylockd swaybg grim wl-clipboard i3status swayidle font-dejavu
   
   # If using virtio-gpu:
   doas apk add mesa-dri-gallium
   

   Copy the config file and edit it:

   mkdir -p ~/.config/sway
   cp /etc/sway/config ~/.config/sway/config
   

3. An alternative is i3, which is X11 based. For Alpine Linux, please follow their detailed setup guide for setting up Xorg and dbus.

   # Debian
   sudo apt install xorg i3-wm i3lock i3status rofi rxvt-unicode fonts-dejavu
   

   # Alpine
   doas apk add i3wm i3lock i3status rofi rxvt-unicode font-dejavu
   

   The config file will be installed to ~/.config/i3/config on the first run.

4. You may need to preset various user roles to use a graphical desktop:

   # Debian
   sudo usermod -a -G video [user]
   sudo usermod -a -G audio [user]
   sudo usermod -a -G input [user]
   

   # Alpine
   doas adduser [user] video
   doas adduser [user] audio
   doas adduser [user] input
   

5. A launcher for i3 and/or Sway might be useful. By default, these installations use TDM, a lightweight terminal-based startx wrapper (which also supports Wayland), but this can be done in several ways.
   • Set up tdm:

     cd ~
     git clone https://github.com/dopsi/console-tdm
     cd console-tdm
     

     # Debian
     sudo apt install dialog
     sudo make install
     

     # Alpine
     doas apk add bash dialog
     doas make install
     

     For each user that will be using tdm:

     tdmctl init
     # You can skip whichever of these window managers isn't present.
     tdmctl add i3 /usr/bin/i3
     tdmctl add sway /usr/bin/sway extra
     

     Place the following in .profile (Alpine) or .bashrc (Debian):

     # Optional: Sway hardware cursors may not work in VirtualBox or QEMU.
     # This seems to have been fixed for a while and can safely be omitted.
     export WLR_NO_HARDWARE_CURSORS=1
     
     # Enable tdm when starting on the first VT (Sway-only, from the Alpine wiki).
     if [ -z "$WAYLAND_DISPLAY" ] && [ "$(tty)" = "/dev/tty1" ]; then
       (tdm --disable-long-names && clear) || true
     fi
     
     # Alternatively:
     # Enable tdm when starting either of the first two VTs.
     if [ -z "$DISPLAY" ] && [ -n "$XDG_VTNR" ] && [ "$XDG_VTNR" -le 2 ]; then
       (tdm --disable-long-names && clear) || true
     fi
     

     X11 only: place this in .xinitrc to allow tdm to start the selected X desktop.

     # i3 only: xrdb -merge "$HOME"/.Xresources
     exec tdm --xstart
     

   • For a graphical login, xdm is tolerable in a VM and easy to set up:

     # Debian
     sudo apt install xdm
     

     # Alpine
     doas apk add xdm
     

   • Alternatively, just use "startx" or "sway" manually. In the case of the former, .xinitrc needs to be preset:

     xrdb -merge "$HOME"/.Xresources
     exec i3
     

6. X11 only: Debian makes xterm default instead of urxvt, so fix that:

   sudo update-alternatives --config x-terminal-emulator
   

   Set up ~/.Xresources from here. This is required to make urxvt not look awful.

   cd ~
   wget https://www.digitalmzx.com/lachesis/.Xresources
   

7. If applicable, update the run.sh script and make sure the VM can start up with graphics and run MegaZeux with the software renderer. This may take some trial and error to get right, which is why QEMU options that have worked in the past are provided in the above tables.

PowerPC/PPC64 (Debian Unstable)

Setting up working Debian Unstable builds for PowerPC/PPC64 currently requires a little bit of extra work.

1. ^^ An old image supporting Yaboot is currently required because all Debian Unstable PPC/PPC64 installers based on grub-ieee1275 have major installation issues (as of 2021-05-09). Skip setting up an apt repository, then add this to /etc/apt/sources.list, sudo apt update, and sudo apt dist-upgrade:

deb [trusted=yes] http://ftp.debian.org/debian-ports sid main

Install the following packages afterward to get the installation roughly equivalent to a standard install.

sudo apt install wget curl ftp gnupg debian-keyring debian-archive-keyring

Remove the old kernel and some large dependencies pulled in by mailutils (not required for these VMs):

sudo apt remove linux-image-4.16.0-1-*
sudo apt remove mailutils --purge
sudo apt autoremove --purge

2. ^ The version of Yaboot in older Debian Unstable PPC64 installers does not support ext4 (even though the equivalent PowerPC installer Yaboot does). Use manual partitioning instead of guided partitioning to create an ext2 /boot partition:

#1 Apple
#2 1.0 MB boot
#3 256.0 MB ext2 /boot
#4 (drive size - 2GB - 258MB) ext4 /
#5 2.0 GB swap

PA-RISC (Debian Unstable)

1. ^ The Debian Installer in newer installer images crashes prior to partitioning. Like PowerPC, an older image needs to be installed, followed by a dist-update and cleanup. Follow the PowerPC instructions above. Make sure you back up the installed image once you've verified that the installation worked. The upgrade process is slow and will involve trial and error.

2. Optional: upgrading systemd may cause the VM to get stuck in an endless boot loop while attempting to run systemd-timesyncd. It may be beneficial to place holds on the relevant systemd packages until after the initial update.

sudo apt-mark hold libpam-systemd
sudo apt-mark hold libsystemd0
sudo apt-mark hold systemd
sudo apt-mark hold systemd-sysv
sudo apt-mark hold systemd-timesyncd

3. If the sudo apt dist-upgrade fails because of libgcc-s4, do the following, then repeat the sudo apt dist-upgrade.

sudo apt install -o Dpkg::Options::="--force-overwrite" libgcc-s4

4. TODO: due to either Artist emulation bugs in QEMU or a lack of driver support in Linux, running this VM in graphical mode will result in the graphical terminal freezing at a certain point. The boot process will continue as usual and the VM can be used from the serial terminal in this situation. This Xorg config fragment can at least get X to successfully start, but the Artist window will still be frozen.

Section "Device"
 Identifier "Artist"
 Driver "fbdev"
 Option "ShadowFB" "off"
EndSection

Section "Screen"
 Identifier "Screen0"
 Device "Artist"
 DefaultDepth 8
 DefaultFbBpp 8
 SubSection "Display"
  Depth 8
  Modes "800x600_60.00"
 EndSubSection
EndSection

Setup (Debian via chroot)

For most QEMU architectures Debian supports, setting up a virtual machine image via a chroot and debootstrap is faster, less painful, and results in a smaller image. For architectures without debian-installer (or with a broken installer, which is often the case for the Ports project), it is necessary.

^^^ No Debian Installer image is available for this architecture and it must be set up manually.

Once this section is completed, it should be possible to follow the normal Linux setup guide without further modifications.

1. Install debootstrap, qemu-user-static, and debian-ports-archive-keyring. If you aren't using Debian as a host, debian-ports-archive-keyring is available here.

2. qemu-img create -f qcow2 [arch here].debian12.qcow2 16G
   mkdir root/

3. As root:

   modprobe nbd
   qemu-nbd -c /dev/nbd0 [arch here].debian12.qcow2
   parted -s -a optimal -- /dev/nbd0 mklabel msdos mkpart primary ext4 1MiB -2GiB mkpart primary linux-swap -2GiB -0
   mkfs -t ext4 -L root /dev/nbd0p1
   mkswap -L swap /dev/nbd0p2
   mount /dev/nbd0p1 root/
   

   Run debootstrap to create an initial user environment:

   # For ARMel:
   debootstrap --arch armel bookworm root/ https://ftp.debian.org/debian
   
   # For MIPSel:
   debootstrap --arch mipsel bookworm root/ https://ftp.debian.org/debian
   
   # For MIPS64el:
   debootstrap --arch mips64el bookworm root/ https://ftp.debian.org/debian
   
   # For RISC-V:
   debootstrap --arch riscv64 unstable root/ https://ftp.debian.org/debian
   
   # For SH-4:
   debootstrap --arch sh4 --keyring=/usr/share/keyrings/debian-ports-archive-keyring.gpg unstable root/ http://ftp.ports.debian.org/debian-ports
   

   Finally:

   # If your host environment doesn't have binfmt_misc set up,
   # now is the time to copy qemu-[arch]-static into root/bin/.
   # If your host environment has binfmt_misc set up, no further
   # action is required; the host kernel will be able to run guest
   # executables in the chroot.
   
   umount root/
   qemu-nbd -d /dev/nbd0
   

4. Set up chroot.sh based on this template. You need to edit PLATFORM_IMAGE (and PLATFORM_NBD, if you intend to chroot into multiple images simultaneously).

   #!/bin/sh
   
   echo "usage: sudo ./chroot.sh"
   echo ""
   echo "*** WARNING ***"
   echo "This script is utter garbage and is not guaranteed to be portable."
   echo "Use at your own risk. If your host doesn't have binfmt, copy the"
   echo "appropriate qemu-user-static executable into the image /bin."
   echo ""
   
   [ "$(id -u)" = 0 ] || { echo "error: run as root or with sudo."; exit; }
   
   PLATFORM_IMAGE=[FIXME YOUR ARCH HERE].debian12.qcow2
   PLATFORM_NBD=/dev/nbd0
   PLATFORM_PART="$PLATFORM_NBD"p1
   PLATFORM_ROOT=root
   
   mkdir -p "$PLATFORM_ROOT"
   
   modprobe nbd || { echo "error: failed to initialized nbd module"; exit; }
   
   if qemu-nbd -c "$PLATFORM_NBD" "$PLATFORM_IMAGE"; then
   sleep 1
   	if mount "$PLATFORM_PART" "$PLATFORM_ROOT"; then
   		mount -o bind,ro /dev "$PLATFORM_ROOT"/dev
   		mount -t proc none "$PLATFORM_ROOT"/proc
   		mount -t sysfs none "$PLATFORM_ROOT"/sys
   
   		chroot "$PLATFORM_ROOT" /bin/bash --login
   
   		umount "$PLATFORM_ROOT"/dev "$PLATFORM_ROOT"/proc "$PLATFORM_ROOT"/sys "$PLATFORM_ROOT"
   	else
   		echo "error: failed to mount partition '$PLATFORM_PART' to '$PLATFORM_ROOT'"
   	fi
   	qemu-nbd -d "$PLATFORM_NBD"
   else
   	echo "error: failed to bind '$PLATFORM_IMAGE' to '$PLATFORM_NBD'"
   fi
   

5. Execute sudo ./chroot.sh to initialize qemu-nbd, mount the root partition to root/, and chroot into it.

   # Verify machine name is armv7l (ARMel), mips (MIPSel), mips64 (MIPS64el), riscv64 (RISC-V), or sh4 (SH-4).
   # Note that the kernel string will still contain the host architecture e.g. x86_64!
   uname -a
   

6. Edit /etc/fstab:

   LABEL=swap none swap sw 0 0
   LABEL=root / ext4 defaults 0 1
   

   Edit /etc/hostname:

   [arch name here]
   

   Edit /etc/hosts and add at the beginning:

   127.0.0.1    [arch name here]
   

   Create /etc/network/interfaces.d/eth0 (NOTE: for mipsel and mips64el, replace eth0 with enp0s11):

   # This is the device name used by Debian and is needed for QEMU system emulation.
   allow-hotplug eth0
   iface eth0 inet dhcp
   

   Create /etc/network/interfaces.d/enp1s0:

   # This allows networking to work from a chroot from Fedora.
   allow-hotplug enp1s0
   iface enp1s0 inet dhcp
   

   Create /etc/network/interfaces.d/lo:

   # This configures the loopback interface.
   # This breaks booting in ARMel and can be omitted for that platform.
   auto lo
   iface lo inet loopback
   

7. Install and configure some required packages:

   # If this architecture is from the Debian Ports project, this needs to be installed first.
   # Officially supported architectures can ignore this step.
   apt install debian-ports-archive-keyring
   
   apt install sudo locales openntpd ntpdate
   
   # These images generally use US/Mountain or America/Denver, depending on what is available.
   dpkg-reconfigure tzdata
   
   # Only select en_US.UTF-8 here; others can be added later if needed.
   dpkg-reconfigure locales
   
   # You may need to edit /etc/defaults/openntpd and add "-s" to the end of DAEMON_OPTS.
   
   systemctl enable serial-getty@ttyS0.service
   

8. Setup user:

   adduser mzx
   usermod -a -G sudo mzx
   passwd -l root
   

9. Set up a kernel and bootloader. This is different for each architecture.
   • ARMel: get a Raspberry Pi Linux kernel (4.19.50) and versatile-pb-buster.dtb here.
   • MIPSel:

     apt install linux-image-4kc-malta
     

     Copy out the kernel and initrd from the image /boot directory into the VM directory. These will be provided as the arguments for -kernel and -initrd.

   • MIPS64el:

     apt install linux-image-5kc-malta
     

     Copy out the kernel and initrd from the image /boot directory into the VM directory. These will be provided as the arguments for -kernel and -initrd.

   • RISC-V:

     apt install linux-image-riscv64
     
     # Also, some extra things to do here (see Debian Wiki RISC-V page):
     apt install u-boot-menu u-boot-qemu
     echo '
     UBOOT_PARAMETERS="rw noquiet root=/dev/vda"
     U_BOOT_FDT_DIR="noexist"' >> /etc/default/u-boot
     u-boot-update
     

     Copy /usr/lib/u-boot/qemu-riscv64_smode/uboot.elf out of the image into the VM directory. This will serve as the argument to -kernel and is required to boot the virtual machine.

   • SH-4:

     apt install linux-image-sh7751r
     

Setup (NetBSD)

^^ Setting up NetBSD is a little more involved than Debian. Note NetBSD also isn't aware of power management for some architectures and will use a full core while its VM is running.

1. Set up initial QEMU disk image.

   qemu-img create -f qcow2 arch.netbsd.qcow2 20G
   

2. For whatever reason, the QEMU -kernel option doesn't seem to work with any BSD kernels, so right now any QEMU that requires -kernel should use a Linux instead.
3. Run installer. Leave root password blank, create user mzx with password mzx and sudo access (if it doesn't give you the option, set the root password). Install all packages, including the X window system. Enable xdm and nptdate. If network autodetection doesn't work here (SPARC 32-bit), pkgin and pkgsrc will need to be set up manually after reboot. Otherwise, install both.
4. Set up run.serial.sh script and run.
5. As root, set up /bin/l:

   echo '#!/bin/sh
   
   LC_COLLATE="C" \
   ls -la "$@"' > /bin/l
   chmod a+x /bin/l
   

6. As root, set a hostname, disable IPv6, enable DHCP (if it isn't already), and reboot:

   # Set a hostname for this architecture e.g. SPARC, SPARC64, ARMv6.
   echo "SPARC" > /etc/myname
   
   # Disable IPv6 for DHCP.
   # This prevents issues where all downloads can hang for a long time before
   # the download starts (due to attempting IPv6 first and it timing out).
   cp /etc/dhcpcd.conf ~/
   echo '
   # Disable IPv6 Support.
   noipv6rs
   noipv6' >> /etc/dhcpcd.conf
   
   # If it wasn't enabled during install, you can enable DHCP like this.
   cp /etc/rc.conf ~/
   echo "dhcpcd=yes" >> /etc/rc.conf
   
   # Reboot for these changes to take effect.
   reboot
   

7. If network wasn't available during installation, manually install pkgsrc. As root:

   ftp http://ftp.netbsd.org/pub/pkgsrc/current/pkgsrc.tar.gz
   tar -xzf pkgsrc.tar.gz -O /usr
   chown root:wheel -R /usr/pkgsrc
   

8. If network wasn't available during installation, manually install pkgin. As root:

   # Replace ARCH and VERSION for the applicable architecture (e.g. sparc) and version (e.g. 9.2).
   pkg_add http://cdn.netbsd.org/pub/pkgsrc/packages/NetBSD/ARCH/VERSION/All/pkgin
   

9. As root, install packages with pkgin:

   pkgin install doas bash gmake pkgconf git nano zip
   pkgin install zlib png libogg libvorbis SDL SDL2
   pkgin install lynx openssl ca-certificates
   

   Configure doas:

   echo 'permit nopass :wheel' >>/usr/pkg/etc/doas.conf
   

   If precompiled packages aren't available for this architecture, use pkgsrc to build and install these packages instead. WARNING: this will take a while.

10. When configuring MegaZeux, make sure to use /usr/pkg as the prefix and to use gmake to invoke Makefile targets.
11. Preparing the image is a little different from Debian, mainly since the Linux kernel does not have write support for NetBSD's filesystem by default. As root, clear the pkgin cache and zero free space.

    pkgin clean
    cat /dev/zero >delet_this
    sync
    rm delet_this
    

    If pkgsrc was used, make sure there are no work directories leftover in the pkgsrc tree (TODO).

    The image is now ready to be shrunk with qemu-img.

Links

1. NetBSD networking FAQ (archived).

2. NetBSD pkgsrc guide (archived).