Improved documentation and error messages.

1 files changed, 28 insertions, 14 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');