[bug#45592] [PATCH] gnu, doc: Create and document procedure to compile ZFS for specific kernel.

[raid5atemyhomework]

Fixes: https://issues.guix.gnu.org/45401

As suggested in https://issues.guix.gnu.org/45403#3 this instead exposes a 
specific `make-zfs-package` procedure that can be combined in the system 
configuration file in order to create a ZFS package that is intended for the 
specific system.
It also gives a basic documentation on how to create a ZFS package for your 
system.

I have not tested the ZFS *yet*, but this actually lets me compile ZFS for 
various kernel versions, which is an improvement over the current situation 
where installing ZFS is not possible at all.

>From 56e108591c65ed3aed1872290133d51962acb4a2 Mon Sep 17 00:00:00 2001
From: raid5atemyhomework <raid5atemyhomework@protonmail.com>
Date: Fri, 1 Jan 2021 20:26:42 +0800
Subject: [PATCH] gnu, doc: Create and document procedure to compile ZFS for
 specific kernel.

---
 doc/guix.texi                 | 61 +++++++++++++++++++++++++++++++++++
 gnu/packages/file-systems.scm | 22 ++++++++++++-
 2 files changed, 82 insertions(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 1081ed26a3..1f874b4ee0 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -13885,6 +13885,67 @@ a file system declaration such as:
 compress-force=zstd,space_cache=v2"))
 @end lisp

+@node ZFS file system
+@subsection ZFS file system
+
+The ZFS on Linux file system cannot legally be downloaded as part of the
+Linux kernel, but you as a user can do anything on hardware you own,
+including download ZFS as source code, compile ZFS as a kernel module,
+and link it into Linux.
+
+As a large and complex kernel module, ZFS has to be compiled for a
+specific version of Linux. Often the latest ZFS package available in Guix
+cannot be compiled with the latest Linux kernel available in Guix, so
+installing the @code{zfs} package in your system configuration file will
+fail.
+
+Instead, you have to check the
+@url{https://github.com/openzfs/zfs/releases,OpenZFS release notes} for
+the specific version of ZFS that Guix has packaged to determine what
+Linux kernels you can use, then check the @code{linux-libre} packages
+that Guix has packaged, and select one you can use on your system.
+
+Then, you have to modify your system configuration file, and create a
+ZFS package that compiles using the specific Linux version you chose.
+Below is a sketch of how you would modify your @code{operating-system}
+declaration in order to set up ZFS:
+
+@lisp
+(use-modules (gnu))
+;; @dots{}
+(use-package-modules
+  ; @dots{}
+  linux
+  file-systems)
+
+;; @dots{}
+
+;; ZFS 0.8.5 is known to compile with Linux 5.9 series
+(define system-kernel linux-libre-5.9)
+(define system-zfs (make-zfs-package system-kernel))
+
+;; @dots{}
+
+(operating-system
+  (kernel system-kernel)
+  (kernel-loadable-modules (list system-zfs))
+  ;; @dots{}
+  (packages
+    (cons* system-zfs
+           ; @dots{}
+           %base-packages))
+  ;; @dots{}
+  )
+@end lisp
+
+@deffn (Scheme Procedure) make-zfs-package @var{kernel}
+This procedure creates a package which, when included as a package
+in your system, can be loaded as a kernel module for the specified
+@var{kernel}, a Linux kernel package.
+It is intended to create a system-specific ZFS kernel module for
+the Linux kernel you will use in your system.
+@end deffn
+
 @node Mapped Devices
 @section Mapped Devices

diff --git a/gnu/packages/file-systems.scm b/gnu/packages/file-systems.scm
index 895ad069c5..ebc4bc87c1 100644
--- a/gnu/packages/file-systems.scm
+++ b/gnu/packages/file-systems.scm
@@ -951,9 +951,29 @@ APFS.")
     (description
      "ZFS on Linux is an advanced file system and volume manager which was
 originally developed for Solaris and is now maintained by the OpenZFS
-community.")
+community.
+
+DO NOT INSTALL THIS PACKAGE. Instead, refer to the 'ZFS file system' section
+of the Guix info manual for how to install ZFS.")
     (license license:cddl1.0)))

+(define-public (make-zfs-package kernel)
+  (package
+    (inherit zfs)
+    (name (string-append "zfs-for-"
+                         (package-name kernel)
+                         "-"
+                         (package-version kernel)
+                         "-version"))
+    (arguments
+      (cons* #:linux kernel (package-arguments zfs)))
+    (description
+     "ZFS on Linux is an advanced file system and volume manager which was
+originally developed for Solaris and is now maintained by the OpenZFS
+community.
+
+This package has been compiled for a specific Linux kernel.")))
+
 (define-public mergerfs
   (package
     (name "mergerfs")
--
2.29.2