Merge pull request #8196 from obsidiansystems/fix-8162

Mark experimental configuration settings programmatically

doc/manual/generate-manpage.nix

@@ -31,19 +31,18 @@ let
 
       showSynopsis = command: args:
         let
-          showArgument = arg: "*${arg.label}*" + (if arg ? arity then "" else "...");
+          showArgument = arg: "*${arg.label}*" + optionalString (! arg ? arity) "...";
           arguments = concatStringsSep " " (map showArgument args);
         in ''
          `${command}` [*option*...] ${arguments}
         '';
 
-      maybeSubcommands = if details ? commands && details.commands != {}
-        then ''
+      maybeSubcommands = optionalString (details ? commands && details.commands != {})
+         ''
            where *subcommand* is one of the following:
 
            ${subcommands}
-         ''
-        else "";
+         '';
 
       subcommands = if length categories > 1
         then listCategories
@@ -65,12 +64,11 @@ let
         * [`${command} ${name}`](./${appendName filename name}.md) - ${subcmd.description}
       '';
 
-      maybeDocumentation =
-        if details ? doc
-        then replaceStrings ["@stores@"] [storeDocs] details.doc
-        else "";
+      maybeDocumentation = optionalString
+        (details ? doc)
+        (replaceStrings ["@stores@"] [storeDocs] details.doc);
 
-      maybeOptions = if details.flags == {} then "" else ''
+      maybeOptions = optionalString (details.flags != {}) ''
         # Options
 
         ${showOptions details.flags toplevel.flags}
@@ -80,15 +78,19 @@ let
         let
           allOptions = options // commonOptions;
           showCategory = cat: ''
-            ${if cat != "" then "**${cat}:**" else ""}
+            ${optionalString (cat != "") "**${cat}:**"}
 
             ${listOptions (filterAttrs (n: v: v.category == cat) allOptions)}
             '';
           listOptions = opts: concatStringsSep "\n" (attrValues (mapAttrs showOption opts));
           showOption = name: option:
             let
-              shortName = if option ? shortName then "/ `-${option.shortName}`" else "";
-              labels = if option ? labels then (concatStringsSep " " (map (s: "*${s}*") option.labels)) else "";
+              shortName = optionalString
+                (option ? shortName)
+                ("/ `-${option.shortName}`");
+              labels = optionalString
+                (option ? labels)
+                (concatStringsSep " " (map (s: "*${s}*") option.labels));
             in trim ''
               - `--${name}` ${shortName} ${labels}
 

doc/manual/utils.nix

@@ -42,7 +42,9 @@ rec {
   filterAttrs = pred: set:
     listToAttrs (concatMap (name: let v = set.${name}; in if pred name v then [(nameValuePair name v)] else []) (attrNames set));
 
-  showSetting = { useAnchors }: name: { description, documentDefault, defaultValue, aliases, value }:
+  optionalString = cond: string: if cond then string else "";
+
+  showSetting = { useAnchors }: name: { description, documentDefault, defaultValue, aliases, value, experimentalFeature }:
     let
       result = squash ''
           - ${if useAnchors
@@ -52,10 +54,28 @@ rec {
           ${indent "  " body}
         '';
 
+      experimentalFeatureNote = optionalString (experimentalFeature != null) ''
+          > **Warning**
+          > This setting is part of an
+          > [experimental feature](@docroot@/contributing/experimental-features.md).
+
+          To change this setting, you need to make sure the corresponding experimental feature,
+          [`${experimentalFeature}`](@docroot@/contributing/experimental-features.md#xp-feature-${experimentalFeature}),
+          is enabled.
+          For example, include the following in [`nix.conf`](#):
+
+          ```
+          extra-experimental-features = ${experimentalFeature}
+          ${name} = ...
+          ```
+        '';
+
       # separate body to cleanly handle indentation
       body = ''
           ${description}
 
+          ${experimentalFeatureNote}
+
           **Default:** ${showDefault documentDefault defaultValue}
 
           ${showAliases aliases}
@@ -74,7 +94,7 @@ rec {
         else "*machine-specific*";
 
       showAliases = aliases:
-          if aliases == [] then "" else
+          optionalString (aliases != [])
             "**Deprecated alias:** ${(concatStringsSep ", " (map (s: "`${s}`") aliases))}";
 
     in result;

src/libstore/globals.hh

@@ -328,16 +328,6 @@ public:
           users in `build-users-group`.
 
           UIDs are allocated starting at 872415232 (0x34000000) on Linux and 56930 on macOS.
-
-          > **Warning**
-          > This is an experimental feature.
-
-          To enable it, add the following to [`nix.conf`](#):
-
-          ```
-          extra-experimental-features = auto-allocate-uids
-          auto-allocate-uids = true
-          ```
         )"};
 
     Setting<uint32_t> startId{this,
@@ -367,16 +357,6 @@ public:
 
           Cgroups are required and enabled automatically for derivations
           that require the `uid-range` system feature.
-
-          > **Warning**
-          > This is an experimental feature.
-
-          To enable it, add the following to [`nix.conf`](#):
-
-          ```
-          extra-experimental-features = cgroups
-          use-cgroups = true
-          ```
         )"};
     #endif
 

src/libutil/config.cc

@@ -191,6 +191,10 @@ std::map<std::string, nlohmann::json> AbstractSetting::toJSONObject()
     std::map<std::string, nlohmann::json> obj;
     obj.emplace("description", description);
     obj.emplace("aliases", aliases);
+    if (experimentalFeature)
+        obj.emplace("experimentalFeature", *experimentalFeature);
+    else
+        obj.emplace("experimentalFeature", nullptr);
     return obj;
 }
 

src/libutil/tests/config.cc

@@ -156,12 +156,54 @@ namespace nix {
     }
 
     TEST(Config, toJSONOnNonEmptyConfig) {
+        using nlohmann::literals::operator "" _json;
         Config config;
-        std::map<std::string, Config::SettingInfo> settings;
-        Setting<std::string> setting{&config, "", "name-of-the-setting", "description"};
+        Setting<std::string> setting{
+            &config,
+            "",
+            "name-of-the-setting",
+            "description",
+        };
         setting.assign("value");
 
-        ASSERT_EQ(config.toJSON().dump(), R"#({"name-of-the-setting":{"aliases":[],"defaultValue":"","description":"description\n","documentDefault":true,"value":"value"}})#");
+        ASSERT_EQ(config.toJSON(),
+          R"#({
+            "name-of-the-setting": {
+              "aliases": [],
+              "defaultValue": "",
+              "description": "description\n",
+              "documentDefault": true,
+              "value": "value",
+              "experimentalFeature": null
+            }
+          })#"_json);
+    }
+
+    TEST(Config, toJSONOnNonEmptyConfigWithExperimentalSetting) {
+        using nlohmann::literals::operator "" _json;
+        Config config;
+        Setting<std::string> setting{
+            &config,
+            "",
+            "name-of-the-setting",
+            "description",
+            {},
+            true,
+            Xp::Flakes,
+        };
+        setting.assign("value");
+
+        ASSERT_EQ(config.toJSON(),
+          R"#({
+            "name-of-the-setting": {
+              "aliases": [],
+              "defaultValue": "",
+              "description": "description\n",
+              "documentDefault": true,
+              "value": "value",
+              "experimentalFeature": "flakes"
+            }
+          })#"_json);
     }
 
     TEST(Config, setSettingAlias) {