xen: documentation and build fixes

pkgs/applications/virtualization/xen/README.md

@@ -40,7 +40,8 @@ but you should verify this information by seeking the fingerprint from other tru
 sources, as this document may be compromised. Once the PGP key is verified, it will
 use `git verify-tag` to ascertain the validity of the cloned Xen sources.
 
-After the script is done, follow the steps in [**For Both Update Methods**](#for-both-update-methods) below.
+After the script is done, follow the steps in
+[**For Both Update Methods**](#for-both-update-methods) below.
 
 #### Downstream Patch Names
 
@@ -87,8 +88,17 @@ open a PR fixing the script, and update Xen manually:
 
 ### For Both Update Methods
 
+1. Update `packages.nix` with the new versions. Don't forget the `slim` packages!
 1. Make sure all branches build. (Both the `standard` and `slim` versions)
 1. Use the NixOS module to test if dom0 boots successfully on all new versions.
+1. Make sure the `meta` attributes evaluate to something that makes sense. The
+   following one-line command is useful for testing this:
+
+   ```console
+   xenToEvaluate=xen; echo -e "\033[1m$(nix eval .#"$xenToEvaluate".meta.description 2> /dev/null | tail -c +2 | head -c -2)\033[0m\n\n$(nix eval .#"$xenToEvaluate".meta.longDescription 2> /dev/null | tail -c +2 | head -c -2)"
+   ```
+
+   Change the value of `xenToEvaluate` to evaluate all relevant Xen packages.
 1. Clean up your changes and commit them, making sure to follow the
    [Nixpkgs Contribution Guidelines](../../../../CONTRIBUTING.md).
 1. Open a PR and await a review from the current maintainers.

pkgs/applications/virtualization/xen/generic.nix

@@ -59,6 +59,7 @@ versionDefinition:
 
   # Documentation
   fig2dev,
+  imagemagick,
   pandoc,
 
   # Scripts
@@ -273,6 +274,7 @@ stdenv.mkDerivation (finalAttrs: {
   outputs = [
     "out" # TODO: Split $out in $bin for binaries and $lib for libraries.
     "man" # Manual pages for Xen userspace utilities.
+    "doc" # The full Xen documentation in HTML format.
     "dev" # Development headers.
     "boot" # xen.gz kernel, policy file if Flask is enabled, xen.efi if EFI is enabled.
   ];
@@ -293,6 +295,7 @@ stdenv.mkDerivation (finalAttrs: {
       bison
       cmake
       fig2dev
+      imagemagick # Causes build failures in Hydra related to fig generation if not included.
       flex
       pandoc
       pkg-config
@@ -561,10 +564,10 @@ stdenv.mkDerivation (finalAttrs: {
     '';
 
   postFixup =
-    # Fix binaries in $out/lib/xen/bin.
+    # Fix binaries in $out/libexec/xen/bin.
     ''
       addAutoPatchelfSearchPath $out/lib
-      autoPatchelf $out/libexec/xen/bin/
+      autoPatchelf $out/libexec/xen/bin
     ''
     # Flask is particularly hard to disable. Even after
     # setting the make flags to `n`, it still gets compiled.
@@ -628,11 +631,11 @@ stdenv.mkDerivation (finalAttrs: {
     longDescription =
       # Starts with the longDescription from ./packages.nix.
       (packageDefinition.meta.longDescription or "")
-      +
-        lib.strings.optionalString (!withInternalQEMU)
-          "\nUse with `qemu_xen_${lib.stringAsChars (x: if x == "." then "_" else x) branch}`"
-      + lib.strings.optionalString latest "or `qemu_xen`"
-      + "."
+      + lib.strings.optionalString (!withInternalQEMU) (
+        "\nUse with `qemu_xen_${lib.stringAsChars (x: if x == "." then "_" else x) branch}`"
+        + lib.strings.optionalString latest " or `qemu_xen`"
+        + ".\n"
+      )
       # Then, if any of the optional with* components are being built, add the "Includes:" string.
       +
         lib.strings.optionalString
@@ -645,22 +648,22 @@ stdenv.mkDerivation (finalAttrs: {
             || withFlask
           )
           (
-            "\nIncludes:\n"
+            "\nIncludes:"
             # Originally, this was a call for the complicated withPrefetchedSources. Since there aren't
             # that many optional components, we just use lib.strings.optionalString, because it's simpler.
             # Optional components that aren't being built are automatically hidden.
-            + lib.strings.optionalString withEFI "* `xen.efi`: Xen's [EFI binary](https://xenbits.xenproject.org/docs/${branch}-testing/misc/efi.html), available on the `boot` output of this package.\n"
-            + lib.strings.optionalString withFlask "* `xsm-flask`: The [FLASK Xen Security Module](https://wiki.xenproject.org/wiki/Xen_Security_Modules_:_XSM-FLASK). The `xenpolicy-${version}` file is available on the `boot` output of this package.\n"
-            + lib.strings.optionalString withInternalQEMU "* `qemu-xen`: Xen's mirror of [QEMU](https://www.qemu.org/).\n"
-            + lib.strings.optionalString withInternalSeaBIOS "* `seabios-xen`: Xen's mirror of [SeaBIOS](https://www.seabios.org/SeaBIOS).\n"
-            + lib.strings.optionalString withInternalOVMF "* `ovmf-xen`: Xen's mirror of [OVMF](https://github.com/tianocore/tianocore.github.io/wiki/OVMF).\n"
-            + lib.strings.optionalString withInternalIPXE "* `ipxe-xen`: Xen's pinned version of [iPXE](https://ipxe.org/).\n"
+            + lib.strings.optionalString withEFI "\n* `xen.efi`: Xen's [EFI binary](https://xenbits.xenproject.org/docs/${branch}-testing/misc/efi.html), available on the `boot` output of this package."
+            + lib.strings.optionalString withFlask "\n* `xsm-flask`: The [FLASK Xen Security Module](https://wiki.xenproject.org/wiki/Xen_Security_Modules_:_XSM-FLASK). The `xenpolicy-${version}` file is available on the `boot` output of this package."
+            + lib.strings.optionalString withInternalQEMU "\n* `qemu-xen`: Xen's mirror of [QEMU](https://www.qemu.org/)."
+            + lib.strings.optionalString withInternalSeaBIOS "\n* `seabios-xen`: Xen's mirror of [SeaBIOS](https://www.seabios.org/SeaBIOS)."
+            + lib.strings.optionalString withInternalOVMF "\n* `ovmf-xen`: Xen's mirror of [OVMF](https://github.com/tianocore/tianocore.github.io/wiki/OVMF)."
+            + lib.strings.optionalString withInternalIPXE "\n* `ipxe-xen`: Xen's pinned version of [iPXE](https://ipxe.org/)."
           )
       # Finally, we write a notice explaining which vulnerabilities this Xen is NOT vulnerable to.
       # This will hopefully give users the peace of mind that their Xen is secure, without needing
       # to search the source code for the XSA patches.
       + lib.strings.optionalString (writeAdvisoryDescription != [ ]) (
-        "\nThis Xen (${version}) has been patched against the following known security vulnerabilities:\n"
+        "\n\nThis Xen (${version}) has been patched against the following known security vulnerabilities:\n"
         + lib.strings.removeSuffix "\n" (lib.strings.concatLines writeAdvisoryDescription)
       );
     homepage = "https://xenproject.org/";

pkgs/applications/virtualization/xen/patches.nix

@@ -64,7 +64,10 @@ in
   #
   # "XSA_100" = xsaPatch {
   #   id = "100";
-  #   name = "Verbatim Title of XSA";
+  #   title = "Verbatim Title of XSA";
+  #   description = ''
+  #     Verbatim description of XSA.
+  #   '';
   #   cve = [ "CVE-1999-0001" "CVE-1999-0002" ]; # Not all XSAs have CVEs. This attribute is optional.
   #   hash = "sha256-0000000000000000000000000000000000000000000000000000";
   # };