Add missing documentation about cmdlines for various verbs

The error message is changed to be more direct. If somebody doesn't know that
the parameters are passed to the command, "additional" would be unclear.

In the man page the verbs are listed by the order one would normally use them,
i.e. summary, then build, then qmeu/shell/boot/…, then clean, and the less
frequently used verbs last.

Descriptions are added to the commands which take parameters that they do that
and how those parameters are interpreted. In paricular, for 'boot' we accept
kernel commandline options, and for 'qemu' we only take qemu options. (Which is
understandable, given that we don't do a direct kernel boot, but not obvious.)

Fixes #1210.

diff --git a/man/mkosi.1 b/man/mkosi.1
index daed32d36f7af3f06e839cb1f9df4ccb4eb8a09b..7f472d3c158641fb869f86083b36b57e8b693d19 100644 (file)
--- a/man/mkosi.1
+++ b/man/mkosi.1
@@ -7,19 +7,19 @@
 mkosi \[em] Build Bespoke OS Images
 .SH SYNOPSIS
 .PP
-\f[C]mkosi [options\&...] build\f[R]
-.PP
-\f[C]mkosi [options\&...] clean\f[R]
-.PP
 \f[C]mkosi [options\&...] summary\f[R]
 .PP
+\f[C]mkosi [options\&...] build [script parameters\&...]\f[R]
+.PP
 \f[C]mkosi [options\&...] shell [command line\&...]\f[R]
 .PP
 \f[C]mkosi [options\&...] boot [nspawn settings\&...]\f[R]
 .PP
-\f[C]mkosi [options\&...] qemu\f[R]
+\f[C]mkosi [options\&...] qemu [qemu parameters\&...]\f[R]
 .PP
-\f[C]mkosi [options\&...] ssh\f[R]
+\f[C]mkosi [options\&...] ssh [command line\&...]\f[R]
+.PP
+\f[C]mkosi [options\&...] clean\f[R]
 .PP
 \f[C]mkosi [options\&...] serve\f[R]
 .PP
@@ -38,20 +38,6 @@ generate disk images with a number of bells and whistles.
 .PP
 The following command line verbs are known:
 .TP
-\f[B]\f[CB]build\f[B]\f[R]
-This builds the image, based on the settings passed in on the command
-line or read from a \f[C]mkosi.conf\f[R] file.
-This verb is the default if no verb is explicitly specified.
-This command must be executed as \f[C]root\f[R].
-Any arguments passed after \f[C]build\f[R] are passed as arguments to
-the build script (if there is one).
-.TP
-\f[B]\f[CB]clean\f[B]\f[R]
-Remove build artifacts generated on a previous build.
-If combined with \f[C]-f\f[R], also removes incremental build cache
-images.
-If \f[C]-f\f[R] is specified twice, also removes any package cache.
-.TP
 \f[B]\f[CB]summary\f[B]\f[R]
 Outputs a human-readable summary of all options used for building an
 image.
@@ -59,36 +45,56 @@ This will parse the command line and \f[C]mkosi.conf\f[R] file as it
 would do on \f[C]build\f[R], but only output what it is configured for
 and not actually build anything.\[ga]
 .TP
+\f[B]\f[CB]build\f[B]\f[R]
+This builds the image based on the settings passed in on the command
+line or read from a \f[C]mkosi.conf\f[R] file.
+This command is the default if no verb is explicitly specified.
+This command must be executed as \f[C]root\f[R].
+Any arguments passed after the \f[C]build\f[R] verb are passed as
+arguments to the build script (if there is one).
+.TP
 \f[B]\f[CB]shell\f[B]\f[R]
 This builds the image if it is not built yet, and then invokes
 \f[C]systemd-nspawn\f[R] to acquire an interactive shell prompt in it.
-If this verb is used an optional command line may be specified which is
-then invoked in place of the shell in the container.
-Combine this with \f[C]-f\f[R] in order to rebuild the image
-unconditionally before acquiring the shell, see below.
+An optional command line may be specified after the \f[C]shell\f[R]
+verb, to be invoked in place of the shell in the container.
+Use \f[C]-f\f[R] in order to rebuild the image unconditionally before
+acquiring the shell, see below.
 This command must be executed as \f[C]root\f[R].
 .TP
 \f[B]\f[CB]boot\f[B]\f[R]
-Similar to \f[C]shell\f[R] but boots the image up using
+Similar to \f[C]shell\f[R], but boots the image using
 \f[C]systemd-nspawn\f[R].
-If this verb is used an optional command line may be specified which is
-passed as \[lq]kernel command line\[rq] to the init system in the image.
+An optional command line may be specified after the \f[C]boot\f[R] verb,
+which is then passed as the \[lq]kernel command line\[rq] to the init
+system in the image.
 .TP
 \f[B]\f[CB]qemu\f[B]\f[R]
-Similar to \f[C]boot\f[R] but uses \f[C]qemu\f[R] to boot up the image,
-i.e.\ instead of container virtualization VM virtualization is used.
-This verb is only supported on images that contain a boot loader,
+Similar to \f[C]boot\f[R], but uses \f[C]qemu\f[R] to boot up the image,
+i.e.\ instead of container virtualization virtual machine virtualization
+is used.
+This verb is only supported for images that contain a boot loader,
 i.e.\ those built with \f[C]Bootable=yes\f[R] (see below).
 This command must be executed as \f[C]root\f[R] unless the image already
 exists and \f[C]-f\f[R] is not specified.
+Any options specified after the \f[C]qemu\f[R] verb are appended to the
+\f[C]qemu\f[R] invocation.
 .TP
 \f[B]\f[CB]ssh\f[B]\f[R]
 When the image is built with the \f[C]Ssh=yes\f[R] option, this command
-connects to a booted (\f[C]boot\f[R], \f[C]qemu\f[R] verbs) container/VM
-via SSH.
+connects to a booted (\f[C]boot\f[R], \f[C]qemu\f[R] verbs) container or
+VM via SSH.
 Make sure to run \f[C]mkosi ssh\f[R] with the same config as
 \f[C]mkosi build\f[R] was run with so that it has the necessary
 information available to connect to the running container/VM via SSH.
+Any arguments passed after the \f[C]ssh\f[R] verb are passed as
+arguments to the \f[C]ssh\f[R] invocation.
+.TP
+\f[B]\f[CB]clean\f[B]\f[R]
+Remove build artifacts generated on a previous build.
+If combined with \f[C]-f\f[R], also removes incremental build cache
+images.
+If \f[C]-f\f[R] is specified twice, also removes any package cache.
 .TP
 \f[B]\f[CB]serve\f[B]\f[R]
 This builds the image if it is not built yet, and then serves the output

diff --git a/mkosi.md b/mkosi.md
index 8353e95bb5e137ee700fce7b06cbe6a2f0591f33..4377c0dec266128b2be1c8ff396fae1f33fae286 100644 (file)
--- a/mkosi.md
+++ b/mkosi.md
@@ -8,19 +8,19 @@ mkosi — Build Bespoke OS Images
 
 # SYNOPSIS
 
-`mkosi [options…] build`
-
-`mkosi [options…] clean`
-
 `mkosi [options…] summary`
 
+`mkosi [options…] build [script parameters…]`
+
 `mkosi [options…] shell [command line…]`
 
 `mkosi [options…] boot [nspawn settings…]`
 
-`mkosi [options…] qemu`
+`mkosi [options…] qemu [qemu parameters…]`
+
+`mkosi [options…] ssh [command line…]`
 
-`mkosi [options…] ssh`
+`mkosi [options…] clean`
 
 `mkosi [options…] serve`
 
@@ -41,20 +41,6 @@ whistles.
 
 The following command line verbs are known:
 
-`build`
-
-: This builds the image, based on the settings passed in on the
-  command line or read from a `mkosi.conf` file. This
-  verb is the default if no verb is explicitly specified. This command
-  must be executed as `root`. Any arguments passed after `build` are
-  passed as arguments to the build script (if there is one).
-
-`clean`
-
-: Remove build artifacts generated on a previous build. If combined
-  with `-f`, also removes incremental build cache images. If `-f` is
-  specified twice, also removes any package cache.
-
 `summary`
 
 : Outputs a human-readable summary of all options used for building an
@@ -62,37 +48,52 @@ The following command line verbs are known:
   would do on `build`, but only output what it is configured for and not
   actually build anything.`
 
+`build`
+
+: This builds the image based on the settings passed in on the command line or
+  read from a `mkosi.conf` file. This command is the default if no verb is
+  explicitly specified. This command must be executed as `root`. Any arguments
+  passed after the `build` verb are passed as arguments to the build script (if
+  there is one).
+
 `shell`
 
 : This builds the image if it is not built yet, and then invokes
-  `systemd-nspawn` to acquire an interactive shell prompt in it. If
-  this verb is used an optional command line may be specified which is
-  then invoked in place of the shell in the container. Combine this
-  with `-f` in order to rebuild the image unconditionally before
-  acquiring the shell, see below. This command must be executed as
-  `root`.
+  `systemd-nspawn` to acquire an interactive shell prompt in it. An optional
+  command line may be specified after the `shell` verb, to be invoked in place
+  of the shell in the container. Use `-f` in order to rebuild the image
+  unconditionally before acquiring the shell, see below. This command must be
+  executed as `root`.
 
 `boot`
 
-: Similar to `shell` but boots the image up using `systemd-nspawn`. If
-  this verb is used an optional command line may be specified which is
-  passed as "kernel command line" to the init system in the image.
+: Similar to `shell`, but boots the image using `systemd-nspawn`. An optional
+  command line may be specified after the `boot` verb, which is then passed as
+  the "kernel command line" to the init system in the image.
 
 `qemu`
 
-: Similar to `boot` but uses `qemu` to boot up the image, i.e. instead
-  of container virtualization VM virtualization is used. This verb is
-  only supported on images that contain a boot loader, i.e. those
-  built with `Bootable=yes` (see below). This command must be executed
-  as `root` unless the image already exists and `-f` is not specified.
+: Similar to `boot`, but uses `qemu` to boot up the image, i.e. instead of
+  container virtualization virtual machine virtualization is used. This verb is
+  only supported for images that contain a boot loader, i.e. those built with
+  `Bootable=yes` (see below). This command must be executed as `root` unless
+  the image already exists and `-f` is not specified. Any options specified
+  after the `qemu` verb are appended to the `qemu` invocation.
 
 `ssh`
 
 : When the image is built with the `Ssh=yes` option, this command connects
-  to a booted (`boot`, `qemu` verbs) container/VM via SSH. Make sure to
+  to a booted (`boot`, `qemu` verbs) container or VM via SSH. Make sure to
   run `mkosi ssh` with the same config as `mkosi build` was run with so
   that it has the necessary information available to connect to the running
-  container/VM via SSH.
+  container/VM via SSH. Any arguments passed after the `ssh` verb are passed as
+  arguments to the `ssh` invocation.
+
+`clean`
+
+: Remove build artifacts generated on a previous build. If combined
+  with `-f`, also removes incremental build cache images. If `-f` is
+  specified twice, also removes any package cache.
 
 `serve`
 

diff --git a/mkosi/__init__.py b/mkosi/__init__.py
index 7cc4d89c9d49fc05ce32ce7e4e20590d8e0e4d4f..0327fb67eb25c9a9e760e3f1e5700036ed0ff6f9 100644 (file)
--- a/mkosi/__init__.py
+++ b/mkosi/__init__.py
@@ -6462,7 +6462,7 @@ def load_args(args: argparse.Namespace) -> MkosiConfig:
     args.extra_search_paths = expand_paths(args.extra_search_paths)
 
     if args.cmdline and args.verb not in MKOSI_COMMANDS_CMDLINE:
-        die(f"Additional parameters only accepted for {list_to_string(verb.name for verb in MKOSI_COMMANDS_CMDLINE)} invocations.")
+        die(f"Parameters after verb are only accepted for {list_to_string(verb.name for verb in MKOSI_COMMANDS_CMDLINE)}.")
 
     if args.output_format is None:
         args.output_format = OutputFormat.gpt_ext4