lbhelper documentation

lbhelper is a library helps you to customized Debian images.

About lbhelper

Basically, lbhelper is a Python wrapper of Debian Live Build. It provides a set of declarative targets to define customization options supported by the Live Build. You don’t need to have all knowledge about the Live Build to use this library. Instead, this document covers necessary information about supported options and build process, which is enough for you to use this library.

What is Live Build And How it Works

Live Build is a toolset for building Debian based images. The project is maintained by Debian and used to build official Debian Live Images. This tool is also used by some Debian based distributions like Kali Linux.

To create a customized image via Live Build, we need to create a directory to store configurations. Each sub-directory represents different different configuration as below shows:

├── auto                        # live-build auto-scripts. Defines config/build/cleanup options for live-build.
└── config
    ├── archives                # Package mirrors/repositories
    ├── hooks                   # Extra scripts to run during build stages
    │   ├── live                # Hooks to run on live system
    │   └── normal              # Hooks to run on both live and installed system
    ├── includes.binary         # Files to include on the ISO/CD Rom filesystem
    ├── includes.chroot         # Files to include in the live system's filesystem
    ├── package-lists           # Packages to install
    │   ├── *.list.chroot       # Packages to install on both installed and live system
    │   └── *.list.chroot_live  # Packages to install only on live system
    ├── packages.chroot         # Standalone .deb packages to install on both installed and live system
    ├── apt/preferences         # Build time aptitude preference. Takes effect while building imaage
    ├── etc/apt/preferences     # Aptitude preference from installed system.
    └── bootloaders             # Bootloaders for live system

Live and Installed System

An image built from Live Build is a live system which can run directly on Live CD or Live USB. By contrast, a system installed from a live system is called installed system. Live Build allows you to customize packages and scripts run on live and installed systems, which gives you more flexibilities while defining and distributing your images. For instance, you might want to include calamares installer in your live system, which is not expected on an installed system.

Build Process

Live Build follows the sequence of stages to build an image:

  1. [Bootstrap] Setup a Debian chroot directory. All changes will happen there and won’t cause impacts to host.

  2. [Chroot] Chroot to the directory.

  3. [Packages] Installing packages (/packages-lists).

  4. [Hooks] Run hooks scripts (/hooks).

  5. [Binary] Includes static files ( /includes.* ).

  6. [Imaging] Create live image ISO.

What lbhelper Can Do For You

In lbhelper, configurable options are turned into Targets classes. You can pass these targets to an unified function, build_image, to create configurations required by Live Build and customize build parameters. Instead of directly managing/tracking multiple files across configuration directory, lbhelper helps you organize config dependencies as Python modules. This approach reduces complexity of configuration management.

Additionally, for some common configuration patterns like setting up GRUB or AppImages, lbhelper provides extensions to simplify setup works.

What lbhelper Doesn’t Solve

As the orders of actions in build process are immutable, you still need to carefully manage file dependencies by yourself. For instance, it’s not possible to run a script included in Binary stage in Hooks stage.

What’s Next

Now you should have basic understanding about what lbhelper can do for you. You can jump to different sections to learn how to use it.

Contents: