Merge pull request #32424 from oxij/nixos/related-packages

nixos: doc: implement related packages in the manual

4 files changed, 57 insertions, 7 deletions

diff --git a/lib/default.nix b/lib/default.nix
index 9dc4fea99fc2..eb19dc06ce80 100644
--- a/lib/default.nix
+++ b/lib/default.nix
@@ -56,7 +56,7 @@ let
       replaceStrings seq stringLength sub substring tail;
     inherit (trivial) id const concat or and boolToString mergeAttrs
       flip mapNullable inNixShell min max importJSON warn info
-      nixpkgsVersion mod;
+      nixpkgsVersion mod compare splitByAndCompare;
 
     inherit (fixedPoints) fix fix' extends composeExtensions
       makeExtensible makeExtensibleWithCustomName;
@@ -71,8 +71,8 @@ let
     inherit (lists) singleton foldr fold foldl foldl' imap0 imap1
       concatMap flatten remove findSingle findFirst any all count
       optional optionals toList range partition zipListsWith zipLists
-      reverseList listDfs toposort sort take drop sublist last init
-      crossLists unique intersectLists subtractLists
+      reverseList listDfs toposort sort compareLists take drop sublist
+      last init crossLists unique intersectLists subtractLists
       mutuallyExclusive;
     inherit (strings) concatStrings concatMapStrings concatImapStrings
       intersperse concatStringsSep concatMapStringsSep
diff --git a/lib/lists.nix b/lib/lists.nix
index 8f67c6bb0ca3..f7e09040a5aa 100644
--- a/lib/lists.nix
+++ b/lib/lists.nix
@@ -385,6 +385,30 @@ rec {
       if len < 2 then list
       else (sort strictLess pivot.left) ++  [ first ] ++  (sort strictLess pivot.right));
 
+  /* Compare two lists element-by-element.
+
+     Example:
+       compareLists compare [] []
+       => 0
+       compareLists compare [] [ "a" ]
+       => -1
+       compareLists compare [ "a" ] []
+       => 1
+       compareLists compare [ "a" "b" ] [ "a" "c" ]
+       => 1
+  */
+  compareLists = cmp: a: b:
+    if a == []
+    then if b == []
+         then 0
+         else -1
+    else if b == []
+         then 1
+         else let rel = cmp (head a) (head b); in
+              if rel == 0
+              then compareLists cmp (tail a) (tail b)
+              else rel;
+
   /* Return the first (at most) N elements of a list.
 
      Example:
diff --git a/lib/options.nix b/lib/options.nix
index 769d3cc55723..ab1201c718a0 100644
--- a/lib/options.nix
+++ b/lib/options.nix
@@ -14,6 +14,7 @@ rec {
     , defaultText ? null # Textual representation of the default, for in the manual.
     , example ? null # Example value used in the manual.
     , description ? null # String describing the option.
+    , relatedPackages ? null # Related packages used in the manual.
     , type ? null # Option type, providing type-checking and value merging.
     , apply ? null # Function that converts the option value to something else.
     , internal ? null # Whether the option is for NixOS developers only.
@@ -76,7 +77,6 @@ rec {
   getValues = map (x: x.value);
   getFiles = map (x: x.file);
 
-
   # Generate documentation template from the list of option declaration like
   # the set generated with filterOptionSets.
   optionAttrSetToDocList = optionAttrSetToDocList' [];
@@ -93,9 +93,10 @@ rec {
           readOnly = opt.readOnly or false;
           type = opt.type.description or null;
         }
-        // (if opt ? example then { example = scrubOptionValue opt.example; } else {})
-        // (if opt ? default then { default = scrubOptionValue opt.default; } else {})
-        // (if opt ? defaultText then { default = opt.defaultText; } else {});
+        // optionalAttrs (opt ? example) { example = scrubOptionValue opt.example; }
+        // optionalAttrs (opt ? default) { default = scrubOptionValue opt.default; }
+        // optionalAttrs (opt ? defaultText) { default = opt.defaultText; }
+        // optionalAttrs (opt ? relatedPackages && opt.relatedPackages != null) { inherit (opt) relatedPackages; };
 
         subOptions =
           let ss = opt.type.getSubOptions opt.loc;
diff --git a/lib/trivial.nix b/lib/trivial.nix
index c452c7b65bc1..5f18c0b61cc0 100644
--- a/lib/trivial.nix
+++ b/lib/trivial.nix
@@ -81,6 +81,31 @@ rec {
   */
   mod = base: int: base - (int * (builtins.div base int));
 
+  /* C-style comparisons
+
+     a < b  => -1
+     a == b => 0
+     a > b  => 1
+  */
+  compare = a: b:
+    if a < b
+    then -1
+    else if a > b
+         then 1
+         else 0;
+
+  /* Split type into two subtypes by predicate `p`, assume
+
+       forall x y . x < y if p x == true && p y == false
+
+     compare elements of the same subtype with `yes` and `no`
+     comparisons respectively.
+  */
+  splitByAndCompare = p: yes: no: a: b:
+    if p a
+    then if p b then yes a b else -1
+    else if p b then 1 else no a b;
+
   /* Reads a JSON file. */
   importJSON = path:
     builtins.fromJSON (builtins.readFile path);