feat(kernel,initrd): extend plugins with new options, stabilize

.github/workflows/spread-manual.yaml

@@ -70,7 +70,33 @@ jobs:
           path: tests
       - name: Kernel plugin test
         run: |
-          spread google:ubuntu-22.04-64:tests/spread/plugins/craft-parts/kernel
+          spread google:ubuntu-22.04-64:tests/spread/plugins/craft-parts/kernel       \
+                 google:ubuntu-22.04-64:tests/spread/plugins/craft-parts/kernel-bin   \
+                 google:ubuntu-22.04-64:tests/spread/plugins/craft-parts/kernel-cross \
+                 google:ubuntu-22.04-64:tests/spread/plugins/craft-parts/kernel-deb
+
+  initrd-plugins:
+    needs: [predicate, snap-build]
+    if: needs.predicate.outputs.should_run == 'true'
+    runs-on: [spread-installed]
+    steps:
+      - name: Cleanup job workspace
+        run: |
+          rm -rf "${{ github.workspace }}"
+          mkdir "${{ github.workspace }}"
+      - name: Checkout snapcraft
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          submodules: true
+      - name: Download snap artifact
+        uses: actions/download-artifact@v5
+        with:
+          name: snap
+          path: tests
+      - name: Initrd plugin test
+        run: |
+          spread google:ubuntu-22.04-64:tests/spread/plugins/craft-parts/initrd
 
   remote-build:
     needs: [predicate, snap-build]

docs/.custom_wordlist.txt

@@ -80,6 +80,8 @@ jemalloc
 JLink
 json
 KCalc
+kconfig
+kdefconfig
 keyrings
 landscape
 lang

docs/reference/plugins/initrd_plugin.rst

@@ -1,3 +1,6 @@
+.. meta::
+    :description: Understand the usage and meaning of the varies keys and environment variables used by the initrd plugin. See an example, test cases, and real world usage.
+
 .. _reference-initrd-plugin:
 
 Initrd plugin
@@ -84,7 +87,7 @@ initrd-build-efi-image
 If true, a Unified Kernel Image (UKI) will be created using the initrd
 compressed CPIO archive created by this plugin and a kernel image file. The
 kernel image must be present in ``${CRAFT_STAGE}`` and must be named
-``kernel.img``.
+``vmlinuz``.
 
 
 initrd-efi-image-key

docs/reference/plugins/kernel_plugin.rst

@@ -1,3 +1,5 @@
+.. meta::
+    :description: Understand the usage and meaning of the varies keys and environment variables used by the kernel plugin. See an example, test cases, and real world usage.
 .. _reference-kernel-plugin:
 
 Kernel plugin
@@ -29,8 +31,16 @@ kernel-kdefconfig
 
 **Default**: ``["defconfig"]``
 
-The kernel configurations to use when generating a ``.config``, such as those
-found in ``arch/${arch}/configs`` or ``kernel/configs``.
+The kernel configurations to use when generating a ``.config``. Multiple items
+in the list may be specified, but their order matters. Items later in the list
+take precedent over earlier items.
+
+If ``kernel-ubuntu-debian-package`` is ``true``, then the specified kdefconfig
+files must be in the annotations format and located in ``${CRAFT_PROJECT_DIR}/annotations``.
+
+If ``kernel-ubuntu-debian-package`` is ``false``, then the specified kdefconfig
+files must be in the regular kconfig fragment style and located in either
+``${CRAFT_PART_SRC}/arch/${CRAFT_ARCH_BUILD_FOR}/configs`` or ``${CRAFT_PART_SRC}/kernel/configs``.
 
 
 kernel-kconfigs
@@ -43,6 +53,10 @@ values in the base configurations established by the ``kernel-kdefconfig`` and
 ``kernel-ubuntu-kconfigflavour`` keys. The kernel build system is used to resolve any
 configuration dependencies or invalid combinations.
 
+If ``kernel-ubuntu-debian-package`` is ``true``, this option is unavailable.
+Instead, a config fragment should be put into ``${CRAFT_PROJECT_DIR}/annotations/``
+and specified in the ``kernel-kdefconfig`` key.
+
 
 kernel-tools
 ~~~~~~~~~~~~
@@ -52,6 +66,9 @@ kernel-tools
 A list of kernel tools to build. If set, the specified tools will be built and added to
 the final snap package.
 
+This option is incompatible with ``kernel-ubuntu-binary-package`` and instead,
+the tools to include should be specified in ``stage-packages``.
+
 Valid values are ``bpf``, ``cpupower``, and ``perf``.
 
 .. admonition:: Warning
@@ -89,6 +106,19 @@ kernels available on Launchpad.
 Valid values are Ubuntu release code names like ``jammy``, ``lunar``, or ``noble``.
 
 
+kernel-ubuntu-abinumber
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Type**: string
+
+A string which specifies a particular kernel version and, more importantly,
+ABI number of the kernel package to build. This value is meaningful when
+``kernel-ubuntu-release-name`` or ``kernel-ubuntu-binary-package`` are used. For the
+former, this value will be used when cloning the git repository for the chosen release.
+For the latter, this value will be used to specify the kernel version of the debian
+package.
+
+
 kernel-ubuntu-binary-package
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -109,17 +139,29 @@ repackaged into a snap. A particular ABI may be specified with ``kernel-ubuntu-a
    for a viable workaround.
 
 
-kernel-ubuntu-abinumber
-~~~~~~~~~~~~~~~~~~~~~~~
+kernel-ubuntu-debian-package
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-**Type**: string
+**Type**: bool
 
-A string which specifies a particular kernel version and, more importantly,
-ABI number of the kernel package to build. This value is meaningful when
-``kernel-ubuntu-release-name`` or ``kernel-ubuntu-binary-package`` are used. For the
-former, this value will be used when cloning the git repository for the chosen release.
-For the latter, this value will be used to specify the kernel version of the debian
-package.
+**Default**: ``false``
+
+If enabled, the kernel will be built following how debian packages traditionally are.
+This means that the build steps are handled by the ``debian/rules`` makefile, rather
+than any direct ``make`` invocations as is done in other cases with this plugin.
+
+This option is primarily intended to be used by the Canonical Kernel team. Its
+usage requires the kernel source provides a valid ``debian/`` directory.
+
+
+kernel-ubuntu-debian-dkms
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Type**: list of strings
+
+A list of DKMS packages to include in the debian package build of the kernel.
+
+This option is only meaningful when used with ``kernel-ubuntu-debian-package``.
 
 
 Environment variables
@@ -208,6 +250,50 @@ specified.
 How it works
 ------------
 
+There are three primary patterns for this plugin depending on the selected keys.
+
+1. ``kernel-ubuntu-binary-package: true``
+#. ``kernel-ubuntu-debian-package: true``
+#. Neither
+
+
+Binary package
+~~~~~~~~~~~~~~
+
+In the case where building from a binary package, most of the processes used by
+this plugin are skipped. Instead, a prebuilt kernel image and its associated
+modules are fetched from the archive and staged to the expected locations for a
+kernel snap.
+
+This option is the fastest route to producing a kernel snap when a kernel debian
+package already exists, and no real changes need to be made to it.
+
+
+Debian package
+~~~~~~~~~~~~~~
+
+This case performs a source-based build, following the standard Ubuntu kernel
+build method as closely as possible. Ultimately, ``dpkg`` and its associated
+tools are responsible for configuring and building a kernel and its modules,
+with options to include DKMS packages from the archive or to build the supported
+kernel tools.
+
+By the end, several deb packages will be produced and then extracted and staged.
+This option supplants the binary package option in cases where the kernel must
+be customized in some way, but the standard debian tooling still needs to be
+used to build the kernel.
+
+
+Neither
+~~~~~~~
+
+This case performs a complete build of an arbitrary kernel source, whether it be
+for a debian package or from some other maintainer.
+
+This option is the most feature-rich path enabling end-to-end control over the
+entire kernel, and is most useful for doing board development work when you have
+a known-working kernel for the hardware and need to package it into a snap.
+
 During the build step the plugin performs the following actions:
 
 #. Pass a collection of flags built from the selected keys to a kernel build
@@ -245,7 +331,9 @@ key, and so a generic ``kernel-ubuntu-kconfigflavour`` is used (as this is the
 default behavior, no key is specified). A specific tag (Ubuntu-5.15.0-176.186)
 is named with the ``kernel-ubuntu-abinumber`` key, which means that tag of the
 Jammy tree will be cloned. A kernel config value is specified to remove debug
-information.
+information. The kernel is then built following the standard ``make defconfig;
+make; make install`` pattern rather than using tools like ``dpkg`` to produce
+and unpack a deb.
 
 The linux-firmware and wireless-regdb packages are staged with this part for
 convenience but are not necessarily required.