rl-2411: lib release notes (#359887)

Author: infinisil

nixos/doc/manual/redirects.json

@@ -1871,6 +1871,18 @@
   "sec-release-24.11-wiki": [
     "release-notes.html#sec-release-24.11-wiki"
   ],
+  "sec-release-24.11-lib": [
+    "release-notes.html#sec-release-24.11-lib"
+  ],
+  "sec-release-24.11-lib-breaking": [
+    "release-notes.html#sec-release-24.11-lib-breaking"
+  ],
+  "sec-release-24.11-lib-additions-improvements": [
+    "release-notes.html#sec-release-24.11-lib-additions-improvements"
+  ],
+  "sec-release-24.11-lib-deprecations": [
+    "release-notes.html#sec-release-24.11-lib-deprecations"
+  ],
   "sec-release-24.05": [
     "release-notes.html#sec-release-24.05"
   ],

nixos/doc/manual/release-notes/rl-2411.section.md

@@ -797,10 +797,6 @@
   not the `hare` package, should be added to `nativeBuildInputs` when building
   Hare programs.
 
-- [`lib.options.mkPackageOptionMD`](https://nixos.org/manual/nixpkgs/unstable#function-library-lib.options.mkPackageOptionMD) is now obsolete; use the identical [`lib.options.mkPackageOption`](https://nixos.org/manual/nixpkgs/unstable#function-library-lib.options.mkPackageOption) instead.
-
-- `lib.misc.mapAttrsFlatten` is now formally deprecated and will be removed in future releases; use the identical [`lib.attrsets.mapAttrsToList`](https://nixos.org/manual/nixpkgs/unstable#function-library-lib.attrsets.mapAttrsToList) instead.
-
 - `virtualisation.docker.liveRestore` has been renamed to `virtualisation.docker.daemon.settings."live-restore"` and turned off by default for state versions of at least 24.11.
 
 - Tailscale's `authKeyFile` can now have its corresponding parameters set through `config.services.tailscale.authKeyParameters`, allowing for non-ephemeral unsupervised deployment and more.
@@ -977,6 +973,57 @@ To provide some examples:
 
 Note that this also allows writing overlays that explicitly apply to multiple boards.
 
+## Nixpkgs Library {#sec-release-24.11-lib}
+
+### Breaking changes {#sec-release-24.11-lib-breaking}
+
+- [`lib.escapeShellArg`](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.strings.escapeShellArg) and [`lib.escapeShellArgs`](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.strings.escapeShellArgs): Arguments that don't need to be escaped won't be anymore, which is not breaking according to the functions documentation, but it can cause breakages if used for the non-intended use cases.
+- [`lib.warn msg val`](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.trivial.warn) (and its relatives [`lib.warnIf`](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.trivial.warnIf) and [`lib.warnIfNot`](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.trivial.warnIfNot)) now require `msg` to be a string to match the behavior of the new [`builtins.warn`](https://nix.dev/manual/nix/2.25/language/builtins.html?highlight=warn#builtins-warn).
+- `lib.mdDoc`: Removed after deprecation in the previous release.
+
+### Additions and Improvements {#sec-release-24.11-lib-additions-improvements}
+
+New and extended interfaces:
+- [`lib.fromHexString`](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.trivial.fromHexString): Convert a hexadecimal string to it's integer representation.
+- `lib.network.ipv6.fromString`: Parse an IPv6 address.
+- [`lib.getLicenseFromSpdxIdOr`](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.meta.getLicenseFromSpdxIdOr): Get the corresponding attribute in `lib.licenses` from an SPDX ID or fall back to the given default value.
+- [`lib.licensesSpdx`](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.meta.licensesSpdx): Mapping of SPDX ID to the attributes in `lib.licenses`.
+- [`lib.getFirstOutput`](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.attrsets.getFirstOutput): Like `getOutput` but with a list of fallback output names.
+- [`lib.getInclude`](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.attrsets.getInclude) and [`lib.getStatic`](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.attrsets.getStatic): Get a package’s `include`/`static` output.
+- [`lib.trim`](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.strings.trim) and [`lib.trimWith`](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.strings.trimWith): Remove leading and trailing whitespace from a string.
+- [`lib.meta.defaultPriority`](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.meta.defaultPriority): The default priority of packages in Nix.
+- [`lib.toExtension`](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.fixedPoints.toExtension): Convert to an extending function (overlay).
+- `lib.fetchers.normalizeHash`: Convert an attrset containing one of `hash`, `sha256` or `sha512` into one containing `outputHash{,Algo}` as accepted by `mkDerivation`.
+- `lib.fetchers.withNormalizedHash`: Wraps a function which accepts `outputHash{,Algo}` into one which accepts `hash`, `sha256` or `sha512`.
+- Various builtins are now reexported in a more standard way:
+  - `lib.map` -> `lib.lists.map` -> `builtins.map`
+  - `lib.intersectAttrs` -> `lib.attrsets.intersectAttrs` -> `builtins.intersectAttrs`
+  - `lib.removeAttrs` -> `lib.attrsets.removeAttrs` -> `builtins.removeAttrs`
+  - `lib.match` -> `lib.strings.match` -> `builtins.match`
+  - `lib.split` -> `lib.strings.split` -> `builtins.split`
+  - `lib.typeOf` -> `builtins.typeOf`
+  - `lib.unsafeGetAttrPos` -> `builtins.unsafeGetAttrPos`
+- [`lib.cli.toGNUCommandLine`](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.cli.toGNUCommandLine) now supports the `optionValueSeparator` argument attribute to control the key-value separator for arguments.
+
+Documentation improvements:
+- Much of the documentation has been migrated to the [standard doc-comment format](https://github.com/NixOS/rfcs/pull/145), including [`lib.derivations`](https://nixos.org/manual/nixpkgs/unstable/#sec-functions-library-derivations), [`lib.fixedPoints`](https://nixos.org/manual/nixpkgs/unstable/#sec-functions-library-fixedPoints), [`lib.gvariant`](https://nixos.org/manual/nixpkgs/unstable/#sec-functions-library-gvariant), [`lib.filesystem`](https://nixos.org/manual/nixpkgs/unstable/#sec-functions-library-filesystem), [`lib.strings`](https://nixos.org/manual/nixpkgs/unstable/#sec-functions-library-strings), [`lib.meta`](https://nixos.org/manual/nixpkgs/unstable/#sec-functions-library-meta).
+- [`lib.generators` documentation](https://nixos.org/manual/nixpkgs/unstable/#sec-functions-library-generators) is now improved and rendered in the manual.
+- [`lib.cli` documentation](https://nixos.org/manual/nixpkgs/unstable/#sec-functions-library-cli) is now improved and rendered in the manual.
+- [`lib.composeExtensions`](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.fixedPoints.composeExtensions) and [`lib.composeManyExtensions`](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.fixedPoints.composeManyExtensions) documentation is now improved.
+- [`lib.importTOML`](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.trivial.importTOML) and [`lib.importJSON`](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.trivial.importJSON)'s documentation now have an example.
+
+Module System:
+- `lib.importApply`: New function, imports a Nix expression file much like the module system would, after passing an extra positional argument to the function in the file.
+- Improve error message when accessing an option that isn't defined.
+- `lib.types.anything`: Don't fail to merge when specifying the same list multiple times.
+- Improve error when loading a flake as a module.
+
+### Deprecations {#sec-release-24.11-lib-deprecations}
+
+- [`lib.options.mkPackageOptionMD`](https://nixos.org/manual/nixpkgs/unstable#function-library-lib.options.mkPackageOptionMD) is now obsolete; use the identical [`lib.options.mkPackageOption`](https://nixos.org/manual/nixpkgs/unstable#function-library-lib.options.mkPackageOption) instead.
+- `lib.misc.mapAttrsFlatten` is now formally deprecated and will be removed in future releases; use the identical [`lib.attrsets.mapAttrsToList`](https://nixos.org/manual/nixpkgs/unstable#function-library-lib.attrsets.mapAttrsToList) instead.
+- `lib.isInOldestRelease`: Renamed to [`oldestSupportedReleaseIsAtLeast`](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.trivial.oldestSupportedReleaseIsAtLeast) and deprecated.
+
 ## NixOS Wiki {#sec-release-24.11-wiki}
 
 The official NixOS Wiki at [wiki.nixos.org](https://wiki.nixos.org/) was launched in April 2024, featuring