From: Zbigniew Jędrzejewski-Szmek Date: Fri, 28 Oct 2022 16:27:38 +0000 (+0200) Subject: Add missing documentation about cmdlines for various verbs X-Git-Tag: v15~386^2~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f53c7d4edd15fc619448ba5c9d48d482ff8fb173;p=thirdparty%2Fmkosi.git 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 daed32d36..7f472d3c1 100644 --- 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 8353e95bb..4377c0dec 100644 --- 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 7cc4d89c9..0327fb67e 100644 --- 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