Merge pull request #244044 from tweag/lib-readme

Create a Readme in `lib`

5 files changed, 107 insertions, 6 deletions

diff --git a/lib/README.md b/lib/README.md
new file mode 100644
index 00000000000..ac7cbd4330a
--- /dev/null
+++ b/lib/README.md
@@ -0,0 +1,73 @@
+# Nixpkgs lib
+
+This directory contains the implementation, documentation and tests for the Nixpkgs `lib` library.
+
+## Overview
+
+The evaluation entry point for `lib` is [`default.nix`](default.nix).
+This file evaluates to an attribute set containing two separate kinds of attributes:
+- Sub-libraries:
+  Attribute sets grouping together similar functionality.
+  Each sub-library is defined in a separate file usually matching its attribute name.
+
+  Example: `lib.lists` is a sub-library containing list-related functionality such as `lib.lists.take` and `lib.lists.imap0`.
+  These are defined in the file [`lists.nix`](lists.nix).
+
+- Aliases:
+  Attributes that point to an attribute of the same name in some sub-library.
+
+  Example: `lib.take` is an alias for `lib.lists.take`.
+
+Most files in this directory are definitions of sub-libraries, but there are a few others:
+- [`minver.nix`](minver.nix): A string of the minimum version of Nix that is required to evaluate Nixpkgs.
+- [`tests`](tests): Tests, see [Running tests](#running-tests)
+  - [`release.nix`](tests/release.nix): A derivation aggregating all tests
+  - [`misc.nix`](tests/misc.nix): Evaluation unit tests for most sub-libraries
+  - `*.sh`: Bash scripts that run tests for specific sub-libraries
+  - All other files in this directory exist to support the tests
+- [`systems`](systems): The `lib.systems` sub-library, structured into a directory instead of a file due to its complexity
+- [`path`](path): The `lib.path` sub-library, which includes tests as well as a document describing the design goals of `lib.path`
+- All other files in this directory are sub-libraries
+
+### Module system
+
+The [module system](https://nixos.org/manual/nixpkgs/#module-system) spans multiple sub-libraries:
+- [`modules.nix`](modules.nix): `lib.modules` for the core functions and anything not relating to option definitions
+- [`options.nix`](options.nix): `lib.options` for anything relating to option definitions
+- [`types.nix`](types.nix): `lib.types` for module system types
+
+## Reference documentation
+
+Reference documentation for library functions is written above each function as a multi-line comment.
+These comments are processed using [nixdoc](https://github.com/nix-community/nixdoc) and [rendered in the Nixpkgs manual](https://nixos.org/manual/nixpkgs/stable/#chap-functions).
+The nixdoc README describes the [comment format](https://github.com/nix-community/nixdoc#comment-format).
+
+See the [chapter on contributing to the Nixpkgs manual](https://nixos.org/manual/nixpkgs/#chap-contributing) for how to build the manual.
+
+## Running tests
+
+All library tests can be run by building the derivation in [`tests/release.nix`](tests/release.nix):
+
+```bash
+nix-build tests/release.nix
+```
+
+Some commands for quicker iteration over parts of the test suite are also available:
+
+```bash
+# Run all evaluation unit tests in tests/misc.nix
+# if the resulting list is empty, all tests passed
+nix-instantiate --eval --strict tests/misc.nix
+
+# Run the module system tests
+tests/modules.sh
+
+# Run the lib.sources tests
+tests/sources.sh
+
+# Run the lib.filesystem tests
+tests/filesystem.sh
+
+# Run the lib.path property tests
+path/tests/prop.sh
+```
diff --git a/lib/path/tests/prop.sh b/lib/path/tests/prop.sh
index 9fea5215778..f321fdf1cf4 100755
--- a/lib/path/tests/prop.sh
+++ b/lib/path/tests/prop.sh
@@ -1,9 +1,12 @@
 #!/usr/bin/env bash
 
-# Property tests for the `lib.path` library
-#
+# Property tests for lib/path/default.nix
 # It generates random path-like strings and runs the functions on
 # them, checking that the expected laws of the functions hold
+# Run:
+# [nixpkgs]$ lib/path/tests/prop.sh
+# or:
+# [nixpkgs]$ nix-build lib/tests/release.nix
 
 set -euo pipefail
 shopt -s inherit_errexit
diff --git a/lib/tests/misc.nix b/lib/tests/misc.nix
index 86861695460..56bf31ea5da 100644
--- a/lib/tests/misc.nix
+++ b/lib/tests/misc.nix
@@ -1,6 +1,18 @@
-# to run these tests:
-# nix-instantiate --eval --strict nixpkgs/lib/tests/misc.nix
-# if the resulting list is empty, all tests passed
+/*
+Nix evaluation tests for various lib functions.
+
+Since these tests are implemented with Nix evaluation, error checking is limited to what `builtins.tryEval` can detect, which is `throw`'s and `abort`'s, without error messages.
+If you need to test error messages or more complex evaluations, see ./modules.sh, ./sources.sh or ./filesystem.sh as examples.
+
+To run these tests:
+
+  [nixpkgs]$ nix-instantiate --eval --strict lib/tests/misc.nix
+
+If the resulting list is empty, all tests passed.
+Alternatively, to run all `lib` tests:
+
+  [nixpkgs]$ nix-build lib/tests/release.nix
+*/
 with import ../default.nix;
 
 let
diff --git a/lib/tests/modules.sh b/lib/tests/modules.sh
index 50f24c09ca4..180cca9955e 100755
--- a/lib/tests/modules.sh
+++ b/lib/tests/modules.sh
@@ -1,7 +1,13 @@
 #!/usr/bin/env bash
-#
+
 # This script is used to test that the module system is working as expected.
+# Executing it runs tests for `lib.modules`, `lib.options` and `lib.types`.
 # By default it test the version of nixpkgs which is defined in the NIX_PATH.
+#
+# Run:
+# [nixpkgs]$ lib/tests/modules.sh
+# or:
+# [nixpkgs]$ nix-build lib/tests/release.nix
 
 set -o errexit -o noclobber -o nounset -o pipefail
 shopt -s failglob inherit_errexit
diff --git a/lib/tests/sources.sh b/lib/tests/sources.sh
index cda77aa96b2..079c7eea565 100755
--- a/lib/tests/sources.sh
+++ b/lib/tests/sources.sh
@@ -1,4 +1,11 @@
 #!/usr/bin/env bash
+
+# Tests lib/sources.nix
+# Run:
+# [nixpkgs]$ lib/tests/sources.sh
+# or:
+# [nixpkgs]$ nix-build lib/tests/release.nix
+
 set -euo pipefail
 shopt -s inherit_errexit