From 25bdcd51e86eaee6d5e2a0d908cdd0caa82b2ccd Mon Sep 17 00:00:00 2001
From: nicoo <nicoo@mur.at>
Date: Thu, 28 Nov 2024 16:55:04 +0000
Subject: [PATCH] lib.packagesFromDirectoryRecursive: Split and explain
 examples, warn about scope limitation

---
 lib/filesystem.nix | 35 +++++++++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/lib/filesystem.nix b/lib/filesystem.nix
index 17ca23606f8be..b8ce722dac557 100644
--- a/lib/filesystem.nix
+++ b/lib/filesystem.nix
@@ -328,7 +328,7 @@ in
 
     # Examples
     :::{.example}
-    ## `lib.filesystem.packagesFromDirectoryRecursive` usage example
+    ## Basic use of `lib.packagesFromDirectoryRecursive`
 
     ```nix
     packagesFromDirectoryRecursive {
@@ -336,17 +336,48 @@ in
       directory = ./my-packages;
     }
     => { ... }
+    ```
+
+    In this case, `callPackage` will only search `pkgs` for a file's input parameters.
+    In other words, a file cannot refer to another file in the directory in its input parameters.
+    :::
 
+    ::::{.example}
+    ## Create a scope for the nix files found in a directory
+    ```nix
     lib.makeScope pkgs.newScope (
       self: packagesFromDirectoryRecursive {
-        callPackage = self.callPackage;
+        inherit (self) callPackage;
         directory = ./my-packages;
       }
     )
     => { ... }
     ```
 
+    For example, take the following directory structure:
+    ```
+    my-packages
+    ├── a.nix    → { b }: assert b ? b1; ...
+    └── b
+       ├── b1.nix  → { a }: ...
+       └── b2.nix
+    ```
+
+    Here, `b1.nix` can specify `{ a }` as a parameter, which `callPackage` will resolve as expected.
+    Likewise, `a.nix` receive an attrset corresponding to the contents of the `b` directory.
+
+    :::{.note}
+    `a.nix` cannot directly take as inputs packages defined in a child directory, such as `b1`.
+    :::
+
+    :::{.warning}
+    As of now, `lib.packagesFromDirectoryRecursive` cannot create nested scopes for sub-directories.
+
+    In particular, files under `b/` can only require (as inputs) other files under `my-packages`,
+    but not to those in the same directory, nor those in a parent directory; e.g, `b2.nix` cannot directly
+    require `b1`.
     :::
+    ::::
   */
   packagesFromDirectoryRecursive =
     {