Libguestfs - Jun 2015 - [PATCH] builder: add a doc snippet about firstboot scripts

When convering a POD documentation, possibily combining various
sub-documents together, simplify the L<> links that explicitly point to
the very same documentation being generated.

For example, when generating the virt-builder documentation, links like
  L<virt-builder(1)/SECTION>
will be turned into
  L</SECTION>
thus not making Pod::Simple parse them as external reference.

While it is a slightly crude hack, it seems there's no easy way to
process the link parsing with Pod::Simple subclasses.
---
 podwrapper.pl.in | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/podwrapper.pl.in b/podwrapper.pl.in
index 0bb7b28..b354db6 100755
--- a/podwrapper.pl.in
+++ b/podwrapper.pl.in
@@ -278,6 +278,9 @@ foreach (@inserts) {
         if $content eq $oldcontent;
 }
 
+# Turn external links to this man page into simple cross-section links.
+$content =~ s,\QL<$name($section)/\E,L</,g;
+
 # Perform @verbatims.
 foreach (@verbatims) {
     my @a = split /:/, $_, 2;
-- 
2.1.0

Document basic information about them for Linux and Windows guests.
---
 builder/virt-builder.pod | 36 ++++++++++++++++++++++++++++++++++++
 generator/customize.ml   |  6 ++++++
 2 files changed, 42 insertions(+)

diff --git a/builder/virt-builder.pod b/builder/virt-builder.pod
index b68845b..f44c165 100644
--- a/builder/virt-builder.pod
+++ b/builder/virt-builder.pod
@@ -805,6 +805,42 @@ In any case, the C<~USER/.ssh> directory and the
 C<~USER/.ssh/authorized_keys> file will be created if not existing
 already.
 
+=head2 FIRST BOOT SCRIPTS
+
+The I<--firstboot> and I<--firstboot-command> options allow to
execute
+commands at the first boot of the guest.  To do so, an init script for
+the guest init system is installed, which takes care of running all
+the added scripts and commands.
+
+Supported operating systems are:
+
+=over 4
+
+=item Linux
+
+Init systems supported are: systemd, System-V init (known also as sysvinit),
+and Upstart (using the System-V scripts).
+
+Note that usually init scripts run as root, but with a more limited
+environment than what could be available from a normal shell:
+for example, C<$HOME> may be unset or empty.
+
+=item Windows
+
+F<rhsrvany.exe>, available from sources at
+L<https://github.com/rwmjones/rhsrvany>, is installed to run the
+first boot scripts.  It is required, and the setup of first boot
+scripts will fail if it is not present.
+
+F<rhsrvany.exe> is copied from the location pointed to by the
+C<VIRT_TOOLS_DATA_DIR> environment variable; if not set, a compiled-in
+default will be used (something like "/usr/share/virt-tools").
+
+=back
+
+The output of the first boot scripts is available in the guest as
+F<~root/virt-sysprep-firstboot.log>.
+
 =head2 INSTALLATION PROCESS
 
 When you invoke virt-builder, installation proceeds as follows:
diff --git a/generator/customize.ml b/generator/customize.ml
index 2980d39..f57aba6 100644
--- a/generator/customize.ml
+++ b/generator/customize.ml
@@ -148,6 +148,9 @@ conveniently wraps the command up in a single line script
for you.
 You can have multiple I<--firstboot> options.  They run in the same
 order that they appear on the command line.
 
+Please take a look at L<virt-builder(1)/FIRST BOOT SCRIPTS> for more
+information and caveats about the first boot scripts.
+
 See also I<--run>.";
   };
 
@@ -162,6 +165,9 @@ boots up (as root, late in the boot process).
 You can have multiple I<--firstboot> options.  They run in the same
 order that they appear on the command line.
 
+Please take a look at L<virt-builder(1)/FIRST BOOT SCRIPTS> for more
+information and caveats about the first boot scripts.
+
 See also I<--run>.";
   };
 
-- 
2.1.0

On Tue, Jun 09, 2015 at 11:58:26AM +0200, Pino Toscano
wrote:
> Document basic information about them for Linux and Windows guests.
> ---
>  builder/virt-builder.pod | 36 ++++++++++++++++++++++++++++++++++++
>  generator/customize.ml   |  6 ++++++
>  2 files changed, 42 insertions(+)
> 
> diff --git a/builder/virt-builder.pod b/builder/virt-builder.pod
> index b68845b..f44c165 100644
> --- a/builder/virt-builder.pod
> +++ b/builder/virt-builder.pod
> @@ -805,6 +805,42 @@ In any case, the C<~USER/.ssh> directory and the
>  C<~USER/.ssh/authorized_keys> file will be created if not existing
>  already.
>  
> +=head2 FIRST BOOT SCRIPTS
> +
> +The I<--firstboot> and I<--firstboot-command> options allow to
execute
.. allow you to execute ..

[...]
> +F<rhsrvany.exe> is copied from the location pointed to by the
> +C<VIRT_TOOLS_DATA_DIR> environment variable; if not set, a
compiled-in
> +default will be used (something like "/usr/share/virt-tools").
Probably best to put C<> or F<> instead of quotes around this
string.

ACK.

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

On Tue, Jun 09, 2015 at 11:58:25AM +0200, Pino Toscano
wrote:
> When convering a POD documentation, possibily combining various
> sub-documents together, simplify the L<> links that explicitly point
to
> the very same documentation being generated.
> 
> For example, when generating the virt-builder documentation, links like
>   L<virt-builder(1)/SECTION>
> will be turned into
>   L</SECTION>
> thus not making Pod::Simple parse them as external reference.
> 
> While it is a slightly crude hack, it seems there's no easy way to
> process the link parsing with Pod::Simple subclasses.
> ---
>  podwrapper.pl.in | 3 +++
>  1 file changed, 3 insertions(+)
> 
> diff --git a/podwrapper.pl.in b/podwrapper.pl.in
> index 0bb7b28..b354db6 100755
> --- a/podwrapper.pl.in
> +++ b/podwrapper.pl.in
> @@ -278,6 +278,9 @@ foreach (@inserts) {
>          if $content eq $oldcontent;
>  }
>  
> +# Turn external links to this man page into simple cross-section links.
> +$content =~ s,\QL<$name($section)/\E,L</,g;
> +
>  # Perform @verbatims.
>  foreach (@verbatims) {
>      my @a = split /:/, $_, 2;
ACK.

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-top is 'top' for virtual machines.  Tiny program with many
powerful monitoring features, net stats, disk stats, logging, etc.
http://people.redhat.com/~rjones/virt-top