Pino Toscano
2015-Jun-10 16:19 UTC
[Libguestfs] [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
Pino Toscano
2015-Jun-10 16:47 UTC
[Libguestfs] [PATCH v2] 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 | 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
Richard W.M. Jones
2015-Jun-15 14:47 UTC
Re: [Libguestfs] [PATCH v2] Improve fixed appliance documentation
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 PROCESSI 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