From 6cd0bef858db460ecb4a6b153225d15bdc62a5fd Mon Sep 17 00:00:00 2001
From: Helmut Grohne <helmut@subdivi.de>
Date: Fri, 23 Dec 2022 12:18:26 +0100
Subject: add documentation in pod2man format

Fixes: #2
---
 debvm-create | 79 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

(limited to 'debvm-create')

diff --git a/debvm-create b/debvm-create
index a8f164d..6026a7c 100755
--- a/debvm-create
+++ b/debvm-create
@@ -4,6 +4,85 @@
 
 # shellcheck disable=SC2016 # Intentional quoting technique
 
+: <<'POD2MAN'
+=head1 NAME
+
+debvm-create - Create a VM image for various Debian releases and architectures
+
+=head1 SYNOPSIS
+
+B<debvm-create> [B<-a> I<architecture>] [B<-h> I<hostname>] [B<-k> I<sshkey>] [B<-m> I<mirror>] [B<-o> I<output>] [B<-p> I<package>] [B<-r> I<release>] [B<-s> I<size_in_GB>] [B<--> I<mmdebstrap options>]
+
+=head1 DESCRIPTION
+
+B<debvm-create> is essentially a thin wrapper around B<mmdebstrap> for creating a raw ext4 filesystem image for booting with B<debvm-run>.
+The purpose of these images primarily is testing the different releases and architectures.
+Beyond essential packages, the image will contain B<apt>, an init system and a suitable kernel package.
+Notably absent is a bootloader and partition table.
+In order to boot such an image, one is supposed to extract the kernel and initrd from the image and pass it to a suitable bootloader.
+No user account is created and root can login without specifying a password.
+
+=head1 OPTIONS
+
+=over 8
+
+=item B<-a> I<architecture>
+
+Specify a Debian architecture name.
+By default, the native architecture is being used.
+A suitable kernel image is automatically selected and installed into the image.
+
+=item B<-h> I<hostname>
+
+Set the hostname of the virtual machine.
+By default, the hostname is B<testvm>.
+
+=item B<-k> I<sshkey>
+
+Install the given ssh public key file into the virtual machine image for the root user.
+This option also causes the ssh server to be installed.
+By default, no key or server is installed.
+
+=item B<-m> I<mirror>
+
+Specify the Debian mirror to be used for downloading packages and to be configured inside the virtual machine image.
+By default, B<http://deb.debian.org/debian> is being used.
+
+=item B<-o> I<output>
+
+Specify the file name of the resulting virtual machine image.
+By default, it is written to B<rootfs.ext4>.
+
+=item B<-p> I<package>
+
+Request additional packages to be installed into the virtual machine image.
+This option can be specified multiple times and packages can be separated with comma.
+Package recommendations are not honoured.
+
+=item B<-r> I<release>
+
+Use the given Debian release.
+By default, B<unstable> is being used.
+
+=item B<-s> I<size_in_GB>
+
+Specify the image size in giga bytes.
+The default image size is 1 GB.
+
+=item B<--> I<mmdebstrap options>
+
+All options beyond a double dash are passed to B<mmdebstrap> before the suite, target and mirror specification.
+This can be used to provide additional hooks for image customization.
+
+=back
+
+=head1 SEE ALSO
+
+    debvm-run(1) mmdebstrap(1)
+
+=cut
+POD2MAN
+
 set -u
 
 ARCHITECTURE=$(dpkg --print-architecture)
-- 
cgit v1.2.3