diff options
Diffstat (limited to 'nix/readTree/README.md')
| -rw-r--r-- | nix/readTree/README.md | 28 |
1 files changed, 21 insertions, 7 deletions
diff --git a/nix/readTree/README.md b/nix/readTree/README.md index c93cf2bfdd..5d430d1cfc 100644 --- a/nix/readTree/README.md +++ b/nix/readTree/README.md @@ -52,14 +52,20 @@ true;` attribute merged into it. `readTree` will follow any subdirectories of a tree and import all Nix files, with some exceptions: +* If a folder contains a `default.nix` file, no *sibling* Nix files will be + imported - however children are traversed as normal. +* If a folder contains a `default.nix` it is loaded and, if it + evaluates to a set, *merged* with the children. If it evaluates to + anything other than a set, else the children are *not traversed*. +* A folder can opt out from readTree completely by containing a + `.skip-tree` file. The content of the file is not read. These + folders will be missing completely from the readTree structure. * A folder can declare that its children are off-limit by containing a `.skip-subtree` file. Since the content of the file is not checked, it can be useful to leave a note for a human in the file. -* If a folder contains a `default.nix` file, no *sibling* Nix files will be - imported - however children are traversed as normal. -* If a folder contains a `default.nix` it is loaded and, if it evaluates to a - set, *merged* with the children. If it evaluates to anything else the children - are *not traversed*. +* The `default.nix` of the top-level folder on which readTree is + called is **not** read to avoid infinite recursion (as, presumably, + this file is where readTree itself is called). Traversal is lazy, `readTree` will only build up the tree as requested. This currently has the downside that directories with no importable files end up in @@ -67,8 +73,16 @@ the tree as empty nodes (`{}`). ## Import structure -`readTree` is called with two parameters: The arguments to pass to all imports, -and the initial path at which to start the traversal. +`readTree` is called with an argument set containing a few parameters: + +* `path`: Initial path at which to start the traversal. +* `args`: Arguments to pass to all imports. +* `filter`: (optional) A function to filter the argument set on each + import based on the location in the tree. This can be used to, for + example, implement a "visibility" system inside of a tree. +* `scopedArgs`: (optional) An argument set that is passed to all + imported files via `builtins.scopedImport`. This will forcefully + override the given values in the import scope, use with care! The package headers in this repository follow the form `{ pkgs, ... }:` where `pkgs` is a fixed-point of the entire package tree (see the `default.nix` at the |