out-of-tree build: ruby

[libguestfs.git] / test-tool / libguestfs-test-tool.pod

diff --git a/test-tool/libguestfs-test-tool.pod b/test-tool/libguestfs-test-tool.pod
index df8c77b..9a92861 100644 (file)
--- a/test-tool/libguestfs-test-tool.pod
+++ b/test-tool/libguestfs-test-tool.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
 
 =head1 NAME
 

-libguestfs-test-tool - End user tests for libguestfs
+libguestfs-test-tool - Diagnostics for libguestfs

 
 =head1 SYNOPSIS
 
 
 =head1 SYNOPSIS
 


@@ -10,12 +10,11 @@ libguestfs-test-tool - End user tests for libguestfs
 
 =head1 DESCRIPTION
 
 
 =head1 DESCRIPTION
 

-libguestfs-test-tool is a test program shipped with libguestfs to end
-users and developers, to allow them to check basic libguestfs
-functionality is working.  This is needed because libguestfs
-occasionally breaks for reasons beyond our control: usually because of
-changes in the underlying qemu or kernel packages, or the host
-environment.
+libguestfs-test-tool is a test program shipped with libguestfs to
+allow you to check basic libguestfs functionality is working.  This is
+needed because libguestfs occasionally breaks for reasons beyond our
+control: usually because of changes in the underlying qemu or kernel
+packages, or the host environment.

 
 If you suspect a problem in libguestfs, then just run:
 
 
 If you suspect a problem in libguestfs, then just run:
 


@@ -30,7 +29,7 @@ If it runs to completion successfully, you will see this near the end:
 and the test tool will exit with code 0.
 
 If it fails (and/or exits with non-zero error code), please paste the
 and the test tool will exit with code 0.
 
 If it fails (and/or exits with non-zero error code), please paste the

-B<complete, unedited> output of the test tool into a bug report.  More
+I<complete, unedited> output of the test tool into a bug report.  More

 information about reporting bugs can be found on the
 L<http://libguestfs.org/> website.
 
 information about reporting bugs can be found on the
 L<http://libguestfs.org/> website.
 


@@ -38,31 +37,26 @@ L<http://libguestfs.org/> website.
 
 =over 4
 
 
 =over 4
 

-=item I<--help>
+=item B<--help>

 
 Display short usage information and exit.
 
 
 Display short usage information and exit.
 

-=item I<--helper /path/to/libguestfs-test-tool-helper>
-
-Pass an alternate name for the helper program.  libguestfs-test-tool
-will normally look in the C<$libexec> directory that was configured
-when the tool was built.
-
-=item I<--qemu qemu_binary>
+=item B<--qemu qemu_binary>

 
 If you have downloaded another qemu binary, point this option at the
 full path of the binary to try it.
 
 
 If you have downloaded another qemu binary, point this option at the
 full path of the binary to try it.
 

-=item I<--qemudir qemu_source_dir>
+=item B<--qemudir qemu_source_dir>

 
 If you have compiled qemu from source, point this option at the source
 directory to try it.
 
 
 If you have compiled qemu from source, point this option at the source
 directory to try it.
 

-=item I<--timeout N>
+=item B<-t N>
+
+=item B<--timeout N>

 
 

-Set the launch timeout to C<N> seconds.  The default is 120 seconds
-which does not usually need to be adjusted unless your machine is very
-slow.
+Set the launch timeout to C<N> seconds.  The default is 600 seconds
+(10 minutes) which does not usually need to be adjusted.

 
 =back
 
 
 =back
 


@@ -75,31 +69,28 @@ the qemu source directory.
 If you have downloaded a qemu binary from somewhere, use the I<--qemu>
 option to point to the binary.
 
 If you have downloaded a qemu binary from somewhere, use the I<--qemu>
 option to point to the binary.
 

-When using an alternate qemu with libguestfs, usually you would need
-to write a qemu wrapper script (see section I<QEMU WRAPPERS> in
-L<guestfs(3)>).  libguestfs-test-tool writes a temporary qemu wrapper
-script when you use either of the I<--qemudir> or I<--qemu> options.
+Note when using these options, you can ignore the business of qemu
+wrapper scripts (L<guestfs(3)/QEMU WRAPPERS>), since
+libguestfs-test-tool writes a wrapper script for you if one is needed.

 
 

-=head1 EXIT CODE
+=head1 TRYING OUT A DIFFERENT KERNEL

 
 

-libguestfs-test-tool returns I<0> if the tests completed without
-error, or I<1> if there was an error.
+If you are using febootstrap E<ge> 3.8 then you can select which
+kernel libguestfs tries.  You do this by setting the environment
+variables C<FEBOOTSTRAP_KERNEL> and/or C<FEBOOTSTRAP_MODULES>.

 
 

-=head1 FILES
+Refer to L<febootstrap-supermin-helper(8)/ENVIRONMENT VARIABLES>
+for further information.

 
 

-=over 4
+=head1 SELF-DIAGNOSIS

 
 

-=item /usr/libexec/libguestfs-test-tool-helper
+Refer to L<guestfs(3)/APPLIANCE BOOT PROCESS> to understand the
+messages produced by libguestfs-test-tool and/or possible errors.

 
 

-This helper program is run inside the appliance and provides
-additional tests.
+=head1 EXIT STATUS

 
 

-=item /usr/bin/mkisofs
-
-The C<mkisofs> command is required in order to construct a CD-ROM ISO
-file which is used as part of the tests.
-
-=back
+libguestfs-test-tool returns I<0> if the tests completed without
+error, or I<1> if there was an error.

 
 =head1 ENVIRONMENT VARIABLES
 
 
 =head1 ENVIRONMENT VARIABLES
 


@@ -118,7 +109,7 @@ Richard W.M. Jones (C<rjones at redhat dot com>)
 
 =head1 COPYRIGHT
 
 
 =head1 COPYRIGHT
 

-Copyright (C) 2009 Red Hat Inc.
+Copyright (C) 2009-2011 Red Hat Inc.

 L<http://libguestfs.org/>
 
 This program is free software; you can redistribute it and/or modify
 L<http://libguestfs.org/>
 
 This program is free software; you can redistribute it and/or modify


@@ -133,4 +124,4 @@ GNU General Public License for more details.
 
 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 
 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software

-Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.