Libguestfs - Jun 2015 - Re: [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 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