From 04e2b14c395ede7933addb7c4c68e1eca35468c8 Mon Sep 17 00:00:00 2001 From: Martin Whitaker Date: Thu, 4 Jan 2018 12:30:38 +0000 Subject: Improved documentation and error messages. --- lib/MGA/DrakISO/BuildBoot.pm | 42 ++++++++++++++++++++++++++++-------------- lib/MGA/DrakISO/BuildISO.pm | 15 +++++++-------- lib/MGA/DrakISO/BuildLoop.pm | 8 ++++++++ lib/MGA/DrakISO/BuildMedia.pm | 10 ++++++++-- lib/MGA/DrakISO/BuildRoot.pm | 14 ++++++++++++++ lib/MGA/DrakISO/Loopback.pm | 8 ++++++++ lib/MGA/DrakISO/Mounts.pm | 7 +++++++ lib/MGA/DrakISO/Storage.pm | 8 ++++++++ lib/MGA/DrakISO/Utils.pm | 4 ++++ 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; -- cgit v1.2.1