Metier Documentation

SliTaz live ISO builder

Metier builds bootable SliTaz live ISO images from a flavor: a list of packages plus a few files of your own. It is the KISS successor of Tazlito. The live system runs from RAM: the whole root filesystem is a rootfs.gz initramfs, there is no squashfs layer and no media probing at boot.

x86_64: one hybrid image that boots on BIOS and UEFI through GRUB2 (one menu for both), from a CD or from a USB key it was copied to.
i486: a BIOS image booted by isolinux, as Tazlito made it, for old hardware.

Metier is a POSIX shell script with a few library files. It reads the .tazpkg packages itself (cpio and lzma), so it needs neither tazpkg nor spk, and it runs on SliTaz as well as on any GNU/Linux host carrying the tools below.

Install and host tools
Quick start
Commands
Build an ISO
Check a flavor
Test in QEMU
Write a USB key
Workspace
metier.conf
Flavors
Packages and dependencies
Local packages and mirror
The build pipeline
Boot loaders
Build chroots and cron
Troubleshooting
Coming from Tazlito
About

Install and host tools

On SliTaz, install the package. It pulls the ISO tools in and puts the program in /usr/bin, its library in /usr/lib/metier and this manual in /usr/share/doc/metier:

# spk-add metier

From the sources, make install does the same (PREFIX and DESTDIR are honoured). Metier also runs in place, from its source directory or through a symlink: it finds its lib/ next to the script.

For	Tools
every build	cpio, gzip, xz, awk, sed, find, tar (busybox provides all but xz)
i486 ISO	genisoimage (or xorriso); isohybrid, optional, makes it bootable from a USB key
x86_64 ISO	xorriso, mtools (mformat, mcopy, mmd)
mirror packages	curl
metier emu	qemu-system-x86_64 or qemu-system-i386, OVMF for UEFI (the SliTaz qemu package ships it)

metier check tells what is there and what is missing. Build and flash need root: run by a regular user, metier restarts itself through sudo. The rootfs must hold real root ownership and setuid bits, and flash writes a raw device.

Quick start

$ metier flavors                    # what can be built
$ metier check base-x86_64          # the packages it will install
$ metier build base-x86_64          # -> $BASE/iso/slitaz-base-x86_64-cooking.iso
$ metier emu base-x86_64            # boot it in a QEMU window

Commands

Every command prints its own help with --help.

metier build <flavor>          Build a bootable ISO
metier check [flavor]          Host tools; with a flavor, its install set
metier emu <iso|flavor>        Boot an ISO in QEMU
metier flash <iso> <device>    Write an ISO to a USB key
metier flavors                 List the flavors
metier version                 Print the version
metier help                    Commands summary

Build an ISO

# metier build <flavor> [options]

The ISO lands in $BASE/iso/slitaz-<flavor>-<arch>-<channel>.iso with its .md5 beside it (Tazinst checks an ISO against it). When the flavor name already ends with the arch, it is not repeated: base-x86_64 gives slitaz-base-x86_64-cooking.iso. The build works in $BASE/<arch>/distro/<flavor>/, wiped at each run.

--arch i486\|x86_64	Target arch. Optional when the flavor receipt declares a single `ARCH=`; required for a multi-arch flavor, and checked against its list.
--firmware bios\|uefi\|both	Boot target. Default: bios for i486, both for x86_64. i486 is BIOS only.
--channel cooking\|stable	Package channel, part of the ISO name and of the mirror path. Default: cooking.
--compression gzip\|lzma\|xz\|none	Override the receipt `COMPRESSION` (default lzma).
--output DIR	ISO directory, instead of `$BASE/iso`.
--base DIR	Workspace, see Workspace.
--mirror URL	Mirror root, see mirror.
--serial	Send the boot menu and the console to the serial port too, for headless tests.
--emu	Boot the finished ISO in QEMU (as the invoking user); with --serial, on the serial console.

# metier build core-x86_64
# metier build base --arch i486 --serial --emu
# metier build firefox-x86_64 --base /home/tux/slitaz --output /tmp

Check a flavor

Without argument, check reports the workspace and the host tools. With a flavor, it resolves the install set exactly as a build would, without building and without root: the packages it adds from the DEPENDS of the list, the ones skipped through packages.exclude, and any package found nowhere. Run it after editing a flavor or when the wok changed.

$ metier check vps-marmite
  vps-marmite (x86_64): 76 listed package(s)
  added 12 package(s) from DEPENDS:
      grep                           (dep of grub2)
      pcre                           (dep of grep)
      ...
  88 package(s) to install

Test in QEMU

$ metier emu <iso|flavor> [options]

The argument is an ISO path, or a flavor name: metier then boots the ISO that build made for it. The QEMU binary follows the arch (from --arch, the ISO name, or the flavor receipt). x86_64 boots on UEFI by default (OVMF), i486 on BIOS. KVM is used when /dev/kvm is writable.

(none)	Graphical window, resizable, scaled to its size.
--serial	No window, serial console in this terminal (Ctrl-A X quits). Best with an ISO built with --serial.
--headless	No display, serial on stdout, for scripts.
--bios \| --uefi	Force the firmware: --bios tests the GRUB BIOS path of an x86_64 ISO.
--memory M	RAM in MiB (default 256; a desktop flavor wants 1024 or more).
--timeout S	Stop QEMU after S seconds.
--arch, --channel, --base	To resolve a flavor name, as for build.

The source tree carries a smoke test: it builds a flavor with --serial, boots it headless and waits for the login prompt.

$ tests/smoke.sh base-x86_64
$ tests/smoke.sh base --arch i486 --base /home/tux/slitaz

Write a USB key

# metier flash --list
# metier flash slitaz-core-x86_64-cooking.iso /dev/sdb

flash copies the hybrid ISO byte for byte to a whole USB disk: every partition on it is lost. The key then boots like the CD, live and read-only. For a persistent system, boot the key and install with Tazinst. Safety rules:

the target is a whole disk (/dev/sdb, not /dev/sdb1), removable unless --force, with nothing mounted;
the ISO must fit, and a card reader without a card is refused;
it asks to type YES; in a script, pass --yes; --plan shows what would happen and writes nothing.

Workspace

Metier works in a SliTaz workspace, $BASE, with the same layout as the cook tools:

$BASE/repos/flavors/<flavor>/       Flavor sources (hg clone of flavors)
$BASE/<arch>/packages/*.tazpkg      Cooked packages, searched first
$BASE/<arch>/cache/<channel>/       Packages fetched from the mirror
$BASE/<arch>/distro/<flavor>/       Build tree (rootfs/, rootcd/)
$BASE/iso/                          ISO images and their .md5

A tree without the <arch> level ($BASE/packages, $BASE/distro...) is used as is: that is the layout of a single-arch build chroot. $BASE is the first of:

--base DIR
the $SLITAZ environment variable (kept through sudo)
BASE= in metier.conf
/home/slitaz when it is writable: SliTaz build chroots and native cook
~/.slitaz of the invoking user

metier.conf

Metier reads /etc/slitaz/metier.conf, then ~/.slitaz/metier.conf of the invoking user, which wins (under sudo, the user who ran sudo). The files are parsed, never sourced, since build runs as root. Two keys:

BASE="/home/tux/slitaz"              Workspace outside /home/slitaz
MIRROR="http://mirror.slitaz.org"    Mirror root

A developer who keeps the workspace in their home only needs this one line in ~/.slitaz/metier.conf; build chroots need no file at all.

Flavors

A flavor is a directory of $BASE/repos/flavors. Metier reads Tazlito flavors as they are:

receipt	Required. `FLAVOR`, `SHORT_DESC`, `VERSION`, `ARCH` (one arch or a list, e.g. `"x86_64 i486"`), `COMPRESSION` (default lzma). Other Tazlito fields are ignored.
packages.list	Required. The packages the ISO is for, one per line, `#` comments allowed.
packages.exclude	Optional. Dependencies never to pull in, one per line.
rootfs/	Copied over the installed packages, before the post_install scripts (which can still change these files).
rootcd/	Copied onto the ISO itself, outside the live system.
addfiles/	Copied over the rootfs last, after post_install: the final word on a file.
distro.sh	Run on the finished rootfs, before packing. `$1` is the build directory holding `rootfs/` and `rootcd/` (Tazlito convention), `$ROOTFS` is exported.

Overlays are copied without ownership: files land root-owned whoever owns the hg clone. Metier also writes /etc/slitaz/flavor (flavor name and build date, read by Tazhelper and kept by Tazinst).

Packages and dependencies

Metier installs the packages of packages.list and their DEPENDS, recursively, like Tazpkg. The dependencies are read in the receipt of the very .tazpkg that will be installed, and PROVIDE is honoured: a dependency that a listed package provides is not installed again. The build log names every added package and the package that wanted it.

Some receipts depend on tools busybox already provides (grep, mount, the util-linux bits...). On a busybox system they are dead weight: list them in packages.exclude. An excluded name is never pulled in as a dependency, and its own dependencies are not walked; written in packages.list, it is still installed.

# packages.exclude - busybox covers them
grep
util-linux-mount

A library missing from a receipt's DEPENDS is a wok bug: fix the receipt, do not paper over it in the flavor. glibc-base (x86_64) stays listed in every flavor anyway: the system boots on it.

Local packages and mirror

Each package is looked up in $BASE/<arch>/packages (your cooks), then in the cache, then on the mirror, which fills the cache. The highest version wins inside a directory. All packages are resolved before anything is extracted: when some are found nowhere, the build stops at once with the full list, each with the package that wanted it.

The mirror is optional: a build from local packages only never touches the network. Metier probes mirror.slitaz.org then mirror3.slitaz.org for <arch>/<channel>/packages/, or the root given by --mirror, $METIER_MIRROR or MIRROR= in metier.conf. The package index is refreshed once a day.

The build pipeline

Load the flavor and settle the arch.
Resolve the install set (list, DEPENDS, exclusions); stop on missing packages.
Extract each package into rootfs/ and record it in the package database, so the live system knows what is installed.
Copy rootfs/, move /boot onto the CD tree, copy rootcd/.
Lay the links extraction alone misses: /lib64 on x86_64, every busybox applet, busybox setuid.
Run each package's post_install, as spk-add does, then update the system databases (MIME, icons, GSettings schemas, pixbuf loaders).
Copy addfiles/, run distro.sh, write /etc/slitaz/flavor.
Name the kernel bzImage, pack rootfs.gz (cpio, lzma by default).
Write the boot loader setup (Boot loaders).
Assemble the ISO and its .md5.

Pre_install scripts are not run: they prepare a running system for new files, and some delete busybox links that the package replaces, which on a rootfs built from scratch removed the real tools.

Boot loaders

i486: the syslinux package brings isolinux and its menu; metier sets the build date in isolinux.cfg, builds the ISO with genisoimage and makes it hybrid with isohybrid when present. The splash image comes from slitaz-configs-base, shared by every ISO.

x86_64: one /boot/grub/grub.cfg serves both firmwares, with the SliTaz theme and a keyboard layout submenu. UEFI: the loader of grub2-efi-x64 sits alone in a small FAT image appended to the ISO as a real GPT partition, so the image boots from a CD and from a key it was copied to. BIOS: a GRUB El Torito image and a hybrid MBR, made from the grub2 package. The kernel and rootfs live once, on the ISO filesystem. A loader that cannot draw falls back to a text menu.

--serial adds the serial port to the menu and console=ttyS0,115200 last on the kernel command line, so the login prompt lands on the serial console.

Build chroots and cron

In a SliTaz build chroot, /home/slitaz holds the packages and the flavors, so metier needs no option and no configuration, and runs as root without sudo. A build host can make cooking ISOs on demand or from cron:

# metier build core-x86_64 && metier build base --arch i486

Two builds of the same flavor must not run at once: they share $BASE/<arch>/distro/<flavor>.

Troubleshooting

missing packages	Cook them, put them in `$BASE/<arch>/packages`, or fix the list. A "(dep of X)" entry comes from the receipt of X.
cache not writable	`metier check` runs as your user; the build cache belongs to root. The mirror is then skipped for the check.
post_install ... non-zero	A warning, the build goes on: some scripts expect tools of a running system.
boot stops at `grub>`	The ISO was built before the ESP stub configuration; rebuild it.
kernel panic on /init	Look at the x86_64 boot invariants in `BOOT64.md` (loader link, busybox applets, glibc-base).
i486 ISO not bootable from a key	Install isohybrid (syslinux-extra) and rebuild.

Coming from Tazlito

Same flavors: receipt, packages.list, rootfs/, rootcd/, distro.sh are read as they are. Not supported: multi-rootfs flavors (ROOTFS_SELECTION) and custom_rules; metier refuses them with a clear message.
No chroot needed and no get-flavor step: metier reads the flavor in place and the packages from the workspace.
One command per task: build, check, emu, flash.
x86_64 is new: hybrid BIOS and UEFI with GRUB2.

About

Metier is free software under the GNU GPL version 2 or later. Sources: hg.slitaz.org/metier. The x86_64 boot notes are in BOOT64.md, next to this manual.