From Mageia wiki
Jump to: navigation, search



Drakconf multiflag.png
Other languages
English ; français ;
Synopsis:
draklive2 is a mastering tool that creates an ISO image containing a Mageia live system (or 'Live ISO' for short). The image is a hybrid ISO, allowing it to be used with both optical media and USB flash drives.

Contents

Overview

draklive2 uses the Mageia classical installer to create the live system, with a few subsequent tweaks to optimise the system for live use. It then compresses the resulting root file system (to reduce the size of the ISO image) and adds a GRUB2 boot loader to enable booting from the live media. The bootloader supports both legacy (MBR) and EFI boot.

draklive2 is the tool used to create the Live ISOs for the Mageia distribution. Mageia users can also use this tool to create their own custom Live ISOs containing a desktop environment or selection of packages not available in the official Mageia offerings.

Normally the composition of the Live ISO created by draklive2 is determined by a configuration file supplied by the user, but if an incomplete configuration is supplied, the classical installer will be run in GUI mode, allowing the user to select languages, desktop environments, and packages via the GUI.

Origins

draklive2 is an evolution of the original draklive tool. Unlike draklive, its only function is to create ISO images; creating disk images and copying images onto media is not supported.

The main enhancements to the original draklive tool are:

  • the ability to use the installer GUI to compose the live system
  • simplified text-based configuration
  • the GRUB2 bootloader is used for both legacy and EFI boot
  • the GRUB2 boot menu supports both language and keyboard selection and is itself translated into the selected language
  • both 32-bit and 64-bit EFI boot are supported
  • persistence is supported

Quickstart

To get started, first install the drakiso and drakiso-bootloader-files packages. If you intend to use the installer GUI, also install either the x11-server-xephyr or the x11-server-xnest package. Then, if you haven't already done so, install and configure sudo to allow you to execute commands that require root privileges. Finally, select one of the following three examples and follow the instructions for that example.

If draklive2 is run by the root user, sudo is not used and does not need to be installed.

Note:
You can create both 32-bit and 64-bit variants of your Live ISO, regardless of whether the system you are using to create them is 32-bit or 64-bit. However, if you wish to create a 64-bit EFI bootable ISO, you should install the x86_64 version of the drakiso-bootloader-files package, and if you wish to create a 32-bit EFI bootable ISO, you should install the i586 version of the drakiso-bootloader-files package.

Example 1 : Xfce Live ISO

This example creates a Live ISO based on the Xfce desktop environment. The result is very similar to the official Mageia Xfce Live ISOs.

To create the ISO:

1. Make a working copy of /usr/share/drakiso/examples/xfce. The filesystem containing your working copy should have at least 12GB of free space.

2. In the working copy, edit the file config/settings.cfg and adjust the following settings:

arch - either i586 or x86_64
repository - either a FTP or HTTP URL or a path to a local mirror of the repository

3. In a terminal window, change directory to the top-level directory of your working copy and execute the command:

draklive2 --clean --all

Example 2 : Custom Live ISO

This example creates a Live ISO based on selections made by the user in the installer GUI.

To create the ISO:

1. Make a working copy of /usr/share/drakiso/examples/gui. The filesystem containing your working copy should have at least 6GB of free space, and 12GB or more if you select a heavyweight desktop environment or a large number of packages.

2. In the working copy, edit the file config/settings.cfg and adjust the following settings:

arch - either i586 or x86_64
repository - either a FTP or HTTP URL or a path to a local mirror of the repository

If you want all languages and locales to be included, also add the line

region=all

(the user will be asked to choose a language when the live system boots).

If you want to use the default username "live" with no passwords, also add the line

default_user=live

If you want automatic login, also add the line

 default_session=<session name>

where <session name> is the Name value found in the session .desktop file (located in /usr/share/xsessions), after removing any white space.

And with drakiso v1.15 or later...

If you are going to distribute your ISO to other people, change the show_licence setting from no to yes.

If you want MageiaWelcome to autostart, change the show_welcome setting from no to yes.

If you want the live installer (draklive-install) to be included, change the live_installer setting from no to yes.

If you want the non-free drivers (NVIDIA and Broadcom wl) to be included, change the nonfree_drivers setting from no to yes.

If you want additional packages that can't be selected in the GUI to be included (or excluded), add a comma-separated list of package names to the include_packages (or exclude_packages) setting. Use the base package name, and don't add white space around the commas.

3. In a terminal window, change directory to the top-level directory of your working copy and execute the command:

draklive2 --clean--all

The installer GUI will start and allow you to choose your language(s), desktop environment(s), packages, user details, and miscellaneous system settings before going on to create the ISO image.

Note:
The bootloader will include support for all languages, regardless of the language(s) you select. See below for how to change this.

Example 3 : Minimal Live ISO

This example creates a Live ISO with a minimal text-only Mageia system. No graphics support is included.

To create the ISO:

1. Make a working copy of /usr/share/drakiso/examples/minimal. The filesystem containing your working copy should have at least 3GB of free space.

2. In the working copy, edit the file config/settings.cfg and adjust the following settings:

arch - either i586 or x86_64
repository - either a FTP or HTTP URL or a path to a local mirror of the repository

3. In a terminal window, change directory to the top-level directory of your working copy and execute the command:

draklive2 --clean --all

In more detail

draklive2 is started from the command line. It can be run by any user, as it will then use the sudo command to execute any operations that require root privileges. If started without any command line options, it will just print a summary of the available options and exit.

draklive2 creates the Live ISO in four major steps:

Root

This uses the classical installer to install a standard Mageia system into a dummy root file system and then performs any post-install customisation specified by the user. The only significant difference to a standard install is that it installs support for all hardware (rather than detecting what is required for the target machine), and (optionally) installs support for all locales.
This step is performed when either the --root or --all option is specified on the command line.

Boot

This prepares all the files needed for booting the live system. The dummy root filesystem must have been created before performing this step, as it is used to provide the Linux kernel image and create the initial RAM disk image used when booting the system.
This step is performed when either the --boot or --all option is specified on the command line. It does not normally need to be rerun if the Root step is rerun.

Loop

This compresses the dummy root file system into a squashfs file system image. This gets stored in the ISO image filesystem in the file /loopbacks/distrib.sqfs. When you boot the live system, this gets mounted (read-only) and merged with either a RAM disk or a persistent overlay partition using the overlayfs filesystem. This merging with a RAM disk or a persistent overlay partition is what allows changes to be made to a running live system.
This step is performed when either the --loop or --all option is specified on the command line. It must be rerun if the Root step is rerun. It only needs to be rerun after the Boot step is rerun if the initial RAM disk image changes.

Master

This creates the final ISO image from the files created in the Boot and Loop steps and generates any requested checksums.
This step is performed when either the --master or --all option is specified on the command line. It must be rerun if any of the previous steps are rerun.

If multiple steps are specified on the command line, draklive2 will execute them in the correct order, regardless of the order they appear.

The --clean option can be added on the command line to delete all files created by previous runs. Note that it uses the current settings to determine what to delete; there is no memory of what you last ran.

draklive2 normally outputs a relatively small amount of information as it progresses. The level of verbosity can be increased or decreased by adding the --verbose <level> option on the command line, where <level> ranges from 0 (minimum verbosity) to 4 (maximum verbosity).

ISO composition

The composition of the Live ISO is controlled via two files, a basic settings file and a build configuration file. draklive2 looks for these files in the directory specified by the --config-dir command line option (subsequently referred to as <config-dir>). If not specified, <config-dir> will be set to the current working directory.

Note:
draklive2 is highly configurable, but many of the options described below are rarely required and can be omitted in most cases. It is suggested that the user starts with one of the examples in /usr/share/drakiso/examples, and modifies the settings and build configuration as required.

Basic settings

The basic settings file contains a list of parameters for controlling the Live ISO creation. The name and location of this file can be specified by the --settings command line option. If not specified, the default is <config-dir>/config/settings.cfg.

Syntax

Each line of the basic settings file should contain a single parameter name and associated value, with the name and value separated by an '=' character, e.g.

arch=x86_64
release=6

Names should be simple alpha-numeric identifiers and must contain no white space. Values may be any sequence of characters. If a value is enclosed in either single or double quotes, the outermost pair of quote characters is discarded. No whitespace is allowed between the name and the '=' or, for quoted values, between the '=' and the first quote character or after the last quote character.

Lines starting with a '#' character are treated as comments and are ignored.

Note:
In the following sections, a setting name in angled brackets (e.g. <arch>) is used as shorthand for the setting value.

Required settings

draklive2 requires the following parameters to be defined:

arch

The architecture for the live system. Supported architectures are i586 and x86_64.

repository

The URL or path to the repository that will be used to create the live system. Only FTP or HTTP URLs are supported. The URL or path should end with the Mageia version number; the architecture will be appended automatically.

vendor

An arbitrary string of up to 128 characters identifying the person or organisation that is creating the Live ISO. This will be used as the Publisher ID in the ISO meta-data.

Optional Settings

draklive2 recognises the following optional parameters:

default_session

The default session name used for automatic login. This should be the Name value found in the session .desktop file (located in /usr/share/xsessions), after removing any white space.
If not specified, no default session name will be defined for automatic login.

default_user

The username of the default user of the live system. This should be a valid Linux username. If specified, the system will be configured to automatically log in that user after booting.
If not specified the installer GUI will be run and present the user management screen.

desktop

An arbitrary string. Only used for constructing the Live ISO name.

distro

An arbitrary string. Only used for constructing the Live ISO name.

media

An arbitrary string. Only used for constructing the Live ISO name.

product

An arbitrary string. Only used for constructing the Live ISO name.

region

The set of locales that will be included on the Live ISO. This can either be the name of a set of locales defined in the build configuration file or the special value all (which causes all available locales to be included).
If not specified the installer GUI will be run and present the language and keyboard selection screens.

release

An arbitrary string. Only used for constructing the Live ISO name.

set

An option inherited from draklive. Untested in draklive2.

workdir

The path to the base working directory for draklive2. All files created by draklive2 will be stored in a subdirectory (named as the Live ISO name) below this directory.
If not specified, the current working directory will be used.

User settings

The user can add additional parameters in the basic settings file for use within the build configuration file. draklive2 will ignore these parameters.

Overriding settings

A setting can be overridden (or added) by using the --define <name>=<value> command line option.

Build configuration

The build configuration file specifies all aspects of the Live ISO composition. The name and location of this file can be specified by the --config command line option. If not specified, the default is <config-dir>/config/build.cfg.

Syntax

The build configuration is composed from the following basic data types:

number
any sequence of decimal digits
string
any sequence of characters enclosed in either single or double quotes. If enclosed in single quotes, the enclosed string is used exactly as written. If enclosed in double quotes, certain characters have special meaning, as described below.
array
any sequence of elements separated by commas and enclosed in square brackets, e.g. ['a','b','c']. Any amount of white space may be added between the elements and the punctuation. Elements may be of any data type. Occasionally arrays are used to hold pairs of values, in which case the '=>' digraph may be used to separate the two elements in each pair instead of a comma.
associative array
any sequence of key/value pairs separated by commas and enclosed in curly brackets, with the key and value separated by the '=>' digraph, e.g. {a=>1,b=>2} . Any amount of white space may be added between the keys and values and the punctuation. Keys should be simple alpha-numeric identifiers (i.e. contain no white space). Values may be of any data type.

A '#' character outside a string starts a comment. It and all subsequent characters on the same line are ignored.

Readers familiar with Perl will have already realised that the build configuration file uses Perl syntax. The file may, in fact, contain any Perl constructs; the only restriction being that the associative array describing the build configuration is the last item in the file.

Double-quoted strings are therefore interpreted according to Perl rules. As well as the usual escape sequences common to most programming languages (e.g. "\n" for a new line), any Perl variable will be expanded to the variable value. See the Perl language documentation for more details.

Note:
In the following sections, a configuration key in curly brackets (e.g. {system}{vga_mode}) is used as shorthand for the configuration value.

Keys

The complete build configuration is an associative array which may contain the following keys:

system (required)

An associative array containing the configuration values used to create and customise the live system during the Root step. It may contain the following keys:
enabled_media (required)
An array specifying the media within the selected repository that are to be enabled when running the classical installer to create the live system. Each element of the array should be a string specifying the name of a medium, e.g. 'Core Release', 'Core Updates'.
rpmsrate_flags (optional)
An array specifying the rpmsrate categories to be included when the classical installer selects packages. Each element of the array should be a string specifying the name of a category, e.g. 'CAT_OFFICE', 'CAT_VIDEO'. See the <arch>/media/media_info/rpmsrate file in the selected repository to learn what packages are included in each category.
If not specified, the installer GUI will be run and present the desktop and package selection screens.
rpmsrate_level (optional)
A number specifying the threshold for package selection within the rpmsrate categories. Packages with a rating in the rpmsrate file less than this number will not be included when a rpmsrate category is selected.
If not specified, the default level is 5.
include_packages (optional)
An array specifying a list of additional packages to be included when the classical installer selects packages. Each element of the array should be a string specifying the base name of a package.
This applies even when the installer GUI is used to select packages.
exclude_packages (optional)
An array specifying a list of packages to be excluded when the classical installer selects packages. Each element of the array should be a string specifying the base name of a package.
This applies even when the installer GUI is used to select packages.
preferred_packages (optional)
An array specifying a list of preferred packages to be used when the classical installer is selecting package dependencies. Each element of the array should be a string specifying the base name of a package.
local_repo_packages (optional)
An array specifying a list of packages to be stored in a local repository in the live system. Each element of the array should be a string specifying the base name of a package. These packages will be available to be installed (using urpmi or rpmdrake) when the live system is running. Note that these packages will be automatically excluded when the classical installer is selecting packages.
local_repo_biarch_packages (optional)
An array specifying a list of package names for which both the 32-bit and 64-bit version of the package should be included in the live system local repository.
langs_always (optional)
An array specifying a list of locales that will always be included, regardless of the region setting. Each element of the array should be a string specifying one locale (e.g. 'en_US').
post_install_nr (optional)
A string specifying a bash shell command string that will be executed by the classical installer in the build system environment at the end of the installation process.
post_install (optional)
A string specifying a bash shell command string that will be executed by the classical installer inside a chroot to the dummy root filesystem at the end of the installation process.
additional_media (optional)
An array specifying a list of media from which additional packages can be installed, and optionally, the packages to be installed from those media. The media will be added using urpmi.addmedia in the order given. Each element of the array should be an associative array containing the following keys:

name (required)

A string specifying the medium name passed to urpmi.addmedia. If set to '--distrib', the --distrib option will be passed to urpmi.addmedia instead of a name.

path (required)

A string specifying the medium URL or path passed to urpmi.addmedia.

packages (optional)

An array specifying a list of packages to be installed from this medium. Each element of the array should be a string specifying the base name of a package.
rpms (optional)
An array specifying a list of additional RPM packages to be installed in the dummy root filesystem. Each element of the array should be a string specifying the path to a RPM file. A relative path will be taken as relative to <config-dir>. Any package dependencies not included in this list will be searched for and installed from the full set of media specified in additional_media.
erase_rpms (optional)
An array specifying a list of packages to be removed once all package installation has been performed. Each element of the array should be a string specifying the base name of a package.
disable_services (optional)
An array specifying a list of services to be disabled (using systemctl). Each element of the array should be a string specifying the base name of a service; the .service extension will be added automatically.
disable_timers (optional)
An array specifying a list of timers to be disabled (using systemctl). Each element of the array should be a string specifying the base name of a timer; the .timer extension will be added automatically.
files (optional)
An array specifying a list of files to be copied into the dummy root filesystem. Each element of the array should itself be a two or three element array containing:
  • a string specifying the path to the file(s) to be copied. The path may include simple wildcards (* and ?) and may either specify individual files or whole directories. A relative path will be taken as relative to <config-dir>.
  • a string specifying the destination. This should be an absolute path in the dummy root filesystem. If the string ends with a '/', it is assumed to be a directory and file names will be preserved. A directory must be specified if multiple files are being copied.
  • (optionally) an associative array containing the following keys:

mode (optional)

A 4 digit number specifying the copied file mode in octal format.

no_install (optional)

A number specifying whether the files should be removed from the installed system if draklive-install is used to install the live system. Any non-zero number will cause the files to be removed by draklive-install.
remove_files (optional)
An array specifying a list of files or directories to be deleted from the dummy root filesystem. Each element of the array should be a string specifying an absolute path in the dummy root filesystem. The path may include simple wildcards (* and ?) and may either specify individual files or whole directories.
patches (optional)
An array specifying a list of patches to apply to the dummy root filesystem. Each element of the array should be a string specifying the path to a patch file. A relative path will be taken as relative to <config-dir>. File paths inside the patch file should be relative to the root of the dummy root filesystem.
final_fixes (optional)
A string specifying a bash shell command string that will be executed inside a chroot to the dummy root filesystem after all other customisation steps have been performed.
append (optional)
A string specifying the default options that should be passed on the boot command line when the live system is booted. If specified, this string will be appended to the command line in every boot menu entry.
vga_mode (optional)
A number specifying the vga mode that should be passed on the boot command line when the live system is booted. If specified, vga={system}{vga_mode} will be appended to the command line in every boot menu entry.

loopbacks (optional)

An associative array containing the configuration values used when compressing the dummy root filesystem during the Loop step. It may contain the following keys:
exclude (optional)
An array specifying files to be excluded when compressing the dummy root filesystem. Each element of the array should be an associative array containing one (and only one) of the following keys:

path

A string specifying an absolute path in the dummy root filesystem. The path may include simple wildcards (* and ?) and may either specify individual files or whole directories.

source

A string specifying an absolute path in the dummy root filesystem. The path should identify a file that contains a further list of absolute paths to files to be excluded. The file should contain one path per line.
compression (optional)
(draklive2 v1.14 or later)
A string specifying the compression mode used when compressing the dummy root filesystem. This may be any valid argument to the -comp option of the mksquashfs command. If the zstd compression mode is chosen, it may be followed by a colon and a numeric value specifying the compression level.
If not specified, the default is 'zstd:18'.

regions (optional)

An associative array that defines sets of locales that may be included in the Live ISO. The key names may be freely chosen by the user. Each key should be associated with an array of strings specifying a list of locales for that key.
During the Root step, draklive2 will select the set of locales identified by <region>.

media (required)

An associative array containing the configuration values used when preparing the bootloader files during the Boot step and when creating the final ISO image during the Master step. It may contain the following keys:
label (required)
A string specifying the volume label for the ISO image.
overlay_label (optional)
A string specifying the volume label used to identify the optional persistent overlay partition.
If not specified, the bootloader will not search for an updated kernel in the persistent overlay partition. This does not affect dracut, which will still search for and use a persistent overlay partition if one exists.
bootloader_title (optional)
A string specifying the title line for the bootloader screen.
If not specified, {media}{label} will be used, with any '-' characters in the label replaced by spaces.
bootloader_theme (optional)
A string specifying the path to a directory containing the theme files to be used by the bootloader. A relative path will be taken as relative to <config-dir>.
If not specified, /boot/grub2/themes/maggy will be used if it is present on the build system, otherwise, no bootloader theme will be included in the Live ISO.
bootloader_font (optional)
A string specifying the path to a file containing the default boot loader font. This should be a GRUB2 (.pf2) font file. A relative path will be taken as relative to <config-dir>.
If not specified, /usr/share/grub/unicode.pf2 will be used if it is present on the build system, otherwise, no default boot loader font will be included in the Live ISO and the bootloader will fall back to text mode.
bootloader_langs (optional)
A string specifying the path to a file containing the list of languages to be included in the bootloader language selection menu. A relative path will be taken as relative to <config-dir>.
If not specified, the language selection menu will not be included in the bootloader.
bootloader_kbds (optional)
A string specifying the path to a file containing the list of keyboard types to be included in the bootloader keyboard selection menu . A relative path will be taken as relative to <config-dir>.
If not specified, the keyboard selection menu will not be included in the bootloader.
bootloader_messages (optional)
A string specifying the path to a directory containing message translations for the bootloader. Only compiled translation (.mo) files will be included in the Live ISO.
bootloader_default (optional)
A number specifying the bootloader menu entry that will be selected by default. Entries are numbered starting from zero.
If not specified, the first boot loader menu entry will be the default.
bootloader_timeout (optional)
A number specifying the delay in seconds before the bootloader automatically boots from the default entry.
If not specified, the delay will be 4 seconds.
bootloader_entries (optional)
An array of paired values specifying the bootloader menu entries. The first element in each pair should be a string specifying the menu entry title. The second element in each pair should be an associative array containing the following keys:

command (optional)

A string specifying the GRUB2 command that will be executed when the menu entry is selected. This should either be 'linux' or 'linux16'.
If not specified, the linux command will be used.

image (optional)

A string specifying the path to the kernel image that will be used for this menu entry.
If not specified, /boot/vmlinuz will be used, which is the kernel copied from the dummy root filesystem during the Boot step.

initrd (optional)

A string specifying the path to the initial RAM disk image that will be used for this menu entry. If not specified, /boot/initrd.gz will be used, which is the initial RAM disk image created during the Boot step. The special value 'none' may be used to indicate that there is no initial RAM disk image for this menu entry.

append (optional)

A string specifying additional options to append to the boot command line for this menu entry. Any options that are automatically added by draklive2 will be added before this string.
mbr_boot_img (optional)
A string specifying the path to the GRUB2 MBR bootloader image for hybrid boot. A relative path will be taken as relative to <config-dir>.
If not specified, /usr/lib/grub/i386-pc/boot_hybrid.img will be used if it exists on the build system, otherwise draklive2 will terminate with an error.
eltorito_img (optional)
A string specifying the path to the GRUB2 El Torito bootloader image. A relative path will be taken as relative to <config-dir>.
If not specified, draklive2 will use grub2-mkimage to build the El Torito boot loader image.
iso_part_start (optional)
A number specifying the starting sector for the hybrid ISO protective partition that protects the iso9660 filesystem. This should either be 0 or 1. The option of starting at sector 1 is provided for compatibility with some old BIOSs.
If not specified, the protective partition will start at sector 0.
iso_part_type (optional)
A string specifying the partition type for the hybrid ISO protective partition that protects the iso9660 filesystem. This should be a two-digit hexadecimal number in 'C' format, e.g. '0x00'.
If not specified, the protective partition type will be set to '0x00'.
efi_type (optional)
A string specifying the EFI boot type(s) to be supported. This should be one of 'none', '32bit', '64bit', or 'all'.
If not specified, the default is 'none'.
boot32_efi (optional)
A string specifying the path to the GRUB2 32-bit EFI boot loader image. A relative path will be taken as relative to <config-dir>.
If not specified, draklive2 will use grub2-mkimage to build the 32-bit EFI boot loader image if it is required (this requires the 32-bit grub2-efi package to be installed on the build system).
This key is ignored if the EFI boot type is set to 'none' or '64bit'.
boot64_efi (optional)
A string specifying the path to the GRUB2 64-bit EFI boot loader image. A relative path will be taken as relative to <config-dir>.
If not specified, draklive2 will use grub2-mkimage to build the 64-bit EFI boot loader image if it is required (this requires the 64-bit prog|grub2-efi}} package to be installed on the build system).
This key is ignored if the EFI boot type is set to 'none' or '32bit'.
copy_from_repo (optional)
An array of paired values specifying a list of files or directories to be copied from the repository to the ISO image filesystem. The first element in each pair should be a string specifying the path to the file or directory to be copied (relative to the <arch> directory in the repository). The second element in each pair should be a string specifying the path to the file or directory in the ISO image filesystem (relative to the root of the filesystem). Intermediate directories in the ISO image filesystem will be automatically created as required.
If <repository> is a FTP or HTTP URL, the list may only contain files, not directories.
checksums (optional)
An array specifying a list of checksum types that should be calculated from and stored alongside the ISO image file. Each element of the array should be a string specifying a checksum type. Recognised types are:
  • 'md5' - a 128-bit MD5 checksum, stored in a file with the extension .md5
  • 'sha1' - a 160-bit SHA-1 checksum, stored in a file with the extension .sha1
  • 'sha2' - a 512-bit SHA-2 checksum, stored in a file with the extension .sha512
  • 'sha3' - a 512-bit SHA-3 checksum, stored in a file with the extension .sha3
If not specified, no checksums will be generated.

iso_name_fields (optional)

An array specifying the settings values used to construct the Live ISO name, which is used both to name the working subdirectory and as the base name for the ISO image file and associated checksum files. Each element of the array should be a string specifying the name of one setting. The settings values will be separated by '-' characters when constructing the Live ISO name.
If not specified, the default name for the Live ISO is <distro>-<release>-<product>-<desktop>-<region>-<arch>-<media>. Null settings are skipped, as is the region setting if it is set to all.

Using settings

Before reading the build configuration file, draklive2 will read the basic settings file and store the settings in an associative array contained within an object that is stored in the global $build variable. This allows the settings to be used in the build configuration file. For example, the arch setting can be obtained by $build->{settings}{arch}. Shortcuts can be created by declaring local variables, e.g.

my $arch = $build->{settings}{arch};

which can then be used within double-quoted strings.

Useful Perl functions

A useful shortcut is the Perl built-in qw() function. This converts a sequence of plain words into a comma-separated list of quoted strings, e.g.

qw(a b c)

is equivalent to

'a', 'b', 'c'

Before reading the build configuration file, draklive2 imports the MDK::Common Perl library, so the build configuration file may use any function exported by this library. A useful function is if_(), which allows items to be conditionally included in a list. So for example, if the local variable $arch is set to x86_64

'a', 'b', if_($arch eq 'x86_64', 'c', 'd')

is equivalent to

'a', 'b', 'c', 'd'

otherwise, it is equivalent to

'a', 'b'

Syntax checking

Because the build configuration file uses Perl syntax, the Perl interpreter can be used to check that there are no syntax errors in the file before running draklive2. Just run

perl -qw <file>

(where <file> is the path to the file). To avoid a spurious warning, you need to assign the top-level associative array to a variable, e.g.

my $config = { ... };

Bootloader menus

Main menu

This menu will present the items specified by the user in {media}{bootloader_entries}. If a persistent overlay partition identified by {media}{overlay_label} is detected and contains an updated kernel, this will then be followed by a menu entry that selects between the latest kernel in the persistent overlay and the original kernel in the base ISO image. If the user has specified a {media}{bootloader_langs} file, this will then be followed by a menu entry that selects the language selection menu. If the user has specified a {media}{bootloader_kbds} file, this will then be followed by a menu entry that selects the keyboard selection menu.

Language selection menu

This menu will present the list of languages specified by the {media}{bootloader_langs} file. The file should contain an array of paired values, using the same syntax as the build configuration file except that the array is enclosed in round brackets instead of square brackets. The first element in each pair should be a string specifying the language code (e.g. 'en_US'). The second element in each pair should be a string specifying the displayed name of the language. If the file is UTF-8 coded, precede the array with the line

use utf8;

See /usr/share/drakiso/bootloader/lang-names.txt for an example.

When an entry is selected in this menu, the bootloader lang environment variable will be set to the selected language code, enabling the bootloader menus to be translated if the necessary translations have been provided in the {media}{bootloader_messages} directory.

When an ordinary entry in the main menu is selected, the bootloader will add a lang=<language code> option to the boot command line to pass the most recently selected language code to the live system.

Keyboard selection menu

This menu will present the list of keyboards specified by the {media}{bootloader_kbds} file. The file should contain an array of paired values, using the same syntax as the build configuration file except that the array is enclosed in round brackets instead of square brackets. The first element in each pair should be a string specifying the keyboard code (e.g. 'en'). The second element in each pair should be a string specifying the displayed name of the keyboard. If the file is UTF-8 coded, precede the array with the line

use utf8;

See /usr/share/drakiso/bootloader/kbd-names.txt for an example.

When an ordinary entry in the main menu is selected, the bootloader will add a kbd=<keyboard code> option to the boot command line to pass the most recently selected keyboard code to the live system.

If a file named lang-kbds.txt exists in the same directory as the {media}{bootloader_langs} file, the lang-kbds.txt file will be used to determine the default entry in the keyboard selection menu, once a language has been selected. The file should contain an associative array where the keys are the language codes and the associated values are the default keyboard codes.

See /usr/share/drakiso/bootloader/lang-kbds.txt for an example.

Note:
It was intended that the keyboard selection menu would also be used to change the keyboard mapping in the bootloader, but GRUB2 does not provide a reliable way to do this.

Translations

All text in the main menu and keyboard selection menu is translatable. The language names in the language selection menu are not translatable - it is assumed each language name will be provided in its native form in the {media}{bootloader_langs} file.

dracut configuration

The dracut configuration for generating the live system initial RAM disk will need adjustment. The two essential changes are

hostonly="no"
add_dracutmodules+=" mgalive "

The mgalive module handles mounting the compressed loopback filesystem; without this, the live system cannot be booted. The mgalive module also handles the detection and use of a persistent overlay partition. The label specified in {media}{overlay_label} should match the label searched for by the mgalive module, which is currently mgalive-persist.

See /usr/share/drakiso/examples/minimal/files/dracut-live.conf for an example of other changes that may be required.