xref: /kvm-unit-tests/README (revision cf44bb89c6e5e5244e675f52ded43eb466730bbd) 
1# Welcome to kvm-unit-tests
2
3See http://www.linux-kvm.org/page/KVM-unit-tests for a high-level
4description of this project, as well as running tests and adding
5tests HOWTOs.
6
7# Building the tests
8
9This directory contains sources for a kvm test suite.
10
11To create the test images do:
12
13    ./configure
14    make
15
16in this directory. Test images are created in ./<ARCH>/*.flat
17
18## Standalone tests
19
20The tests can be built as standalone
21To create and use standalone tests do:
22
23    ./configure
24    make standalone
25    (send tests/some-test somewhere)
26    (go to somewhere)
27    ./some-test
28
29'make install' will install all tests in PREFIX/share/kvm-unit-tests/tests,
30each as a standalone test.
31
32
33# Running the tests
34
35Then use the runner script to detect the correct invocation and
36invoke the test:
37
38    ./x86-run ./x86/msr.flat
39or:
40
41    ./run_tests.sh
42
43to run them all.
44
45To select a specific qemu binary, specify the QEMU=<path>
46environment variable:
47
48    QEMU=/tmp/qemu/x86_64-softmmu/qemu-system-x86_64 ./x86-run ./x86/msr.flat
49
50# Contributing
51
52## Directory structure
53
54    .:				configure script, top-level Makefile, and run_tests.sh
55    ./scripts:		helper scripts for building and running tests
56    ./lib:			general architecture neutral services for the tests
57    ./lib/<ARCH>:	architecture dependent services for the tests
58    ./<ARCH>:		the sources of the tests and the created objects/images
59
60See <ARCH>/README for architecture specific documentation.
61
62## Style
63
64Currently there is a mix of indentation styles so any changes to
65existing files should be consistent with the existing style. For new
66files:
67
68  - C: please use standard linux-with-tabs
69  - Shell: use TABs for indentation
70
71## Patches
72
73Patches are welcome at the KVM mailing list <kvm@vger.kernel.org>.
74
75Please prefix messages with: [kvm-unit-tests PATCH]
76
77You can add the following to .git/config to do this automatically for you:
78
79    [format]
80        subjectprefix = kvm-unit-tests PATCH
81
82Additionally it's helpful to have a common order of file types in patches.
83Our chosen order attempts to place the more declarative files before
84the code files. We also start with common code and finish with unit test
85code. git-diff's orderFile feature allows us to specify the order in a
86file. The orderFile we use is `scripts/git.difforder`. Adding the config
87with `git config diff.orderFile scripts/git.difforder` enables it.
88