[PATCH] Improve fixed appliance documentation
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 | 11 ++++++++++- src/guestfs.pod | 24 +++++++++++++++++++++++ 3 files changed, 36 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..7e1f34d 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 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 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
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
On Wed, Jun 10, 2015 at 06:47:44PM +0200, Pino Toscano wrote:
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
I think this section is in the wrong place, since it should be under INTERNALS. However I don't like this patch for a couple of reasons, one of which to be fair I didn't discuss before: - I'd kind of like to split up the giant guestfs(3) man page, for the obvious reason that it's huge and hard to navigate. In such a split, there might be a guestfs-internals(3) man page containing the current content of guestfs(3)/INTERNALS. - If we split up the man page into many pages, then I don't particularly see a problem with keeping the description of the fixed appliance in the current place, where it is close to the relevant tool. Rich. -- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones Read my programming and virtualization blog: http://rwmj.wordpress.com libguestfs lets you edit virtual machines. Supports shell scripting, bindings from many languages. http://libguestfs.org
On Monday 15 June 2015 15:47:31 Richard W.M. Jones wrote:
On Wed, Jun 10, 2015 at 06:47:44PM +0200, Pino Toscano wrote:
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
I think this section is in the wrong place, since it should be under INTERNALS.
I was in doubt about that too, your suggestion makes sense to me.
However I don't like this patch for a couple of reasons, one of which to be fair I didn't discuss before:
- I'd kind of like to split up the giant guestfs(3) man page, for the obvious reason that it's huge and hard to navigate. In such a split, there might be a guestfs-internals(3) man page containing the current content of guestfs(3)/INTERNALS.
Then this section could be there indeed, I guess.
- If we split up the man page into many pages, then I don't particularly see a problem with keeping the description of the fixed appliance in the current place, where it is close to the relevant tool.
While the usage of the tool is relevant, for those using libguestfs with fixed appliance is IMHO less relevant (source-based Linux distros and hopefully soon also non-Linux OSes), so it would be better a single place (not bound to any tool) describing this approach. What I could add there is a link back to the tool, so it's even slightly more visible. What do you think? -- Pino Toscano
On Mon, Jun 15, 2015 at 05:47:49PM +0200, Pino Toscano wrote:
What I could add there is a link back to the tool, so it's even slightly more visible.
Yes, adding a link back to the tool would be necessary. ACK with this change & moving it into the "INTERNALS" section. Rich. -- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones Read my programming and virtualization blog: http://rwmj.wordpress.com virt-p2v converts physical machines to virtual machines. Boot with a live CD or over the network (PXE) and turn machines into KVM guests. http://libguestfs.org/virt-v2v
participants (2)
-
Pino Toscano -
Richard W.M. Jones