Merge remote-tracking branch 'obsidian/meson-functional-tests' into m…

…eson-misc

.version

@@ -1 +1 @@
-2.24.0
+2.25.0

doc/manual/src/SUMMARY.md.in

@@ -28,6 +28,7 @@
   - [Data Types](language/types.md)
     - [String context](language/string-context.md)
   - [Syntax and semantics](language/syntax.md)
+    - [Variables](language/variables.md)
     - [Identifiers](language/identifiers.md)
     - [Scoping rules](language/scope.md)
     - [String interpolation](language/string-interpolation.md)
@@ -127,6 +128,7 @@
   - [Contributing](development/contributing.md)
 - [Releases](release-notes/index.md)
 {{#include ./SUMMARY-rl-next.md}}
+  - [Release 2.24 (2024-07-31)](release-notes/rl-2.24.md)
   - [Release 2.23 (2024-06-03)](release-notes/rl-2.23.md)
   - [Release 2.22 (2024-04-23)](release-notes/rl-2.22.md)
   - [Release 2.21 (2024-03-11)](release-notes/rl-2.21.md)

doc/manual/src/command-ref/env-common.md

@@ -9,22 +9,26 @@ Most Nix commands interpret the following environment variables:
 
 - <span id="env-NIX_PATH">[`NIX_PATH`](#env-NIX_PATH)</span>
 
-  A colon-separated list of directories used to look up the location of Nix
-  expressions using [paths](@docroot@/language/types.md#type-path)
-  enclosed in angle brackets (i.e., `<path>`),
-  e.g. `/home/eelco/Dev:/etc/nixos`. It can be extended using the
-  [`-I` option](@docroot@/command-ref/opt-common.md#opt-I).
+  A colon-separated list of search path entries used to resolve [lookup paths](@docroot@/language/constructs/lookup-path.md).
 
-  If `NIX_PATH` is not set at all, Nix will fall back to the following list in [impure](@docroot@/command-ref/conf-file.md#conf-pure-eval) and [unrestricted](@docroot@/command-ref/conf-file.md#conf-restrict-eval) evaluation mode:
+  This environment variable overrides the value of the [`nix-path` configuration setting](@docroot@/command-ref/conf-file.md#conf-nix-path).
 
-  1. `$HOME/.nix-defexpr/channels`
-  2. `nixpkgs=/nix/var/nix/profiles/per-user/root/channels/nixpkgs`
-  3. `/nix/var/nix/profiles/per-user/root/channels`
+  It can be extended using the [`-I` option](@docroot@/command-ref/opt-common.md#opt-I).
+
+  > **Example**
+  >
+  > ```bash
+  > $ export NIX_PATH=`/home/eelco/Dev:nixos-config=/etc/nixos
+  > ```
 
   If `NIX_PATH` is set to an empty string, resolving search paths will always fail.
-  For example, attempting to use `<nixpkgs>` will produce:
 
-      error: file 'nixpkgs' was not found in the Nix search path
+  > **Example**
+  >
+  > ```bash
+  > $ NIX_PATH= nix-instantiate --eval '<nixpkgs>'
+  > error: file 'nixpkgs' was not found in the Nix search path (add it using $NIX_PATH or -I)
+  > ```
 
 - <span id="env-NIX_IGNORE_SYMLINK_STORE">[`NIX_IGNORE_SYMLINK_STORE`](#env-NIX_IGNORE_SYMLINK_STORE)</span>
 

doc/manual/src/command-ref/nix-shell.md

@@ -297,3 +297,8 @@ with import <nixpkgs> {};
 
 runCommand "dummy" { buildInputs = [ python pythonPackages.prettytable ]; } ""
 ```
+
+The script's file name is passed as the first argument to the interpreter specified by the `-i` flag.
+
+Aside from the very first line, which is a directive to the operating system, the additional `#! nix-shell` lines do not need to be at the beginning of the file.
+This allows wrapping them in block comments for languages where `#` does not start a comment, such as ECMAScript, Erlang, PHP, or Ruby.

doc/manual/src/command-ref/opt-common.md

@@ -37,7 +37,7 @@ Most Nix commands accept the following command-line options:
     Print even more informational messages.
 
   - `4` “Debug”
-   
+
     Print debug information.
 
   - `5` “Vomit”
@@ -187,11 +187,12 @@ Most Nix commands accept the following command-line options:
   For `nix-shell`, this option is commonly used to give you a shell in which you can build the packages returned by the expression.
   If you want to get a shell which contain the *built* packages ready for use, give your expression to the `nix-shell --packages ` convenience flag instead.
 
-- <span id="opt-I">[`-I`](#opt-I)</span> *path*
+- <span id="opt-I">[`-I` / `--include`](#opt-I)</span> *path*
 
-  Add an entry to the [Nix expression search path](@docroot@/command-ref/conf-file.md#conf-nix-path).
+  Add an entry to the list of search paths used to resolve [lookup paths](@docroot@/language/constructs/lookup-path.md).
   This option may be given multiple times.
-  Paths added through `-I` take precedence over [`NIX_PATH`](@docroot@/command-ref/env-common.md#env-NIX_PATH).
+
+  Paths added through `-I` take precedence over the [`nix-path` configuration setting](@docroot@/command-ref/conf-file.md#conf-nix-path) and the [`NIX_PATH` environment variable](@docroot@/command-ref/env-common.md#env-NIX_PATH).
 
 - <span id="opt-option">[`--option`](#opt-option)</span> *name* *value*
 

doc/manual/src/language/identifiers.md

@@ -16,13 +16,14 @@ An *identifier* is an [ASCII](https://en.wikipedia.org/wiki/ASCII) character seq
 
 # Names
 
-A name can be an [identifier](#identifier) or a [string literal](./syntax.md#string-literal).
+A *name* can be written as an [identifier](#identifier) or a [string literal](./syntax.md#string-literal).
 
 > **Syntax**
 >
 > *name* → *identifier* | *string*
 
-Names are used in [attribute sets](./syntax.md#attrs-literal), [`let` bindings](./syntax.md#let-expressions), and [`inherit`](./syntax.md#inheriting attributes).
+Names are used in [attribute sets](./syntax.md#attrs-literal), [`let` bindings](./syntax.md#let-expressions), and [`inherit`](./syntax.md#inheriting-attributes).
+Two names are the same if they represent the same sequence of characters, regardless of whether they are written as identifiers or strings.
 
 # Keywords
 

doc/manual/src/language/scope.md

@@ -1,14 +1,28 @@
 # Scoping rules
 
-Nix is [statically scoped](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scope), but with multiple scopes and shadowing rules.
+A *scope* in the Nix language is a dictionary keyed by [name](./identifiers.md#names), mapping each name to an expression and a *definition type*.
+The definition type is either *explicit* or *implicit*.
+Each entry in this dictionary is a *definition*.
 
-* primary scope: explicitly-bound variables
-  * [`let`](./syntax.md#let-expressions)
-  * [`inherit`](./syntax.md#inheriting-attributes)
-  * [function](./syntax.md#functions) arguments
+Explicit definitions are created by the following expressions:
+- [let-expressions](syntax.md#let-expressions)
+- [recursive attribute set literals](syntax.md#recursive-sets) (`rec`)
+- [function literals](syntax.md#functions)
 
-* secondary scope: implicitly-bound variables
-  * [`with`](./syntax.md#with-expressions)
+Implicit definitions are only created by [with-expressions](./syntax.md#with-expressions).
 
-Primary scope takes precedence over secondary scope.
-See [`with`](./syntax.md#with-expressions) for a detailed example.
+Every expression is *enclosed* by a scope.
+The outermost expression is enclosed by the [built-in, global scope](./builtins.md), which contains only explicit definitions.
+The expressions listed above *extend* their enclosing scope by adding new definitions, or replacing existing ones with the same name.
+An explicit definition can replace a definition of any type; an implicit definition can only replace another implicit definition.
+
+Each of the above expressions defines which of its subexpressions are enclosed by the extended scope.
+In all other cases, the same scope that encloses an expression is the enclosing scope for its subexpressions.
+
+The Nix language is [statically scoped](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scope);
+the value of a variable is determined only by the variable's enclosing scope, and not by the dynamic context in which the variable is evaluated.
+
+> **Note**
+>
+> Expressions entered into the [Nix REPL](@docroot@/command-ref/new-cli/nix3-repl.md) are enclosed by a scope that can be extended by command line arguments or previous REPL commands.
+> These ways of extending scope are not, strictly speaking, part of the Nix language.

doc/manual/src/language/variables.md

@@ -0,0 +1,10 @@
+# Variables
+
+A *variable* is an [identifier](identifiers.md) used as an expression.
+
+> **Syntax**
+>
+> *expression* → *identifier*
+
+A variable must have the same name as a definition in the [scope](./scope.md) that encloses it.
+The value of a variable is the value of the corresponding expression in the enclosing scope.