doc: document command candidates and the duplicate title rule

The migration guide covered a stanza at a time, which is the wrong
shape for the two idioms that repeated a whole stanza.  One of them,
several candidate binaries for one service, is now a command list.
The other, one service gated differently per platform, has no block
equivalent: those blocks share an identity because they share the
barrier condition downstream services wait for, so they cannot be
given separate titles.  For that one the guide says to split the
variants across files, or leave that file in the line-based format,
which Finit still reads.

The udevd example in services.md taught the merge-broken form, and
system/10-hotplug.conf.in pointed readers at it for their syslogd.

Also lists libConfuse among the build dependencies.  It has been
mandatory since the new .conf format landed, and build.md still said
two libraries.  And corrects the note on variable expansion: it is
${VAR} that libconfuse expands when the file is read, with
${VAR:-default} supported.  A plain $VAR reaches the service, which is
what makes `command = "syslogd -F $SYSLOGD_ARGS"` work with envfile.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
This commit is contained in:
Joachim Wiberg committed 2026-08-05 17:57:56 +02:00
1 parent cfae4a0e10
commit 4299ce8839
6 files changed
+147 -14

No files matched your search

+14 -11
View File
@@ -226,23 +226,26 @@ Finit supports conditional loading of blocks. The following example is
taken from the `system/10-hotplug.conf` file in the Finit distribution.
Here we only show a simplified subset.
Starting with the leading `-` on `command`.
Starting with the udev daemon, which goes by two names depending on
how it was built. Both are candidates for the same service:
service udevd {
pidfile = "udevd"
command = "-/lib/systemd/systemd-udevd"
}
service udevd {
pidfile = "udevd"
command = "-udevd"
command = { "/lib/systemd/systemd-udevd", "-udevd" }
}
When loading the .conf file Finit looks for
`/lib/systemd/systemd-udevd`, and if that is not found it logs a
warning. The leading `-` says a missing binary is expected here, so
the block is skipped quietly and the second one can be evaluated,
which also provides a service named `udevd`.
`/lib/systemd/systemd-udevd`, and if that is not there it moves on to
`udevd`. A candidate that is not installed is expected, so no warning
is logged for the ones that are skipped. The leading `-` on the last
one says it is also fine if none of them are found, in which case the
block is dropped quietly and no service named `udevd` exists.
> [!NOTE]
> This needs to be one block. The title is the service identity, so
> two blocks titled `udevd` in the same file are two declarations of
> one service, which Finit rejects. See [Duplicate
> titles](service-opts.md#duplicate-titles).
run udevadm:1 {
runlevel = "S"