From 64de6c47ca242f3dc0b2608a28e66ba76678edf4 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Thu, 28 Nov 2024 17:21:41 +0100 Subject: [PATCH] rl-2411: `lib` release notes --- nixos/doc/manual/redirects.json | 12 ++++ .../manual/release-notes/rl-2411.section.md | 55 +++++++++++++++++-- 2 files changed, 63 insertions(+), 4 deletions(-) diff --git a/nixos/doc/manual/redirects.json b/nixos/doc/manual/redirects.json index e36f45074be39..5f7bf93db21ed 100644 --- a/nixos/doc/manual/redirects.json +++ b/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" ], diff --git a/nixos/doc/manual/release-notes/rl-2411.section.md b/nixos/doc/manual/release-notes/rl-2411.section.md index bf0d7c2646f71..74072bb3d42de 100644 --- a/nixos/doc/manual/release-notes/rl-2411.section.md +++ b/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. @@ -979,6 +975,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