Improved documentation and error messages.

9 files changed, 92 insertions, 24 deletions

diff --git a/lib/MGA/DrakISO/BuildBoot.pm b/lib/MGA/DrakISO/BuildBoot.pm
index b88561f..ed3347c 100644
--- a/lib/MGA/DrakISO/BuildBoot.pm
+++ b/lib/MGA/DrakISO/BuildBoot.pm
@@ -17,6 +17,13 @@
 # along with this program; if not, write to the Free Software Foundation,
 # Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA.
 
+# SYNOPSIS
+# --------
+# This package provides a function to prepare the bootloader files that are
+# needed to boot the ISO. Both MBR and UEFI boot are supported. It also
+# provides a function to prepare the kernel and initrd files needed to boot
+# a Live system.
+
 package MGA::DrakISO::BuildBoot;
 
 use strict;
@@ -37,6 +44,10 @@ our @EXPORT = qw(prepare_live_system_boot prepare_iso_bootloader);
 # Live System
 ###############################################################################
 
+# This is the top-level function called to prepare the kernel and initrd files
+# for booting the Live system. These files are built in and/or copied from the
+# Live root filesystem, so that must be prepared before calling this function.
+#
 sub prepare_live_system_boot {
     my ($build) = @_;
 
@@ -51,7 +62,7 @@ sub prepare_live_system_boot {
 
     # Copy the kernel into the build directory.
     my $vmlinuz = $build->get_system_root . '/boot/vmlinuz-' . $kernel->{version};
-    -e $vmlinuz or die "cannot find kernel $kernel->{version} in root system\n";
+    -e $vmlinuz or die "ERROR: cannot find kernel $kernel->{version} in root system\n";
     cp_f($vmlinuz, $boot_dir . '/vmlinuz');
 
     # Build an initrd suitable for Live boot.
@@ -64,13 +75,16 @@ sub prepare_live_system_boot {
     }
 
     # Move the initrd into the build directory.
-    mv($initrd, $boot_dir . '/initrd.gz') or die "cannot move initrd: $!\n";
+    mv($initrd, $boot_dir . '/initrd.gz') or die "ERROR: cannot move initrd: $!\n";
 }
 
 ###############################################################################
 # ISO Bootloader
 ###############################################################################
 
+# This is the top-level function called to prepare the files needed by the
+# GRUB2 bootloader. It does not depend on any other preparatory steps.
+#
 sub prepare_iso_bootloader {
     my ($build) = @_;
 
@@ -92,7 +106,7 @@ sub prepare_iso_bootloader {
     # font, don't worry - the bootloader will fall back to text mode.
     my $font = $build->get_absolute_path($build->{media}{bootloader_font});
     if (defined $font) {
-        -e $font or die "cannot find bootloader font file $font\n";
+        -e $font or die "ERROR: cannot find bootloader font file $font\n";
     } else {
         $font = '/usr/share/grub/unicode.pf2';
     }
@@ -107,7 +121,7 @@ sub prepare_iso_bootloader {
     # proceed without a theme.
     my $theme = $build->get_absolute_path($build->{media}{bootloader_theme});
     if (defined $theme) {
-        -d $theme or die "cannot find bootloader theme directory $theme\n";
+        -d $theme or die "ERROR: cannot find bootloader theme directory $theme\n";
     } else {
         $theme = '/boot/grub2/themes/maggy';
     }
@@ -127,24 +141,24 @@ sub prepare_iso_bootloader {
     my $add_kbd_menu  = defined $build->{media}{bootloader_kbds};
     if ($add_lang_menu) {
         my $lang_names = $build->get_absolute_path($build->{media}{bootloader_langs});
-        -e $lang_names or die "cannot find bootloader language name file $lang_names\n";
-        my @langs = group_by2(eval(cat_($lang_names))) or die "error in language name file $lang_names\n";
+        -e $lang_names or die "ERROR: cannot find bootloader language name file $lang_names\n";
+        my @langs = group_by2(eval(cat_($lang_names))) or die "ERROR: error in language name file $lang_names\n";
 
         my $lang_kbds = dirname($lang_names) . '/lang-kbds.txt';
         my $kbds;
         if ($add_kbd_menu && -e $lang_kbds) {
-            $kbds = eval(cat_($lang_kbds)) or die "error in language keyboard file $lang_kbds\n";
+            $kbds = eval(cat_($lang_kbds)) or die "ERROR: error in language keyboard file $lang_kbds\n";
         }
 
         MDK::Common::File::output_utf8($grub2_dir . '/lang-menu.cfg', build_lang_menu_cfg(\@langs, %$kbds));
     }
     if ($add_kbd_menu) {
         my $kbd_names = $build->get_absolute_path($build->{media}{bootloader_kbds});
-        -e $kbd_names or die "cannot find bootloader keyboard name file $kbd_names\n";
-        my @kbds = group_by2(eval(cat_($kbd_names))) or die "error in keyboard name file $kbd_names\n";
+        -e $kbd_names or die "ERROR: cannot find bootloader keyboard name file $kbd_names\n";
+        my @kbds = group_by2(eval(cat_($kbd_names))) or die "ERROR: error in keyboard name file $kbd_names\n";
 
         my $layouts = dirname($kbd_names) . '/layouts';
-        -d $layouts or die "cannot find bootloader keyboard map directory $layouts\n";
+        -d $layouts or die "ERROR: cannot find bootloader keyboard map directory $layouts\n";
         cp_f($layouts, $grub2_dir);
 
         MDK::Common::File::output_utf8($grub2_dir . '/kbd-menu.cfg', build_kbd_menu_cfg(\@kbds));
@@ -153,7 +167,7 @@ sub prepare_iso_bootloader {
     # Copy any message translation files the user has provided.
     my $messages = $build->get_absolute_path($build->{media}{bootloader_messages});
     if (defined $messages) {
-        -d $messages or die "cannot find bootloader messages directory $messages\n";
+        -d $messages or die "ERROR: cannot find bootloader messages directory $messages\n";
         my $locale_dir = $grub2_dir . '/locale';
         mkdir_p($locale_dir);
         cp_f(glob($messages . '/*.mo'), $locale_dir);
@@ -163,7 +177,7 @@ sub prepare_iso_bootloader {
     # otherwise build one.
     my $eltorito_img = $build->get_absolute_path($build->{media}{eltorito_img});
     if (defined $eltorito_img) {
-        -e $eltorito_img or die "cannot find El Torito boot image $eltorito_img\n";
+        -e $eltorito_img or die "ERROR: cannot find El Torito boot image $eltorito_img\n";
         cp_f($eltorito_img, $grub2_dir . '/eltorito.img');
     } else {
         build_grub2_eltorito_img($grub2_dir . '/eltorito.img');
@@ -177,7 +191,7 @@ sub prepare_iso_bootloader {
     my $grub2_cfg = $grub2_dir . '/grub.cfg';
     if (defined $build->{media}{grub2_cfg}) {
         my $grub_cfg_template = $build->get_absolute_path($build->{media}{grub2_cfg});
-        -e $grub_cfg_template or die "cannot find grub2 config file $grub_cfg_template\n";
+        -e $grub_cfg_template or die "ERROR: cannot find grub2 config file $grub_cfg_template\n";
         cp_f($grub_cfg_template, $grub2_cfg);
         run_("sed", "-i", "s/VOLUME_LABEL/$label/g", $grub2_cfg);
     } else {
@@ -208,7 +222,7 @@ sub prepare_iso_bootloader {
     # otherwise build one.
     my $bootx64_efi = $build->get_absolute_path($build->{media}{bootx64_efi});
     if (defined $bootx64_efi) {
-        -e $bootx64_efi or die "cannot find EFI boot image $bootx64_efi\n";
+        -e $bootx64_efi or die "ERROR: cannot find EFI boot image $bootx64_efi\n";
         cp_f($bootx64_efi, $efi_boot_dir . '/bootx64.efi');
     } else {
         build_grub2_bootx64_efi($efi_boot_dir . '/bootx64.efi');
diff --git a/lib/MGA/DrakISO/BuildISO.pm b/lib/MGA/DrakISO/BuildISO.pm
index 54edaff..41f562a 100644
--- a/lib/MGA/DrakISO/BuildISO.pm
+++ b/lib/MGA/DrakISO/BuildISO.pm
@@ -19,9 +19,7 @@
 
 # SYNOPSIS
 # --------
-# This module provides a function to build the ISO image. All the files
-# to go on the ISO should be stored in or linked into the build directory
-# before performing this step.
+# This package provides a function to finally build the ISO image.
 
 package MGA::DrakISO::BuildISO;
 
@@ -40,9 +38,10 @@ use Exporter;
 our @ISA = qw(Exporter);
 our @EXPORT = qw(build_iso);
 
-# This is the top-level function called to build an iso image. It generates
+# This is the top-level function called to build an ISO image. It generates
 # the list of file assignments before calling build_iso_image() to do the
-# actual work.
+# actual work. All the files to go on the ISO should be stored in or linked
+# into the build directory before calling this function.
 #
 sub build_iso {
     my ($build) = @_;
@@ -101,10 +100,10 @@ sub build_iso_image {
     my $arch = $build->{settings}{arch};
 
     my $mbr_image = $build->get_absolute_path($build->{media}{mbr_boot_img}) // '/usr/lib/grub/i386-pc/boot_hybrid.img';
-    -e $mbr_image or die "cannot find MBR boot image $mbr_image\n";
+    -e $mbr_image or die "ERROR: cannot find MBR boot image $mbr_image\n";
 
     my $esp_image = $build->get_builddir('images') . '/esp.img';
-    -e $esp_image || $arch ne 'x86_64' or die "cannot find ESP image $esp_image\n";
+    -e $esp_image || $arch ne 'x86_64' or die "ERROR: cannot find ESP image $esp_image\n";
 
     my $build_dir = $build->get_builddir('dist');
     mkdir_p($build_dir);
@@ -148,7 +147,7 @@ sub build_iso_image {
             '-o', $dest,
             @opts,
             '/DATE.txt=' . $date_file,
-    ) or die "unable to run xorrisofs\n";
+    ) or die "ERROR: unable to run xorrisofs\n";
 
     my $filename = basename($dest);
     run_('mgaiso-addmd5', '>', '/dev/null', '2>', '/dev/null', $dest);
diff --git a/lib/MGA/DrakISO/BuildLoop.pm b/lib/MGA/DrakISO/BuildLoop.pm
index 8cdd6e5..3722644 100644
--- a/lib/MGA/DrakISO/BuildLoop.pm
+++ b/lib/MGA/DrakISO/BuildLoop.pm
@@ -17,6 +17,11 @@
 # along with this program; if not, write to the Free Software Foundation,
 # Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA.
 
+# SYNOPSIS
+# --------
+# This package provides a function to build the compressed images that will
+# be mounted as loopback filesystems when booting a Live system.
+
 package MGA::DrakISO::BuildLoop;
 
 use strict;
@@ -34,6 +39,9 @@ use Exporter;
 our @ISA = qw(Exporter);
 our @EXPORT = qw(build_live_loopback_files list_loopback_modules);
 
+# This is the top-level function called to build the loopback images. The Live
+# root filesystem must have been prepared before calling this function.
+#
 sub build_live_loopback_files {
     my ($build) = @_;
     # make sure no external filesystems are mounted before creating the loopback
diff --git a/lib/MGA/DrakISO/BuildMedia.pm b/lib/MGA/DrakISO/BuildMedia.pm
index 31b1f1c..8fe59bd 100644
--- a/lib/MGA/DrakISO/BuildMedia.pm
+++ b/lib/MGA/DrakISO/BuildMedia.pm
@@ -17,7 +17,7 @@
 
 # SYNOPSIS
 # --------
-# This module provides functions to create the installation media that will
+# This package provides a function to create the installation media that will
 # be used by the classic installer and to collect together the various other
 # files that are needed on the installer ISO.
 
@@ -70,6 +70,10 @@ my @excluded;
 # Main Code
 ###############################################################################
 
+# This is the top-level function called to prepare the installation media
+# and other files required by the installer. It is independent of any other
+# preparatory step.
+#
 sub prepare_media {
     my ($build) = @_;
 
@@ -104,6 +108,8 @@ sub prepare_media {
     create_product_id($build, $arch_dir . '/product.id');
     create_index($build, $arch_dir . '/pkg-' . $version . '-' . $tag . '.idx');
 
+    # We don't expect this function to be called twice, but clean up
+    # nonetheless.
     undef $urpm;
     undef %package;
     undef @excluded;
@@ -481,7 +487,7 @@ sub build_installer_media {
     my $silent = $::verbose < 3 ? ' -s' : '';
     print "-- messages from gendistrib -----------------------\n" if !$silent;
     system("gendistrib $silent $arch_dir\n") == 0
-      or die "ERROR: gendistrib failed to generate the media info.\n";
+      or die "ERROR: gendistrib failed to generate the media info\n";
     print "---------------------------------------------------\n" if !$silent;
 }
 
diff --git a/lib/MGA/DrakISO/BuildRoot.pm b/lib/MGA/DrakISO/BuildRoot.pm
index 77181e6..8710043 100644
--- a/lib/MGA/DrakISO/BuildRoot.pm
+++ b/lib/MGA/DrakISO/BuildRoot.pm
@@ -17,6 +17,11 @@
 # along with this program; if not, write to the Free Software Foundation,
 # Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA.
 
+# SYNOPSIS
+# --------
+# This package provides functions to create and customise the root filesystem
+# for a Live system.
+
 package MGA::DrakISO::BuildRoot;
 
 use strict;
@@ -32,6 +37,10 @@ use Exporter;
 our @ISA = qw(Exporter);
 our @EXPORT = qw(install_live_system customise_live_system);
 
+# This is the top-level function called to create the basic root filesystem. It
+# uses stage2 of the Mageia installer to do the actual work. It is independent
+# of any other preparatory step.
+#
 sub install_live_system {
     my ($build) = @_;
 
@@ -64,6 +73,11 @@ sub install_live_system {
     ) or die "unable to install system chroot\n";
 }
 
+# This is the top-level function called to customise the root filesystem. It
+# allows a standard Mageia installation to be fine-tuned for use as a Live
+# system. The basic root filesystem must have been prepared before calling
+# this function.
+#
 sub customise_live_system {
     my ($build) = @_;
 
diff --git a/lib/MGA/DrakISO/Loopback.pm b/lib/MGA/DrakISO/Loopback.pm
index 33a086a..e06d2a4 100644
--- a/lib/MGA/DrakISO/Loopback.pm
+++ b/lib/MGA/DrakISO/Loopback.pm
@@ -17,6 +17,14 @@
 # along with this program; if not, write to the Free Software Foundation,
 # Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA.
 
+# SYNOPSIS
+# --------
+# This package defines a set of alternative methods for creating the images
+# that will be mounted as loopback filesystems when booting a Live system.
+# 'squashfs' is the only method that has been tested with drakiso. The other
+# methods were inherited from the original draklive and are most likely no
+# longer needed.
+
 package MGA::DrakISO::Loopback;
 
 use strict;
diff --git a/lib/MGA/DrakISO/Mounts.pm b/lib/MGA/DrakISO/Mounts.pm
index 4d93afa..855f226 100644
--- a/lib/MGA/DrakISO/Mounts.pm
+++ b/lib/MGA/DrakISO/Mounts.pm
@@ -17,6 +17,13 @@
 # along with this program; if not, write to the Free Software Foundation,
 # Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA.
 
+# SYNOPSIS
+# --------
+# This package defines a set of alternative methods for mounting the loopback
+# filesystems when booting a Live system. 'volatile_squash_union' is the only
+# method that has been tested with drakiso. The other methods were inherited
+# from the original draklive and may no longer be needed.
+
 package MGA::DrakISO::Mounts;
 
 use strict;
diff --git a/lib/MGA/DrakISO/Storage.pm b/lib/MGA/DrakISO/Storage.pm
index aac9429..55857df 100644
--- a/lib/MGA/DrakISO/Storage.pm
+++ b/lib/MGA/DrakISO/Storage.pm
@@ -17,6 +17,14 @@
 # along with this program; if not, write to the Free Software Foundation,
 # Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA.
 
+# SYNOPSIS
+# --------
+# This package defines a set of alternative storage types. This abstraction
+# is inherited from the original draklive, which supported the creation of
+# Live systems on different types of media. drakiso currently only supports
+# creation of ISO images, but this abstraction has been preserved in case
+# the additional functionality is added in the future.
+
 package MGA::DrakISO::Storage;
 
 use strict;
diff --git a/lib/MGA/DrakISO/Utils.pm b/lib/MGA/DrakISO/Utils.pm
index bb40d55..85a9892 100644
--- a/lib/MGA/DrakISO/Utils.pm
+++ b/lib/MGA/DrakISO/Utils.pm
@@ -17,6 +17,10 @@
 # along with this program; if not, write to the Free Software Foundation,
 # Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA.
 
+# SYNOPSIS
+# --------
+# This package provides miscellaneous helper functions.
+
 package MGA::DrakISO::Utils;
 
 use strict;