Re: [Libguestfs] [PATCH v2] Improve fixed appliance documentation
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