[Libguestfs] [PATCH v2] Improve fixed appliance documentation

Pino Toscano ptoscano at redhat.com
Wed Jun 10 16:47:44 UTC 2015


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

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                      | 17 +++++++++++++++-
 src/guestfs.pod                               | 24 +++++++++++++++++++++++
 3 files changed, 42 insertions(+), 27 deletions(-)

diff --git a/appliance/libguestfs-make-fixed-appliance.pod b/appliance/libguestfs-make-fixed-appliance.pod
index 3242afc..9eb8644 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 C<kernel>, C<initrd>, C<root> and C<README.fixed> (note
-the C<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 4862f65..0ffa76c 100644
--- a/examples/guestfs-faq.pod
+++ b/examples/guestfs-faq.pod
@@ -431,7 +431,22 @@ 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 from git or from
+tarballs).  Then, when using libguestfs, you either copy a
+pre-compiled appliance in the default search path, which you can find
+using e.g.
+
+ guestfish get-path
+
+or set the C<LIBGUESTFS_PATH> environment variable to a directory
+containing one.  For more information on pre-compiled/fixed appliances,
+see also L<guestfs(3)/FIXED APPLIANCE>.
+
+You can find pre-compiled appliances already prepared by the
+libguestfs team at
+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 e2ee1b5..eebab53 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -3540,6 +3540,30 @@ Finally, the child process sends asynchronous messages back to the
 main program, such as kernel log messages.  You can register a
 callback to receive these messages.
 
+=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 INTERNALS
 
 =head2 APPLIANCE BOOT PROCESS
-- 
2.1.0




More information about the Libguestfs mailing list