Libguestfs - Jun 2015 - [PATCH v3] Improve fixed appliance documentation

Move the "FIXED APPLIANCE" section from
libguestfs-make-fixed-appliance(1) to the "INTERNALS" section of
guestfs(3), so it's more visible and less hidden in the documentation
of a rarely-used tool.  Also slightly improve it.

Expand the FAQ question about libguestfs without supermin, mentioning
the build options needed and pointing to the aforementioned new section.
---
 appliance/libguestfs-make-fixed-appliance.pod | 28 ++------------------
 examples/guestfs-faq.pod                      | 11 +++++++-
 src/guestfs.pod                               | 37 +++++++++++++++++++++++++++
 3 files changed, 49 insertions(+), 27 deletions(-)

diff --git a/appliance/libguestfs-make-fixed-appliance.pod
b/appliance/libguestfs-make-fixed-appliance.pod
index 9807f80..99c55fa 100644
--- a/appliance/libguestfs-make-fixed-appliance.pod
+++ b/appliance/libguestfs-make-fixed-appliance.pod
@@ -38,8 +38,8 @@ L<guestfs-performance(1)>).
 
 =back
 
-For deeper understanding of why you might need this tool, read the
-section L</FIXED APPLIANCE> below.
+For deeper understanding of why you might need this tool, read
+L<guestfs(3)/FIXED APPLIANCE>.
 
 Instead of running this tool, you can download fixed appliances from
 L<http://libguestfs.org/download/binaries/appliance/>.  These
@@ -120,30 +120,6 @@ completely silent when it is running.
 
 =back
 
-=head1 FIXED APPLIANCE
-
-When libguestfs (or libguestfs tools) are run, they search a path
-looking for an appliance.  The path is built into libguestfs, or can
-be set using the C<LIBGUESTFS_PATH> environment variable.
-
-Normally a supermin appliance is located on this path (see
-L<supermin(1)/SUPERMIN APPLIANCE>).  libguestfs reconstructs this
-into a full appliance by running C<supermin --build>.
-
-However, a simpler "fixed appliance" can also be used.  libguestfs
-detects this by looking for a directory on the path containing four
-files called F<kernel>, F<initrd>, F<root> and
F<README.fixed> (note
-the F<README.fixed> file must be present as well).
-
-If the fixed appliance is found, libguestfs skips supermin entirely
-and just runs qemu with the kernel, initrd and root disk from the
-fixed appliance.
-
-Thus the fixed appliance can be used when a platform or Linux distro
-does not support supermin.  You build the fixed appliance on a
-platform that does support supermin, and copy it over, and use that
-to run libguestfs.
-
 =head1 LICENSING
 
 The fixed appliance is a complete Linux binary distro.  If you
diff --git a/examples/guestfs-faq.pod b/examples/guestfs-faq.pod
index 8d52ab2..bc54c54 100644
--- a/examples/guestfs-faq.pod
+++ b/examples/guestfs-faq.pod
@@ -431,7 +431,16 @@ enough supermin installed, then see the previous question.
 
 If supermin 5 doesn't support your distro at all, you will need to use
 the "fixed appliance method" where you use a pre-compiled binary
-appliance.  See: L<http://libguestfs.org/download/binaries/appliance/>
+appliance.  To build libguestfs without supermin, you need to pass
+C<--disable-appliance --disable-daemon> to either F<./autogen.sh>
or
+F<./configure> (depending whether you are building respectively from
+git or from tarballs).  Then, when using libguestfs, you B<must> set
+the C<LIBGUESTFS_PATH> environment variable to the directory of a
+pre-compiled appliance, as also described in
+L<guestfs(3)/FIXED APPLIANCE>.
+
+For pre-compiled appliances, see also:
+L<http://libguestfs.org/download/binaries/appliance/>.
 
 Patches to port supermin to more Linux distros are welcome.
 
diff --git a/src/guestfs.pod b/src/guestfs.pod
index fa04c86..a524fdf 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -3795,6 +3795,43 @@ The daemon self-limits the frequency of progress messages
it sends
 (see C<daemon/proto.c:notify_progress>).  Not all calls generate
 progress messages.
 
+=head2 FIXED APPLIANCE
+
+When libguestfs (or libguestfs tools) are run, they search a path
+looking for an appliance.  The path is built into libguestfs, or can
+be set using the C<LIBGUESTFS_PATH> environment variable.
+
+Normally a supermin appliance is located on this path (see
+L<supermin(1)/SUPERMIN APPLIANCE>).  libguestfs reconstructs this
+into a full appliance by running C<supermin --build>.
+
+However, a simpler "fixed appliance" can also be used.  libguestfs
+detects this by looking for a directory on the path containing all
+the following files:
+
+=over 4
+
+=item * F<kernel>
+
+=item * F<initrd>
+
+=item * F<root>
+
+=item * F<README.fixed> (note that it B<must> be present as well)
+
+=back
+
+If the fixed appliance is found, libguestfs skips supermin entirely
+and just runs the virtual machine (using qemu or the current backend,
+see L</BACKEND>) with the kernel, initrd and root disk from the fixed
+appliance.
+
+Thus the fixed appliance can be used when a platform or a Linux
+distribution does not support supermin.  You build the fixed appliance
+on a platform that does support supermin using
+L<libguestfs-make-fixed-appliance(1)>, copy it over, and use that
+to run libguestfs.
+
 =head1 LIBGUESTFS VERSION NUMBERS
 
 Since April 2010, libguestfs has started to make separate development
-- 
2.1.0

ACK.

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-builder quickly builds VMs from scratch
http://libguestfs.org/virt-builder.1.html