draklive2: add comments and fix some error messages.

1 files changed, 58 insertions, 6 deletions

diff --git a/draklive2 b/draklive2
index 2fa83d9..a3c5fb8 100755
--- a/draklive2
+++ b/draklive2
@@ -430,17 +430,23 @@ sub create_initrd {
 sub create_bootloader {
     my ($live) = @_;
 
+    # Create a build directory. This will contain all the files we need to
+    # exist in /boot on the ISO.
     my $boot_dir = $live->get_builddir . $live->{prefix}{build}{boot};
     mkdir_p($boot_dir);
 
+    # Locate and copy the kernel we want to boot.
     my $kernel = $live->find_kernel->{version};
     my $vmlinuz = $live->get_system_root . '/boot/vmlinuz-' . $kernel;
     -e $vmlinuz or die "cannot find kernel $kernel in root system\n";
     cp_f($vmlinuz, $boot_dir . '/vmlinuz');
 
+    # Create a subdirectory to hold the grub2 bootloader.
     my $grub2_dir = $boot_dir . '/grub2';
     mkdir_p($grub2_dir);
 
+    # Locate and copy the default font for the bootloader. If we can't find a
+    # font, don't worry - the bootloader will fall back to text mode.
     my $font = get_absolute_path($live, $live->{media}{bootloader_font});
     if (defined $font) {
         -e $font or die "cannot find bootloader font file $font\n";
@@ -453,6 +459,9 @@ sub create_bootloader {
         cp_f($font, $fonts_dir);
     }
 
+    # Locate and copy the bootloader theme. Default to the standard Mageia
+    # theme if the user hasn't specified one. If that's not available either,
+    # proceed without a theme.
     my $theme = get_absolute_path($live, $live->{media}{bootloader_theme});
     if (defined $theme) {
         -d $theme or die "cannot find bootloader theme directory $theme\n";
@@ -468,6 +477,9 @@ sub create_bootloader {
         @theme_fonts = map { basename($_) } glob("$theme/*.pf2");
     }
 
+    # If the user has provided the necessary configuration data, construct
+    # the bootloader language and keyboard selection submenus and copy the
+    # grub2 keyboard layout files.
     my $add_lang_menu = defined $live->{media}{bootloader_langs};
     my $add_kbd_menu  = defined $live->{media}{bootloader_kbds};
     if ($add_lang_menu) {
@@ -483,11 +495,10 @@ sub create_bootloader {
 
         MDK::Common::File::output_utf8($grub2_dir . '/lang-menu.cfg', build_lang_menu_cfg(\@langs, %$kbds));
     }
-
     if ($add_kbd_menu) {
         my $kbd_names = get_absolute_path($live, $live->{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 language name file $kbd_names\n";
+        my @kbds = group_by2(eval(cat_($kbd_names))) or die "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";
@@ -496,6 +507,7 @@ sub create_bootloader {
         MDK::Common::File::output_utf8($grub2_dir . '/kbd-menu.cfg', build_kbd_menu_cfg(\@kbds));
     }
 
+    # Copy any message translation files the user has provided.
     my $messages = get_absolute_path($live, $live->{media}{bootloader_messages});
     if (defined $messages) {
         -d $messages or die "cannot find bootloader messages directory $messages\n";
@@ -504,9 +516,11 @@ sub create_bootloader {
         cp_f(glob($messages . '/*.mo'), $locale_dir);
     }
 
+    # If the user has supplied a grub2 image for non-UEFI boot, copy that,
+    # otherwise build one.
     my $eltorito_img = get_absolute_path($live, $live->{media}{eltorito_img});
     if (defined $eltorito_img) {
-        -e $eltorito_img or die "cannot find Eltorito boot image $eltorito_img\n";
+        -e $eltorito_img or die "cannot find El Torito boot image $eltorito_img\n";
         cp_f($eltorito_img, $grub2_dir . '/eltorito.img');
     } else {
         build_grub2_eltorito_img($live, $grub2_dir . '/eltorito.img');
@@ -514,6 +528,9 @@ sub create_bootloader {
 
     my $label = $live->{media}->get_media_label;
 
+    # If the user has supplied a top-level grub2 configuration file, copy that
+    # (replacing the "VOLUME_LABEL" template with the actual label for the ISO
+    # image), otherwise build one.
     my $grub2_cfg = $grub2_dir . '/grub.cfg';
     if (defined $live->{media}{grub2_cfg}) {
         my $grub_cfg_template = get_absolute_path($live, $live->{media}{grub2_cfg});
@@ -526,17 +543,25 @@ sub create_bootloader {
 
     my $title = $label =~ s/-/ /gr;
 
+    # If we have a theme, replace the menu title with the name of the ISO
+    # (extracted from the disk label).
     my $base_theme_txt = $grub2_dir . "/themes/$theme_name/theme.txt";
     if (-e $base_theme_txt) {
         run_('sed', '-i', qq(s/title-text:.*/title-text: "$title"/), $base_theme_txt);
     }
 
+    # If we are building a 32-bit ISO, we are done, as we don't support
+    # 32-bit UEFI boot.
     return if $live->{settings}{arch} ne 'x86_64';
 
+    # Create another build directory. This will contain all the files we need
+    # to exist in the /EFI directory on the ISO.
     my $efi_root_dir = $live->get_builddir . $live->{prefix}{build}{EFI};
     my $efi_boot_dir = $efi_root_dir . '/BOOT';
     mkdir_p($efi_boot_dir);
 
+    # If the user has supplied a grub2 image for UEFI boot, copy that,
+    # otherwise build one.
     my $bootx64_efi = get_absolute_path($live, $live->{media}{bootx64_efi});
     if (defined $bootx64_efi) {
         -e $bootx64_efi or die "cannot find EFI boot image $bootx64_efi\n";
@@ -545,17 +570,24 @@ sub create_bootloader {
         build_grub2_bootx64_efi($live, $efi_boot_dir . '/bootx64.efi');
     }
 
+    # Build a grub2 configuration file for UEFI boot. This just chains to the
+    # main grub2 configuration file.
     output($efi_boot_dir . '/grub.cfg', build_uefi_grub2_cfg($live));
 
+    # If we have a theme, duplicate the theme configuration file and modify the
+    # title string to indicate we are doing a UEFI boot. This is useful when
+    # dealing with user bug reports...
     if (-e $base_theme_txt) {
         my $uefi_theme_txt = $grub2_dir . "/themes/$theme_name/theme-uefi.txt";
         cp_f($base_theme_txt, $uefi_theme_txt);
         run_('sed', '-i', qq(s/title-text:.*/title-text: "$title (UEFI)"/), $uefi_theme_txt);
     }
 
+    # Create another build directory for temporarily storing the ESP image.
     my $images_dir = $live->get_builddir . $live->{prefix}{build}{images};
     mkdir_p($images_dir);
 
+    # Construct an ESP image. This is needed for USB boot.
     my $esp_image = $images_dir . '/esp.img';
     eval { rm_rf($esp_image) };
     run_("/sbin/mkdosfs", "-F12", "-C", $esp_image, "4096");
@@ -811,9 +843,28 @@ sub create_iso_master {
 sub build_iso_image {
     my ($live, $dest, $label, $mbr_image, $esp_image, @opts) = @_;
 
-    my $boot = $live->get_media_prefix('boot');
-    my $EFI  = $live->get_media_prefix('EFI');
-
+    my $boot = $live->get_media_prefix('boot'); # normally '/boot'
+    my $EFI  = $live->get_media_prefix('EFI');  # normally '/EFI'
+
+    # This builds a hybrid ISO capable of both legacy and UEFI boot. The
+    # ISO contains a primary iso9660 partition (which is the only thing
+    # visible when booting from DVD) and a secondary ESP partition (which
+    # is only used for USB UEFI boot).
+    #
+    # For legacy boot, the system boots the grub2 El Torito image. For DVD
+    # boot, this is located via the El Torito catalogue. For USB boot, it
+    # is located via the grub2 MBR hybrid boot image, which is stored in
+    # the MBR. In both cases the initial grub2 root location is the iso9660
+    # partition, so the initial grub2 configuration file will be read from
+    # that partition.
+    #
+    # For UEFI boot, the system boots the grub2 EFI image. For DVD boot,
+    # this is located via the El Torito catalogue, and we store it in the
+    # iso9660 partition. For USB boot, it must be located in the /EFI/BOOT
+    # directory in the ESP. For DVD boot the initial grub2 root location is
+    # the iso9660 partition, for USB boot it is the ESP partition, and the
+    # initial grub2 configuration file will be located accordingly.
+    #
     run_('xorrisofs',
             '-pad', '-l', '-R', '-J',
             '-V', $label,
@@ -841,6 +892,7 @@ sub build_iso_image {
             if_($dest, '-o', $dest),
             @opts,
     ) or die "unable to run xorrisofs\n";
+
     if ($dest) {
         my $dir = dirname($dest);
         my $filename = basename($dest);