Update fingerprint test and introduce a script to generate fingerprints
[qemu-test.git] / README
1 Build
2 -----
3
4 qemu-test will build a Linux kernel and initramfs based on busybox.  The
5 initramfs will pull in your local glibc.
6
7 Since the initrd and kernel are git submodules, you need to first fetch the
8 submodules:
9
10     $ git submodule update --init
11
12 To build the initrd and kernel, do:
13
14     $ make
15
16 Once the modules are built, you can issue a *make clean* to clean up the working
17 directory.  *make clean* will not remove the final kernel/initramfs.
18
19 Running Tests
20 -------------
21
22 To run a new test, execute:
23
24     $ ./qemu-test ~/build/qemu/x86_64-softmmu/qemu-system-x86_64 \
25                   tests/no-vga-pci-allocation.sh
26
27 The first argument is the QEMU executable to use.  The second is the test shell
28 script.
29
30 If you get an error about QEMU_SRC not being set, you'll need to set the
31 QEMU_SRC environment variable to point to your qemu.git tree.  It should be at
32 least qemu-1.0.
33
34 Writing New Tests
35 -----------------
36
37 Each test is a single shell script.  If the environmental variable QEMU_TEST is
38 set, then the shell script is being used to launch qemu.  If it is not set, then
39 the shell script is running in the guest and can be used to run guest code.
40
41 In both cases, failure is indicated by exiting with a non-zero exit status.
42
43 When running in the host, the following commands are avaiable:
44
45 - qmp  -- execute a qmp command.  'qmp human-monitor-command' can be used to
46           execute HMP commands.
47
48 - qemu -- a light wrapper around the user supplied qemu executable.
49
50 The qemu wrapper tracks standard output from the test and implements a timeout.
51 If no new text appears on stdout after 10 seconds, the guest is assumed to be
52 hung.  Please write your tests accordingly.
53
54 The wrapper also constantly interacts with QMP attempting to detect when QEMU
55 itself is locked up.
56
57 Submitting Tests
58 ----------------
59
60 Send new tests to qemu-devel@nongnu.org
61
62 Tips on Writing New Tests
63 -------------------------
64
65 - Tests should fail and pass as quickly as possible
66 - Running a test should test one piece of functionality.  If you want to test
67   multiple scenarios in one test file, consider using $RANDOM to choose which
68   scenario is run.