Create an Apple Mac .disk_label with grub-render-label

You will generate a binary .disk_label file for an Apple Mac from a short label or a text file, then check that the output was created without changing the source. Allow about ten minutes. You need a Linux shell, the grub-render-label command from grub-common, and a GRUB PF2 font. The examples use GRUB 2.12-1ubuntu7.3, installed here on Ubuntu.

This command is for producing an Apple-specific GRUB label image. It is not a general image converter, and it does not install GRUB, alter boot entries, write a disk, or change firmware settings. The examples write under /tmp or your working directory, so they do not require sudo.

1. Check the installed command and font

First confirm which program will run and record its version:

$ command -v grub-render-label
/usr/bin/grub-render-label
$ grub-render-label --version
grub-render-label (GRUB) 2.12-1ubuntu7.3

The installed manual documents -f or --font as accepting a PF2 font file. Common GRUB installations provide unicode.pf2 under /usr/share/grub. Locate one rather than guessing a path:

$ find /usr/share/grub -type f -name '*.pf2' -print
/usr/share/grub/unicode.pf2
/usr/share/grub/euro.pf2
/usr/share/grub/ascii.pf2

Use a font that contains the characters in your label. If no PF2 file is found, stop here and install the GRUB package through your normal distribution process. Do not copy a font from an arbitrary website into a boot directory.

2. Render a label from a string

Supply the label with -t and the destination with -o. This example keeps the generated file in a temporary directory while you check it:

$ workdir=$(mktemp -d /tmp/grub-label-XXXXXX)
$ grub-render-label \
    --font=/usr/share/grub/unicode.pf2 \
    --text='Example Mac' \
    --output="$workdir/example.disk_label"
$ printf 'status=%s\n' "$?"
status=0

There is no normal text image preview in the terminal. A successful command creates binary data. Check its type and size:

$ file "$workdir/example.disk_label"
/tmp/grub-label-XXXXXX/example.disk_label: data
$ wc -c < "$workdir/example.disk_label"
1671

The exact byte count depends on the text, font and rendering options. The useful checks are a zero exit status and a non-empty output file. The file utility may describe the result simply as data, because a .disk_label is not necessarily recognised by its magic number.

3. Read the label from a file

Use -i or --input when the label is maintained in a file or is supplied by another step in a build. Keep the input as plain text:

$ printf '%s\n' 'Recovery Mac' > "$workdir/label.txt"
$ grub-render-label \
    --font=/usr/share/grub/unicode.pf2 \
    --input="$workdir/label.txt" \
    --output="$workdir/recovery.disk_label"
$ test -s "$workdir/recovery.disk_label" && echo 'label created'
label created

The input file is read; it is not replaced. Keep it under version control or in your build inputs if the label must be reproducible. A trailing newline can be part of the input, so write the file deliberately and check the rendered result on the target Mac.

4. Keep binary output away from the terminal

The manual says that the default output is standard output. That is useful for a pipeline, but it is unsafe to run an unredirected render in an interactive terminal because the result is binary rather than readable text:

$ grub-render-label \
    --font=/usr/share/grub/unicode.pf2 \
    --text='Example Mac' \
    > "$workdir/piped.disk_label"
$ test -s "$workdir/piped.disk_label" && echo 'standard output captured'
standard output captured

Use --output when the destination is a named file. Use shell redirection when the command is one stage in a pipeline. Do not interpret a successful exit status as proof that a bootloader will accept the label. It only says that this render completed.

5. Choose colours or verbose diagnostics carefully

The command provides separate options for the background and text colours. The installed manpage exposes these options but does not define a colour vocabulary, so do not assume that a value accepted by another GRUB tool is valid here. Test any chosen values in a temporary output file before putting them in an image-building script.

Add --verbose when diagnosing a failed render. Keep the output file separate while testing:

$ grub-render-label --verbose \
    --font=/usr/share/grub/unicode.pf2 \
    --text='Example Mac' \
    --output="$workdir/verbose.disk_label"
$ printf 'status=%s, bytes=%s\n' "$?" "$(wc -c < "$workdir/verbose.disk_label")"
status=0, bytes=1671

The byte count above is an example from this installed version, not a required constant. A different label, font or package build can produce a different size.

6. Avoid overwriting a useful label

$ new_label="$workdir/example.disk_label.new"
$ grub-render-label \
    --font=/usr/share/grub/unicode.pf2 \
    --text='Example Mac' \
    --output="$new_label"
$ test -s "$new_label"
$ mv -- "$new_label" "$workdir/example.disk_label"
$ test -s "$workdir/example.disk_label" && echo 'replacement installed'
replacement installed

The mv changes the destination within the temporary directory. If rendering fails, the old file remains because the new path is separate. If you replace a label in a boot image or mounted system, follow that image's backup and recovery procedure first. This command itself has no undo operation.

7. Diagnose the common failures

Missing arguments usually means that the command did not receive enough information to render. Check that you supplied a text or input file, an output destination or redirection, and a usable font:

$ test -r /usr/share/grub/unicode.pf2 && echo 'font readable'
font readable
$ test -r "$workdir/label.txt" && echo 'input readable'
input readable
$ grub-render-label --help

If the input path is wrong, use ls -l and test -r to check it without changing anything. If the font path is wrong, rerun find /usr/share/grub -type f -name '*.pf2'. If output is empty, inspect the command's exit status and stderr before reusing the destination. Do not add sudo as a generic repair: it cannot fix a missing argument, an invalid font or a bad path.

For a final check, compare the output size and, where possible, inspect the label through the Apple Mac boot workflow that will consume it. Keep the original input and any previous boot image until that check succeeds.