All action functions are generated automatically, so there are only
two files you need to edit:
-(1) src/generator.ml: Add your new action, parameters, description,
-etc. to the big list called 'functions' at the top of this file.
+(1) generator/generator_actions.ml: Add your new action, parameters,
+description, etc. to the big list at the top of this file.
(2) Edit/create a C file in daemon/ subdirectory which implements your
'do_action' function. Take a look at one of the numerous examples
appliance/
The qemu appliance, build scripts and so on.
-cat/
- The virt-cat tool.
-
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.
+csharp/
+ Experimental C# bindings.
+
daemon/
The daemon that runs inside the guest and carries out actions.
df/
- The virt-df tool.
-
-edit/
- The virt-edit tool.
+ 'virt-df' command and documentation.
examples/
The examples.
fish/
Guestfish (the command-line program / shell)
+fuse/
+ FUSE (userspace filesystem) built on top of libguestfs.
+
+generator/
+ The crucially important generator, used to automatically
+ generate large amounts of boilerplate C code for things like
+ RPC and bindings.
+
haskell/
Haskell bindings.
+hivex/ [removed in 1.0.85]
+ This used to contain the hivex library for reading and
+ writing Windows Registry binary hive files. This is now
+ available as a separate upstream project.
+
images/
Some guest images to test against. These are gzipped to save
space. You have to unzip them before use.
ocaml/
OCaml bindings.
+php/
+ PHP bindings.
+
po/
- Translations.
+ Translations of simple gettext strings. For translations of
+ longer documents, see po-docs/.
+
+po-docs/
+ The build infrastructure and PO files for translations of
+ manpages and POD files. Eventually this will be combined
+ with the po/ directory, but that is rather complicated.
perl/
Perl bindings.
Regression tests.
rescue/
- The virt-rescue tool.
+ 'virt-rescue' command and documentation.
ruby/
Ruby bindings.
+tools/
+ Command line tools written in Perl (virt-resize and more).
+
src/
Source code to the C library.
- Also contains the crucial generator program.
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
----------------------------------------------------------------------