From d1d1ae7a3b97059af09dd5a5dde2e37ada0fddac Mon Sep 17 00:00:00 2001 From: Noah Snelson Date: Mon, 27 Mar 2023 17:12:49 -0700 Subject: [PATCH] Documentation: list experimental features in manual Lists all current experimental features in the `nix.conf` manual. --- src/libutil/config.hh | 2 +- src/libutil/experimental-features.cc | 91 +++++++++++++++++++++++----- src/libutil/experimental-features.hh | 5 +- 3 files changed, 81 insertions(+), 17 deletions(-) diff --git a/src/libutil/config.hh b/src/libutil/config.hh index 748d6043b..59a766034 100644 --- a/src/libutil/config.hh +++ b/src/libutil/config.hh @@ -367,7 +367,7 @@ extern GlobalConfig globalConfig; struct ExperimentalFeatureSettings : Config { Setting> experimentalFeatures{this, {}, "experimental-features", - "Experimental Nix features to enable."}; + getExperimentalFeaturesList()}; /** * Check whether the given experimental feature is enabled. diff --git a/src/libutil/experimental-features.cc b/src/libutil/experimental-features.cc index 58d762ebb..fc8590674 100644 --- a/src/libutil/experimental-features.cc +++ b/src/libutil/experimental-features.cc @@ -5,18 +5,61 @@ namespace nix { -std::map stringifiedXpFeatures = { - { Xp::CaDerivations, "ca-derivations" }, - { Xp::ImpureDerivations, "impure-derivations" }, - { Xp::Flakes, "flakes" }, - { Xp::NixCommand, "nix-command" }, - { Xp::RecursiveNix, "recursive-nix" }, - { Xp::NoUrlLiterals, "no-url-literals" }, - { Xp::FetchClosure, "fetch-closure" }, - { Xp::ReplFlake, "repl-flake" }, - { Xp::AutoAllocateUids, "auto-allocate-uids" }, - { Xp::Cgroups, "cgroups" }, - { Xp::DiscardReferences, "discard-references" }, +std::map> stringifiedXpFeatures = { + { Xp::CaDerivations, {"ca-derivations", R"( + Allows derivations to be content-addressed in order to prevent rebuilds + when changes to the derivation do not result in changes to the + derivation's output. See + [__contentAddressed](../language/advanced-attributes.md#adv-attr-__contentAddressed) + for more info. + )"} }, + { Xp::ImpureDerivations, {"impure-derivations", R"( + Allows derivations to produce non-fixed outputs by setting the `__impure` + derivation attribute to `true`. See [these release + notes](../release-notes/rl-2.8.md) for an example. + )"} }, + { Xp::Flakes, {"flakes", R"( + Allows for derivations to be packaged in flakes. See the manual entry for + [`nix flake`](../command-ref/new-cli/nix3-flake.md) or this [detailed + introduction](https://www.tweag.io/blog/2020-05-25-flakes/) for more info. + )"} }, + { Xp::NixCommand, {"nix-command", R"( + Allows the usage of the new `nix` CLI subcommands, such as `nix build`, `nix + develop`, `nix run`, etc. See the manual for + [`nix`](../command-ref/new-cli/nix.md) for more info. + )"} }, + { Xp::RecursiveNix, {"recursive-nix", R"( + Allow Nix derivations to call Nix in order to recursively build derivations. + See [this + commit](https://github.com/edolstra/nix/commit/1a27aa7d64ffe6fc36cfca4d82bdf51c4d8cf717) + for more info. + )"} }, + { Xp::NoUrlLiterals, {"no-url-literals", R"( + Disallows unquoted URLs as part of the Nix language syntax. See [RFC + 45](https://github.com/NixOS/rfcs/pull/45) for more info. + )"} }, + { Xp::FetchClosure, {"fetch-closure", R"( + Enables the use of the `fetchClosure` function in the standard library. See + the docs for [`fetchClosure`](../language/builtins.md#builtins-fetchClosure) + for more info. + )"} }, + { Xp::ReplFlake, {"repl-flake", R"( + Allows the user to enter a Nix REPL within a flake, e.g. `nix repl nixpkgs` + or `nix repl .#foo`. + )"} }, + { Xp::AutoAllocateUids, {"auto-allocate-uids", R"( + Allows Nix to automatically pick UIDs for builds, rather than creating + `nixbld*` user accounts. See [here](#conf-auto-allocate-uids) for more info. + )"} }, + { Xp::Cgroups, {"cgroups", R"( + Allows Nix to execute builds inside cgroups. See + [`use-cgroups`](#conf-use-cgroups) for more info. + )"} }, + { Xp::DiscardReferences, {"discard-references", R"( + Enables the use of the `unsafeDiscardReferences` attribute in derivations + that use structured attributes. This disables scanning of outputs for + runtime dependencies. + )"} }, }; const std::optional parseExperimentalFeature(const std::string_view & name) @@ -26,8 +69,11 @@ const std::optional parseExperimentalFeature(const std::str static auto reverseXpMap = []() { auto reverseXpMap = std::make_unique(); - for (auto & [feature, name] : stringifiedXpFeatures) + std::string_view name; + for (auto & [feature, featureStringPair] : stringifiedXpFeatures) { + name = featureStringPair.first; (*reverseXpMap)[name] = feature; + } return reverseXpMap; }(); @@ -41,7 +87,24 @@ std::string_view showExperimentalFeature(const ExperimentalFeature feature) { const auto ret = get(stringifiedXpFeatures, feature); assert(ret); - return *ret; + return ret->first; +} + +std::string getExperimentalFeaturesList() { + std::string experimentalFeaturesList = R"( + Experimental Nix features to enable. + Current experimental features are the following: + +)"; + + std::string experimentalFeatureString; + for (auto& [feature, featureStringPair] : stringifiedXpFeatures) { + experimentalFeatureString = " - `" + featureStringPair.first + "`\n"; + experimentalFeatureString += featureStringPair.second + "\n\n"; + experimentalFeaturesList += experimentalFeatureString; + } + + return experimentalFeaturesList; } std::set parseFeatures(const std::set & rawFeatures) diff --git a/src/libutil/experimental-features.hh b/src/libutil/experimental-features.hh index ac372e03e..1f1852705 100644 --- a/src/libutil/experimental-features.hh +++ b/src/libutil/experimental-features.hh @@ -10,8 +10,8 @@ namespace nix { /** * The list of available experimental features. * - * If you update this, don’t forget to also change the map defining their - * string representation in the corresponding `.cc` file. + * If you update this, don’t forget to also change the map defining their string + * representation and documentation in the corresponding `.cc` file as well. **/ enum struct ExperimentalFeature { @@ -36,6 +36,7 @@ using Xp = ExperimentalFeature; const std::optional parseExperimentalFeature( const std::string_view & name); std::string_view showExperimentalFeature(const ExperimentalFeature); +std::string getExperimentalFeaturesList(); std::ostream & operator<<( std::ostream & str,