Live-build Documentation for Nanite Project

Overview

Live-build is a set of scripts used to build Debian Live systems. It’s the official tool for creating custom Debian-based distributions and is maintained by the Debian Live team.

Installation

To install live-build on a Debian system:

sudo apt-get update
sudo apt-get install live-build

Basic Workflow

The basic workflow for creating a custom Debian Live system consists of:

Create a build directory:
```
mkdir nanite-build && cd nanite-build
```
Configure the build:
```
lb config
```
Build the image:
```
sudo lb build
```

Build Stages

The build process is divided into four main stages:

Bootstrap Stage: Initial phase of populating the chroot directory with packages to make a barebones Debian system.
Chroot Stage: Completes the construction of the chroot directory, populating it with all packages listed in the configuration and other materials. Most customization occurs in this stage.
Binary Stage: Builds a bootable image, using the contents of the chroot directory to construct the root filesystem for the Live system.
Source Stage: If enabled, builds a source tarball after the live image is built.

Configuration Structure

Live-build uses a configuration directory structure under config/:

config/bootstrap/: Configuration for the bootstrap stage
config/chroot/: Configuration for the chroot stage
config/binary/: Configuration for the binary stage
config/source/: Configuration for the source stage

Key Configuration Files

Package Lists: config/package-lists/*.list.chroot - Define packages to include
Hooks:
- config/hooks/live/*.hook.chroot - Scripts run during the chroot stage
- config/hooks/live/*.hook.binary - Scripts run during the binary stage
Includes:
- config/includes.chroot/ - Files to include in the live system
- config/includes.binary/ - Files to include in the binary image

Image Types

Live-build can create several types of images:

ISO Hybrid: Most versatile, can be used on virtual machines, optical media, or USB drives
```
lb config --binary-images iso-hybrid
```
HDD: For specific use cases, creates a disk image
```
lb config --binary-images hdd
```
Netboot: For network booting
```
lb config --binary-images netboot
```

Customization Options

Build-time vs. Boot-time Configuration

Build-time options: Applied during image creation
Boot-time options: Applied when the live system boots
- Early boot options: Applied by live-boot package
- Later boot options: Applied by live-config package

Package Selection

To specify custom package lists:

echo "package1 package2 package3" > config/package-lists/custom.list.chroot

Custom Content

To include custom files in the live system:

mkdir -p config/includes.chroot/path/to/destination
cp /path/to/source/file config/includes.chroot/path/to/destination/

Custom Scripts (Hooks)

To run custom scripts during build:

mkdir -p config/hooks/live
cat > config/hooks/live/custom.hook.chroot << EOF
#!/bin/sh
# Custom script to run during chroot stage
echo "Running custom hook"
# Add your commands here
EOF
chmod +x config/hooks/live/custom.hook.chroot

Advanced Configuration

Preseed Files

For automated installations:

mkdir -p config/includes.installer
cp preseed.cfg config/includes.installer/

Boot Parameters

To set default boot parameters:

lb config --bootappend-live "boot=live components locales=en_US.UTF-8"

Best Practices

Start Simple: Begin with a minimal configuration and add features incrementally
Version Control: Keep your configuration in a version control system
Test Frequently: Build and test images frequently to catch issues early
Document Changes: Document all customizations for future reference
Use Auto Scripts: For reproducible builds, use auto scripts to apply configuration changes

Troubleshooting

Check build logs in binary.log
For failed builds, examine the state of the chroot directory
Use lb clean to clean up before rebuilding
For specific package issues, try installing them manually in the chroot environment

Notes

Explorer

live_build_documentation