zbm-regen-pacman-hook/README.md

# zbm-regen-pacman-hook

Arch Linux pacman hook to automatically recreate ZFSBootMenu images after upgrades. This hook is intended to work with [quico.space/quico-os-setup/arch-zbm](https://quico.space/quico-os-setup/arch-zbm), a root-on-ZFS installation script that uses ZFSBootMenu as its boot loader.

# Setup

> Not explicitly listed here as a step but still relevant: This `pacman` hook only makes sense if you're using ZFSBootMenu images and have the homonymous `zfsbootmenu` package installed.

Get started like so:

1. Clone repo into arbitrary path `<repo>`
1. Symlink to hook file, for example
    ```
    sudo ln -s <repo>/pacman-zbm-image-regen.hook /usr/share/libalpm/hooks/pacman-zbm-image-regen.hook
    ```

# What's it do?

In `pacman` whenever the `zfsbootmenu` package or your kernel are getting updated this hook will regenerate the ZFSBootMenu image via `generate-zbm` which will in turn store a new file in its image path as configured in `/etc/zfsbootmenu/config.yaml`.

This happens as a `PostTransaction` in `pacman`.

# Assumptions

Per [headline](#zbm-regen-pacman-hook) this hook is intended to work with [quico.space/quico-os-setup/arch-zbm](https://quico.space/quico-os-setup/arch-zbm). Before using this hook for any purpose other than an `arch-zbm` Arch Linux installation please closely review what it does and adapt to your use case as needed.

This hook is working on `arch-zbm` machines that use either UEFI or legacy BIOS.

The `zfsbootmenu` package and `generate-zbm` binary in particular don't care where newly generated images need to be stored. After an `arch-zbm` installation you're left with an `/etc/zfsbootmenu/config.yaml` file that instructs `generate-zbm` to store new image files in a sensible location.

## UEFI vs. legacy BIOS

On a UEFI system new ZFSBootMenu images are named `vmlinuz.EFI` and `vmlinuz-backup.EFI`. EFI boot loader entries can and do remain static to always looks for these two exact EFI image file names.

On a legacy BIOS machine ZFSBootMenu creates split images: One `vmlinuz-bootmenu(-backup)` kernel and one `initramfs-bootmenu(-backup).img` initrd. Here, too, your `/boot/syslinux/syslinux.cfg` config file can and does remain static to always look for these exact file names.

## Triggers

The hook triggers on several `pacman` events:
1. An upgrade of `zfsbootmenu` package
1. Upgrades or installation on files that match:
    ```
    Target = usr/lib/modules/*/vmlinuz
    Target = usr/lib/modules/*/extramodules/*
    ```
1. All `pacman` operations on files that match:
    ```
    Target = boot/*-ucode.img
    Target = usr/lib/booster/*
    Target = usr/lib/initcpio/*
    Target = usr/lib/initcpio/*/*
    Target = usr/lib/dracut/*
    Target = usr/lib/dracut/*/*
    Target = usr/lib/dracut/*/*/*
    Target = usr/lib/kernel/*
    Target = usr/lib/kernel/*/*
    Target = usr/src/*/dkms.conf
    ```

# Development

## Conventional commits

This project uses [Conventional Commits](https://www.conventionalcommits.org/) for its commit messages.

### Commit types

Commit _types_ besides `fix` and `feat` are:

- `build`: Project structure, directory layout, build instructions for roll-out
- `refactor`: Keeping functionality while streamlining or otherwise improving function flow
- `test`: Working on test coverage
- `docs`: Documentation for project or components

### Commit scopes

The following _scopes_ are known for this project. A Conventional Commits commit message may optionally use one of the following scopes or none:

- `script`: Work related to commands triggered by `pacman`
- `hook`: Configuring the hook(s)
- `meta`: Affects the project's repo layout, readme content, file names etc.