From a3b227d28a823d59e3281109f5369d0f63b40f62 Mon Sep 17 00:00:00 2001
From: Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>
Date: Tue, 6 Jun 2023 13:23:49 +0200
Subject: ukify: add 'build' verb

The old syntax with linux + initrds as positional arguments is still accepted,
but a warning is emitted. We should remove the support for this after the
next release or so.

Adding a single verb by itself is not very useful, but opens the door to adding
other verbs.
---
 man/ukify.xml | 38 +++++++++++++++++++++-----------------
 1 file changed, 21 insertions(+), 17 deletions(-)

(limited to 'man/ukify.xml')

diff --git a/man/ukify.xml b/man/ukify.xml
index 4531ac89b2..098dacfb99 100644
--- a/man/ukify.xml
+++ b/man/ukify.xml
@@ -23,9 +23,8 @@
   <refsynopsisdiv>
     <cmdsynopsis>
       <command>/usr/lib/systemd/ukify</command>
-      <arg choice="opt"><replaceable>LINUX</replaceable></arg>
-      <arg choice="opt" rep="repeat"><replaceable>INITRD</replaceable></arg>
       <arg choice="opt" rep="repeat">OPTIONS</arg>
+      <arg choice="plain">build</arg>
     </cmdsynopsis>
   </refsynopsisdiv>
 
@@ -35,13 +34,18 @@
     <para>Note: this command is experimental for now. While it is intended to become a regular component of
     systemd, it might still change in behaviour and interface.</para>
 
-    <para><command>ukify</command> is a tool that combines components (e.g.: a kernel and an initrd with
-    a UEFI boot stub) to create a
+    <para><command>ukify</command> is a tool that combines components (usually a kernel, an initrd, and a
+    UEFI boot stub) to create a
     <ulink url="https://uapi-group.org/specifications/specs/unified_kernel_image/">Unified Kernel Image (UKI)</ulink>
     — a PE binary that can be executed by the firmware to start the embedded linux kernel.
     See <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>
     for details about the stub.</para>
 
+    <para>The two primary options that should be specified for the <command>build</command> verb are
+    <varname>Linux=</varname>/<option>--linux=</option>, and
+    <varname>Initrd=</varname>/<option>--initrd=</option>. <varname>Initrd=</varname> accepts multiple
+    whitespace-separated paths and <option>--initrd=</option> can be specified multiple times.</para>
+
     <para>Additional sections will be inserted into the UKI, either automatically or only if a specific
     option is provided. See the discussions of
     <varname>Cmdline=</varname>/<option>--cmdline=</option>,
@@ -173,14 +177,14 @@
       <variablelist>
         <varlistentry>
           <term><varname>Linux=<replaceable>LINUX</replaceable></varname></term>
-          <term>positional argument <replaceable>LINUX</replaceable></term>
+          <term><option>--linux=<replaceable>LINUX</replaceable></option></term>
 
           <listitem><para>A path to the kernel binary.</para></listitem>
         </varlistentry>
 
         <varlistentry>
           <term><varname>Initrd=<replaceable>INITRD</replaceable>...</varname></term>
-          <term>positional argument <replaceable>INITRD</replaceable></term>
+          <term><option>--initrd=<replaceable>LINUX</replaceable></option></term>
 
           <listitem><para>Zero or more initrd paths. In the configuration file, items are separated by
           whitespace. The initrds are combined in the order of specification, with the initrds specified in
@@ -399,9 +403,9 @@
     <example>
       <title>Minimal invocation</title>
 
-      <programlisting>$ ukify \
-      /lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
-      /some/path/initramfs-6.0.9-300.fc37.x86_64.img \
+      <programlisting>$ ukify build \
+      --linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
+      --initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img \
       --cmdline='quiet rw'
       </programlisting>
 
@@ -411,10 +415,10 @@
     <example>
       <title>All the bells and whistles</title>
 
-      <programlisting># /usr/lib/systemd/ukify \
-      /lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
-      early_cpio \
-      /some/path/initramfs-6.0.9-300.fc37.x86_64.img \
+      <programlisting># /usr/lib/systemd/ukify build \
+      --linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
+      --initrd=early_cpio \
+      --initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img \
       --pcr-private-key=pcr-private-initrd-key.pem \
       --pcr-public-key=pcr-public-initrd-key.pem \
       --phases='enter-initrd' \
@@ -468,9 +472,9 @@ Phases=enter-initrd:leave-initrd
        enter-initrd:leave-initrd:sysinit
        enter-initrd:leave-initrd:sysinit:ready
 
-# /usr/lib/systemd/ukify -c ukify.conf \
-        /lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
-        /some/path/initramfs-6.0.9-300.fc37.x86_64.img
+# /usr/lib/systemd/ukify -c ukify.conf build \
+        --linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
+        --initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img
       </programlisting>
 
       <para>One "initrd" (<filename index='false'>early_cpio</filename>) is specified in the config file, and
@@ -482,7 +486,7 @@ Phases=enter-initrd:leave-initrd
     <example>
       <title>Kernel command line auxiliary PE</title>
 
-      <programlisting>ukify \
+      <programlisting>ukify build \
       --secureboot-private-key=sb.key \
       --secureboot-certificate=sb.cert \
       --cmdline='debug' \
-- 
cgit v1.2.3