zbm-syslinux-pacman-hook/README.md

# zbm-syslinux-pacman-hook

Arch Linux pacman hook to automatically recreate syslinux and MBR after updates. 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 Syslinux as your boot loader and have the homonymous `syslinux` package installed.

Get started like so:

1. Install dependencies `jq` and `rsync`
1. Clone repo into arbitrary path `<repo>`
1. Make `pacman-zbm-syslinux-regen.sh` executable
    ```
    chmod +x <repo>/pacman-zbm-syslinux-regen.sh
    ```
1. Symlink to files, for example
    ```
    sudo ln -s <repo>/pacman-zbm-syslinux-regen.sh /usr/local/bin/pacman-zbm-syslinux-regen
    sudo ln -s <repo>/pacman-zbm-syslinux-regen.hook /usr/share/libalpm/hooks/pacman-zbm-syslinux-regen.hook
    ```
    Note that while you may choose an arbitrary location for your shell script symlink `pacman-zbm-syslinux-regen.hook` file references `/usr/local/bin/pacman-zbm-syslinux-regen`. Change that accordingly if you need to.

# What's it do?

In `pacman` whenever the `syslinux` package is getting updated this hook will replace all `*.c32` COMBOOT module files in `/boot/syslinux`, will reinstall newest `extlinux` and write the newest `mbr.bin` Master Boot Record file onto the boot disk.

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

We identify the boot disk via:
```
findmnt --noheadings --target "${boot_dir}" --output 'SOURCE'
```

Where `"${boot_dir}"` is:
```
boot_dir='/boot/syslinux'
```

If this returns zero or more than one mounted drive we bail, print an error message and do not do any operations.

# Assumptions

Per [headline](#zbm-syslinux-pacman-hook) this hook is intended to work with [quico.space/quico-os-setup/arch-zbm](https://quico.space/quico-os-setup/arch-zbm); it's specifically intended for use on `arch-zbm` machines that use legacy BIOS. Before using this hook for any other purpose please closely review what it does and adapt to your use case as needed.

We do not care about `pacman` events other than a `syslinux` package update. Specifically if ZFSBootMenu gets an update `syslinux` and our Master Boot Record remain unaffected. Kernel update? Same, no change needed since no kernel or module change directly influence the simple and decoupled structure of `syslinux`.

# 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 the commands triggered by `pacman`
- `hook`: Configuring the hook(s)
- `meta`: Affects the project's repo layout, readme content, file names etc.