[Pkg-libvirt-commits] [libguestfs] 22/36: Improve fixed appliance documentation

[Hilko Bengen]

This is an automated email from the git hooks/post-receive script.

bengen pushed a commit to annotated tag upstream/1.29.47
in repository libguestfs.

commit 993140219c951e9e2dbfd820f0e6227836d6ed5d
Author: Pino Toscano <ptoscano at redhat.com>
Date:   Tue Jun 16 09:31:25 2015 +0200

    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 5ceef92..6cdf91f 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

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-libvirt/libguestfs.git