osi-tools/Documentation/disk-formats.md

# Adding "disk" formats to osi-mk

<!--
Copyright (C) 2024  Umorpha Systems
SPDX-License-Identifier: AGPL-3.0-or-later
-->

Create a file `lib/mk/format-*.sh`, and `source` that file from
`bin/osi-mk`.

In that file:

 - required: set `formats+=('YOURFORMAT')`

 - required: set `format_options['YOURFORMAT']=` to a
   whitespace-separated list of the `--fmtconf=XXX=` flags that
   your format takes.

 - optional: define `format_checkconf:YOURFORMAT() { … }` to insert
   your own validation for `--conf=` flags.

 - optional: define `format_genfstab:YOURFORMAT() { … }` to override
   the usual `genfstab` command.

 - required: set `format_is_block['YOURFORMAT']=` to `true` or
   `false`, indicating whether osi-mk should pre-allocate a file for
   you (pointed at by `$arg_file`).

   * if `format_is_block['YOURFORMAT']='true'`, then

     + required: define `format_mkfs:YOURFORMAT() { … }` which runs
       the appropriate `mkfs` on `$arg_file`.

     + required: define `format_editfs:YOURFORMAT() { … }` which
       applies any `--fmtconf=XXX=` flags.  If `size` is set, then you
       don't need to resize the file itself, osi-mk does that
       before/after calling `format_editfs:YOURFORMAT`, but you do
       need to run `resize2fs` or `btrfs filesystem resize` or
       whatever.

   * if `format_is_block['YOURFORMAT']='false'`, then

     + required: set `format_wants_tmpfs['YOURFORMAT']` to `true` or
       `false`, indicating whether `$mount_dev` should be set to a
       tmpfs (instead of `$arg_file`) and whether `$mount_opt` should
       be set to `bind`.

     + required: define `format_before:YOURFORMAT() { … }` that does
       any nescessary setup on `$mount_dev`/`$mount_opt` before
       mounting it to do the install.

     + required: define `format_after:YOURFORMAT() { … }` that does
       any nescessary transforms to get from `$mount_dev` to
       `$arg_file`.

	 - required: set `format_after_clamps_mtime['YOURFORMAT']=` to
       `true` or `false` indicating whether  your
       `format_after:YOURFORMAT` function clamps mtimes to
       `SOURCE_DATE_EPOCH` (`true`), or whether osi-mk should adjust
       all the mtimes before calling `format_after:YOURFORMAT`