=== VM test suite to run build in guests === == Intro == This test suite contains scripts that bootstrap various guest images that have necessary packages to build QEMU. The basic usage is documented in Makefile help which is displayed with "make vm-test". == Quick start == Run "make vm-test" to list available make targets. Invoke a specific make command to run build test in an image. For example, "make vm-build-freebsd" will build the source tree in the FreeBSD image. The command can be executed from either the source tree or the build dir; if the former, ./configure is not needed. The command will then generate the test image in ./tests/vm/ under the working directory. Note: images created by the scripts accept a well-known RSA key pair for SSH access, so they SHOULD NOT be exposed to external interfaces if you are concerned about attackers taking control of the guest and potentially exploiting a QEMU security bug to compromise the host. == QEMU binary == By default, qemu-system-x86_64 is searched in $PATH to run the guest. If there isn't one, or if it is older than 2.10, the test won't work. In this case, provide the QEMU binary in env var: QEMU=/path/to/qemu-2.10+. == Make jobs == The "-j$X" option in the make command line is not propagated into the VM, specify "J=$X" to control the make jobs in the guest. == Debugging == Add "DEBUG=1" and/or "V=1" to the make command to allow interactive debugging and verbose output. If this is not enough, see the next section. == Manual invocation == Each guest script is an executable script with the same command line options. For example to work with the netbsd guest, use $QEMU_SRC/tests/vm/netbsd: $ cd $QEMU_SRC/tests/vm # To bootstrap the image $ ./netbsd --build-image --image /var/tmp/netbsd.img <...> # To run an arbitrary command in guest (the output will not be echoed unless # --debug is added) $ ./netbsd --debug --image /var/tmp/netbsd.img uname -a # To build QEMU in guest $ ./netbsd --debug --image /var/tmp/netbsd.img --build-qemu $QEMU_SRC # To get to an interactive shell $ ./netbsd --interactive --image /var/tmp/netbsd.img sh == Adding new guests == Please look at existing guest scripts for how to add new guests. Most importantly, create a subclass of BaseVM and implement build_image() method and define BUILD_SCRIPT, then finally call basevm.main() from the script's main(). - Usually in build_image(), a template image is downloaded from a predefined URL. BaseVM._download_with_cache() takes care of the cache and the checksum, so consider using it. - Once the image is downloaded, users, SSH server and QEMU build deps should be set up: * Root password set to BaseVM.ROOT_PASS * User BaseVM.GUEST_USER is created, and password set to BaseVM.GUEST_PASS * SSH service is enabled and started on boot, $QEMU_SRC/tests/keys/id_rsa.pub is added to ssh's "authorized_keys" file of both root and the normal user * DHCP client service is enabled and started on boot, so that it can automatically configure the virtio-net-pci NIC and communicate with QEMU user net (10.0.2.2) * Necessary packages are installed to untar the source tarball and build QEMU - Write a proper BUILD_SCRIPT template, which should be a shell script that untars a raw virtio-blk block device, which is the tarball data blob of the QEMU source tree, then configure/build it. Running "make check" is also recommended.