Peppermint OS ISO Builder

Table of Contents

1. Project Description
2. Prerequisites
3. Installation
4. Usage
   • Listing Available Options
   • Building an ISO
   • Command-Line Arguments
5. Configuration
   • General ISO Configuration (iso_build_config_*.yaml)
   • Desktop Environment Configuration (desktops/*.yaml)
   • Kernel Configuration (kernels/kernels.yaml)
   • Common Packages (packages/common_packages.yaml)
   • Repository Configuration (repositories.yaml)
6. Customization
   • Adding Extra Packages
   • Changing Default Settings
   • Including Custom Files
7. Building the ISO Process
8. Acknowledgements
9. Contributing
10. License

Project Description

The Peppermint OS ISO Builder is a comprehensive tool designed to generate custom installation images for Peppermint OS. Built upon the solid foundation of Void Linux, this builder provides the flexibility to create tailored Peppermint OS distributions to meet specific user needs or hardware configurations. It automates the process of bootstrapping a minimal Void Linux system, installing necessary packages for a chosen desktop environment and kernel, applying Peppermint OS specific customizations, and generating a bootable ISO image. This allows for experimentation with different desktop environments, kernel versions, and package sets without manually configuring each component.

Prerequisites

Before you begin, ensure your system meets the following prerequisites:

• A Running Linux Distribution: The builder is designed to run on a Linux system.
• Python 3: Python 3 must be installed on your system. You can check your Python version by running python3 --version in your terminal.
• Python Libraries: The following Python libraries are required. You can install them using pip3 install <library_name>:
  • pyyaml
  • argparse
• Essential Build Tools: While the builder scripts handle much of the process, you might need basic build tools and utilities available on your system for certain bootstrap and package installation steps.
• Sufficient Disk Space: Building an ISO image requires a significant amount of disk space for downloading packages, creating temporary files, and generating the final ISO. Ensure you have at least 20-30 GB of free space.
• Internet Connection: A stable internet connection is necessary to download packages from the Void Linux repositories.

Installation

1. Clone the Repository: Obtain the Peppermint OS ISO Builder scripts and configuration files by cloning the relevant repository. The exact command will depend on where the repository is hosted (e.g., GitHub, GitLab). For example:

   git clone <repository_url>
   cd <repository_directory>
   

Usage

The primary script for building the ISO is iso_builder.py. It accepts several command-line arguments to control the build process.

Listing Available Options

Before building, you might want to see the available architectures, desktop environments, and kernel types. You can run the script without any specific build commands to see the help message, which will list the available choices based on the configuration files:

python3 iso_builder.py -h

This will display the help information, including the available options for the <architecture>, --desktop, and --kernel arguments.

Building an ISO
To start the ISO build process, use the following command structure:

Bash

python3 iso_builder.py <architecture> --desktop <desktop> --kernel <kernel> -o <output_directory>
Replace the placeholders with your desired values.

Example:

To build a 64-bit ISO with the XFCE desktop and the Long Term Support (LTS) kernel, saving the output to a directory named custom_isos in your current location, you would run:

Bash

python3 iso_builder.py x86_64 --desktop xfce --kernel lts -o custom_isos
Command-Line Arguments
Here's a more detailed explanation of the command-line arguments:

<architecture>: Specifies the target architecture for the ISO. Common options include x86_64, i386, and aarch64. The available options are determined by the configuration files in the builder/configs directory.
--desktop <desktop>: Sets the desktop environment to be included in the ISO. Supported options are typically xfce, enlightenment, and cinnamon, but can be extended by adding new configuration files in the builder/configs/desktops/ directory. The default is xfce.
--kernel <kernel>: Determines the kernel type to be used. Common options include current, lts, and potentially other specific kernel versions like stable-6.9. The available options are defined in the builder/configs/kernels/kernels.yaml file. The default is current.
-o, --output-iso <path>: Defines the directory where the generated ISO file will be saved. If the directory does not exist, it will likely be created. The default path is builder/iso.
--debug: When this flag is added, the script will output more detailed logging information, which can be helpful for troubleshooting any issues during the build process.
--repos-file <path>: Allows you to specify a custom path to the repositories.yaml file, which defines the Void Linux repositories used for downloading packages. The default path is builder/configs/repositories.yaml.
Configuration
The behavior of the ISO builder is largely controlled by the configuration files. Understanding these files is key to creating customized ISO images.

General ISO Configuration (iso_build_config_*.yaml)
Located in the builder/configs/iso_build_config/ directory, these files (e.g., iso_build_config_x86_64.yaml) contain settings that apply to the overall ISO generation process for a specific architecture. This includes:

iso_volume_label: The label assigned to the ISO image.
output_iso_filename: The name of the generated ISO file.
boot_timeout: The timeout in seconds for the bootloader menu.
boot_default_entry: The default entry to boot from the bootloader menu.
default_locale: The default language and locale settings for the system.
default_keymap: The default keyboard layout.
compression_level: The compression level used for the SquashFS image.
hostname: The default hostname for the live system.
default_timezone: The default timezone.
boot_cmdline: Kernel command-line parameters.
plymouth: Configuration for the Plymouth boot splash screen.
grub: GRUB bootloader specific settings.
grub_modules_efi: Additional GRUB modules for EFI booting.
rootfs: Settings related to the root filesystem, including the target architecture and kernel type.
You can modify these settings to customize various aspects of the live environment and the generated ISO.

Desktop Environment Configuration (desktops/*.yaml)
The files in the builder/configs/desktops/ directory (e.g., xfce.yaml, enlightenment.yaml, cinnamon.yaml) define the specifics for each supported desktop environment. This includes:

name: The display name of the desktop environment.
description: A brief description of the desktop environment.
desktop_packages: A list of packages that are essential for the desktop environment.
login_manager_packages: Packages related to the login manager (e.g., LightDM).
services_enable: System services that should be enabled by default.
display_server: The display server to use (e.g., xorg).
login_manager: The login manager to use (e.g., lightdm).
desktop_environment: The session name for the desktop environment.
lightdm_session: The specific session to launch with the login manager.
lightdm_greeter: Configuration for the LightDM greeter (login screen).
default_packages: Additional default applications to include.
customizations_path: A path to a directory containing desktop-specific customization files.
copy_files: A list of files to copy to specific locations within the root filesystem.
plymouth_theme: Desktop-specific Plymouth theme settings.
By editing these files, you can precisely control which packages and settings are included for each desktop environment.

Kernel Configuration (kernels/kernels.yaml)
The builder/configs/kernels/kernels.yaml file defines the available kernel types and their corresponding package names in the Void Linux repositories. You can add or modify entries here to support different kernel versions. Each kernel type entry typically includes the package_name.

Common Packages (packages/common_packages.yaml)
The builder/configs/packages/common_packages.yaml file lists packages that should be included in all ISO builds, regardless of the chosen desktop environment. This is useful for including essential utilities or system tools.

Repository Configuration (repositories.yaml)
The builder/configs/repositories.yaml file specifies the Void Linux repositories that the builder will use to download packages. You can configure different repositories or mirrors here if needed.

Customization
The Peppermint OS ISO Builder offers several ways to customize the generated ISO images:

Adding Extra Packages
You can include additional packages by modifying the default_packages list in the appropriate desktop environment configuration file (desktops/*.yaml) or by adding them to the additional_packages field within the rootfs section of the iso_build_config_*.yaml file.

Changing Default Settings
Modify the settings within the iso_build_config_*.yaml files to alter default behaviors such as the hostname, timezone, locale, and boot options.

Including Custom Files
The copy_files section in the desktop environment configuration files allows you to specify files to be copied from a source location to a destination within the ISO's root filesystem. This can be used to include custom wallpapers, themes, scripts, or configuration files. The customizations_path setting further points to a directory where you can organize desktop-specific customization files that will be copied into the root filesystem.

Building the ISO Process
The iso_builder.py script orchestrates the following steps to build an ISO image:

Initialization: Sets up the necessary directories and environment variables.
Bootstrap: Creates minimal Void Linux environments (rootfs, peptarget, pephost) using xbps.
Package Installation: Installs common packages, desktop environment packages, and the specified kernel into the root filesystem.
System Reconfiguration: Updates the bootloader configuration and performs other system-level setup within the chroot environment.
Customization: Copies custom files and applies desktop-specific configurations.
Initramfs Creation: Generates the initial RAM filesystem.
Bootloader Generation: Creates configuration files for ISOLINUX (BIOS) and GRUB EFI (UEFI).
SquashFS Image Creation: Compresses the root filesystem into a SquashFS image.
ISO Generation: Uses the generated files and configurations to create the final bootable ISO image.
Cleanup: Removes temporary files and directories.
Finalization: Moves the generated ISO to the specified output directory.
Acknowledgements
We extend our deepest appreciation to the Void Linux Project and its dedicated community. The stability, flexibility, and the innovative xbps package manager of Void Linux provide the essential foundation for Peppermint OS. This project would not be possible without their hard work and commitment to open-source principles.

Contributing
Contributions to the Peppermint OS ISO Builder are welcome. If you have suggestions, bug reports, or would like to contribute code, please refer to the project's contribution guidelines (if available) or contact the Peppermint OS team.

License
This project is licensed under the GNU General Public License version 3 or later (GPL-3.0-or-later). A copy of the license can be found in the LICENSE file within the project repository.