The qemu appliance, build scripts and so on.
capitests/
- Automated tests of the C API.
+ Automated tests of the C API. See "Tests" below.
+
+cat/
+ The 'virt-cat', 'virt-filesystems' and 'virt-ls' commands and
+ documentation.
contrib/
Outside contributions, experimental parts.
daemon/
The daemon that runs inside the guest and carries out actions.
+df/
+ 'virt-df' command and documentation.
+
examples/
The examples.
ocaml/
OCaml bindings.
+php/
+ PHP bindings.
+
po/
Translations of simple gettext strings. For translations of
longer documents, see po-docs/.
regressions/
Regression tests.
+rescue/
+ 'virt-rescue' command and documentation.
+
ruby/
Ruby bindings.
tools/
- Command line tools like virt-cat, virt-df, virt-edit and more.
- In versions <= 1.0.73 these were all in separate directories
- like cat/, df/, edit/, but since then we moved them all into
- one directory to simplify builds.
+ Command line tools written in Perl (virt-resize and more).
src/
Source code to the C library.
test-tool/
Interactive qemu/kernel test tool.
+Tests
+----------------------------------------------------------------------
+
+You can supply zero or as many tests as you want per API call.
+
+The test environment has 4 block devices:
+ /dev/sda 500MB General block device for testing.
+ /dev/sdb 50MB /dev/sdb1 is an ext2 filesystem used for testing
+ filesystem write operations.
+ /dev/sdc 10MB Used in a few tests where 2 block devices are needed.
+ /dev/sdd - ISO with fixed content (see images/test.iso).
+
+To be able to run the tests in a reasonable amount of time, the
+virtual machine and block devices are reused between tests. So don't
+try testing kill_subprocess :-x Between each test we blockdev-setrw,
+umount-all, lvm-remove-all.
+
+Each test starts with an initial scenario, selected using one of the
+'Init*' expressions, described in generator/generator_types.ml. These
+initialize the disks in a particular way as described. You should not
+assume anything about the previous contents of other disks that are
+not initialized.
+
+You can add a prerequisite clause to any individual test. This is a
+run-time check, which, if it fails, causes the test to be skipped.
+Useful if testing a command which might not work on all variations of
+libguestfs builds. A test that has prerequisite of 'Always' is run
+unconditionally.
+
+In addition, packagers can skip individual tests by setting the
+environment variables: eg:
+
+ SKIP_TEST_<CMD>_<NUM>=1 SKIP_TEST_COMMAND_3=1 (skips test #3 of command)
+ SKIP_TEST_<CMD>=1 SKIP_TEST_ZEROFREE=1 (skips all zerofree tests)
+
+and packagers can run only certain tests by setting eg:
+
+ TEST_ONLY="vfs_type zerofree"
+
+See capitests/tests.c for more details of how these environment
+variables work.
+
Debugging
----------------------------------------------------------------------