todo: Suggestion to improve Erlang bindings.
[libguestfs.git] / test-tool / libguestfs-test-tool.pod
1 =encoding utf8
2
3 =head1 NAME
4
5 libguestfs-test-tool - Diagnostics for libguestfs
6
7 =head1 SYNOPSIS
8
9  libguestfs-test-tool [--options]
10
11 =head1 DESCRIPTION
12
13 libguestfs-test-tool is a test program shipped with libguestfs to
14 allow you to check basic libguestfs functionality is working.  This is
15 needed because libguestfs occasionally breaks for reasons beyond our
16 control: usually because of changes in the underlying qemu or kernel
17 packages, or the host environment.
18
19 If you suspect a problem in libguestfs, then just run:
20
21  libguestfs-test-tool
22
23 It will print lots of diagnostic messages.
24
25 If it runs to completion successfully, you will see this near the end:
26
27  ===== TEST FINISHED OK =====
28
29 and the test tool will exit with code 0.
30
31 If it fails (and/or exits with non-zero error code), please paste the
32 I<complete, unedited> output of the test tool into a bug report.  More
33 information about reporting bugs can be found on the
34 L<http://libguestfs.org/> website.
35
36 =head1 OPTIONS
37
38 =over 4
39
40 =item B<--help>
41
42 Display short usage information and exit.
43
44 =item B<--qemu qemu_binary>
45
46 If you have downloaded another qemu binary, point this option at the
47 full path of the binary to try it.
48
49 =item B<--qemudir qemu_source_dir>
50
51 If you have compiled qemu from source, point this option at the source
52 directory to try it.
53
54 =item B<-t N>
55
56 =item B<--timeout N>
57
58 Set the launch timeout to C<N> seconds.  The default is 600 seconds
59 (10 minutes) which does not usually need to be adjusted.
60
61 =back
62
63 =head1 TRYING OUT A DIFFERENT VERSION OF QEMU
64
65 If you have compiled another version of qemu from source and would
66 like to try that, then you can use the I<--qemudir> option to point to
67 the qemu source directory.
68
69 If you have downloaded a qemu binary from somewhere, use the I<--qemu>
70 option to point to the binary.
71
72 Note when using these options, you can ignore the business of qemu
73 wrapper scripts (L<guestfs(3)/QEMU WRAPPERS>), since
74 libguestfs-test-tool writes a wrapper script for you if one is needed.
75
76 =head1 TRYING OUT A DIFFERENT KERNEL
77
78 If you are using febootstrap E<ge> 3.8 then you can select which
79 kernel libguestfs tries.  You do this by setting the environment
80 variables C<FEBOOTSTRAP_KERNEL> and/or C<FEBOOTSTRAP_MODULES>.
81
82 Refer to L<febootstrap-supermin-helper(8)/ENVIRONMENT VARIABLES>
83 for further information.
84
85 =head1 SELF-DIAGNOSIS
86
87 Refer to L<guestfs(3)/APPLIANCE BOOT PROCESS> to understand the
88 messages produced by libguestfs-test-tool and/or possible errors.
89
90 =head1 EXIT STATUS
91
92 libguestfs-test-tool returns I<0> if the tests completed without
93 error, or I<1> if there was an error.
94
95 =head1 ENVIRONMENT VARIABLES
96
97 For the full list of environment variables which may affect
98 libguestfs, please see the L<guestfs(3)> manual page.
99
100 =head1 SEE ALSO
101
102 L<guestfs(3)>,
103 L<http://libguestfs.org/>,
104 L<http://qemu.org/>.
105
106 =head1 AUTHORS
107
108 Richard W.M. Jones (C<rjones at redhat dot com>)
109
110 =head1 COPYRIGHT
111
112 Copyright (C) 2009-2011 Red Hat Inc.
113 L<http://libguestfs.org/>
114
115 This program is free software; you can redistribute it and/or modify
116 it under the terms of the GNU General Public License as published by
117 the Free Software Foundation; either version 2 of the License, or
118 (at your option) any later version.
119
120 This program is distributed in the hope that it will be useful,
121 but WITHOUT ANY WARRANTY; without even the implied warranty of
122 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
123 GNU General Public License for more details.
124
125 You should have received a copy of the GNU General Public License
126 along with this program; if not, write to the Free Software
127 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.