From 9ad0ace8c0ce981703d8ece9f541a596271ec4a1 Mon Sep 17 00:00:00 2001 From: piegames Date: Fri, 23 Jan 2026 17:12:48 +0100 Subject: [PATCH] deprecated-features: Rewrite feature descriptions Changed the writing style of the descriptions, expanded with more examples and rationale, and added the new timline metadata in the frontmatter. Change-Id: I218389e3504fc21f4eb45a927e77a41a1a70d4f5 --- .../deprecated-features/ancient-let.md | 7 +++++- .../deprecated-features/cr-line-endings.md | 14 +++++++++-- .../deprecated-features/nix-path-shadow.md | 8 ++++++- lix/libutil/deprecated-features/nul-bytes.md | 8 +++++-- .../deprecated-features/rec-set-overrides.md | 10 ++++++-- .../shadow-internal-symbols.md | 23 ++++++++++++++++++- .../deprecated-features/url-literals.md | 11 ++++++++- 7 files changed, 71 insertions(+), 10 deletions(-) diff --git a/lix/libutil/deprecated-features/ancient-let.md b/lix/libutil/deprecated-features/ancient-let.md index ced9934bb..c0952226f 100644 --- a/lix/libutil/deprecated-features/ancient-let.md +++ b/lix/libutil/deprecated-features/ancient-let.md @@ -1,7 +1,12 @@ --- name: ancient-let internalName: AncientLet +timeline: + - date: 2024-09-18 + release: 2.92.0 + cls: [1787] + message: Introduced as soft deprecation with a warning. --- -Allow the ancient `let { body = …; … }` syntax. +The ancient `let { body = …; … }` syntax is deprecated. Use the `let … in` syntax instead. diff --git a/lix/libutil/deprecated-features/cr-line-endings.md b/lix/libutil/deprecated-features/cr-line-endings.md index 7a4adf765..365662734 100644 --- a/lix/libutil/deprecated-features/cr-line-endings.md +++ b/lix/libutil/deprecated-features/cr-line-endings.md @@ -1,6 +1,16 @@ --- name: cr-line-endings internalName: CRLineEndings +timeline: + - date: 2025-02-05 + release: 2.93.0 + cls: [2475] + message: Introduced as a parser error. --- -Allow CR (`\r`) and CRLF (`\r\n`) as line delimiters. -Note however that the implementation is inconsistent and buggy and may lead to unexpected evaluation results with certain strings. +CR (`\r`) and CRLF (`\r\n`) are deprecated as line delimiters in Nix code. +The reason for the CR line ending deprecation is that no OS still uses them anymore. +The reason for the CRLF line ending deprecation is that there is a fatal bug in the indentation-stripping logic of indented strings, +breaking all indented strings when CRLF indentation is used. +In a future language revision, the CRLF line endings will be allowed again but with fixed semantics. + +To fix this, convert all files to have regular `\n` endings and disable all software which performs platform-specific normalizations. diff --git a/lix/libutil/deprecated-features/nix-path-shadow.md b/lix/libutil/deprecated-features/nix-path-shadow.md index 34840dec1..3c64ae8e9 100644 --- a/lix/libutil/deprecated-features/nix-path-shadow.md +++ b/lix/libutil/deprecated-features/nix-path-shadow.md @@ -1,6 +1,12 @@ --- name: nix-path-shadow internalName: NixPathShadow +timeline: + - date: 2025-11-23 + release: 2.95.0 + cls: [4632] + message: Introduced as an evaluation-time warning. --- -Allows shadowing `` by configuration of the [*nix path*](@docroot@/language/builtin-constants.html#builtins-nixPath) to a value containing `nix=/some/path`. +Shadowing `` by configuring the [*nix path*](@docroot@/language/builtin-constants.html#builtins-nixPath) to a value containing `nix=/some/path` is deprecated. +The namespace `nix` in the Nix path is reserved for usage in internal code, and overriding it may result in nontrivial breakage. diff --git a/lix/libutil/deprecated-features/nul-bytes.md b/lix/libutil/deprecated-features/nul-bytes.md index 483f88042..b79265588 100644 --- a/lix/libutil/deprecated-features/nul-bytes.md +++ b/lix/libutil/deprecated-features/nul-bytes.md @@ -1,6 +1,10 @@ --- name: nul-bytes internalName: NulBytes +timeline: + - date: 2025-02-05. + release: 2.93.0 + cls: [2476] + message: Introduced as a parser error. --- -Allow NUL bytes (`\0`) in Nix strings. -Note however that due to Nix using NUL-terminated strings internally, this may cause undefined behavior. +Raw NUL bytes (`\0`) in Nix string literals are deprecated. diff --git a/lix/libutil/deprecated-features/rec-set-overrides.md b/lix/libutil/deprecated-features/rec-set-overrides.md index 37d7003b1..e15fc2462 100644 --- a/lix/libutil/deprecated-features/rec-set-overrides.md +++ b/lix/libutil/deprecated-features/rec-set-overrides.md @@ -1,7 +1,13 @@ --- name: rec-set-overrides internalName: RecSetOverrides +timeline: + - date: 2024-09-18 + release: 2.92.0 + cls: [1744] + message: Introduced as soft deprecation with a warning. --- -Allow `__overrides` in recursive attribute sets. +The magic symbol `__overrides` in recursive attribute sets is deprecated. +It was introduced in the early days of the language before the widespread use of overlays and is not needed anymore. -Use fix point functions (e.g. `lib.fix` in Nixpkgs) instead. +To fix this, use fix point functions (e.g. `lib.fix` in Nixpkgs) instead. diff --git a/lix/libutil/deprecated-features/shadow-internal-symbols.md b/lix/libutil/deprecated-features/shadow-internal-symbols.md index 1d9c8a1be..5d4289523 100644 --- a/lix/libutil/deprecated-features/shadow-internal-symbols.md +++ b/lix/libutil/deprecated-features/shadow-internal-symbols.md @@ -1,5 +1,26 @@ --- name: shadow-internal-symbols internalName: ShadowInternalSymbols +timeline: + - date: 2024-11-18 + release: 2.92.0 + cls: [2206, 2295] + message: + Introduced as a parser error for the symbols `__sub`, `__mul`, `__div`, `__lessThan`. --- -Allow shadowing the symbols `__sub`, `__mul`, `__div`, `__lessThan`, `__findFile` when used in the internal AST expansion. (`5 - 3` expands to `__sub 5 3` etc.) +Shadowing symbol names used internally by the parser is deprecated. +As an example, `5 - 3` internally expands to `__sub 5 3` in the parser. +`__sub` is a symbol name in global scope, which could be shadowed by let bindings like any other. +Shadowing internal symbols is deprecated because it can lead to confusing unintended semantics in code. +Using this to override operators with custom implementations is not supported and will lead to unintended semantics. +(For example, overriding `__lessThan` will be ignored within builtin functions that perform comparison operations like sorting.) + +Note that the check happens at usage site, so `let __sub = null; in body` remains allowed for as long as `body` does not contain a subtraction operation. +Similarly, `let __sub = null; in __sub` remains allowed here because the explicit `__sub` usage is obvious and there is less potential for confusion. + +Affected symbol names: + +- `__sub` +- `__mul` +- `__div` +- `__lessThan` diff --git a/lix/libutil/deprecated-features/url-literals.md b/lix/libutil/deprecated-features/url-literals.md index 99232913f..ae1a0cf5b 100644 --- a/lix/libutil/deprecated-features/url-literals.md +++ b/lix/libutil/deprecated-features/url-literals.md @@ -1,5 +1,14 @@ --- name: url-literals internalName: UrlLiterals +timeline: + - date: 2024-08-17 + release: 2.92.0 + cls: [1785] + message: Removed the old `no-url-literals` experimental feature and turned it into a parse error by default. --- -Allow unquoted URLs as part of the Nix language syntax. +*URL literals* are unquoted string literals containing URLs directly as part of the Nix language syntax. +This was deprecated because it needlessly complicates the syntax for the little benefit of merely saving two characters. +Additionally, it is a cause of inconsistencies in the language: `x:x` is a (URL) string but `x: x` and `_:x` are functions. + +To fix this, put the URL in string quotation marks instead: `{ url = https://github.com/NixOS/nixpkgs; }` → `{ url = "https://github.com/NixOS/nixpkgs"; }`