Flake schemas

doc/manual/source/SUMMARY.md.in

@@ -118,6 +118,7 @@
   - [Store Path Specification](protocols/store-path.md)
   - [Nix Archive (NAR) Format](protocols/nix-archive.md)
   - [Derivation "ATerm" file format](protocols/derivation-aterm.md)
+  - [Flake Schemas](protocols/flake-schemas.md)
 - [C API](c-api.md)
 - [Glossary](glossary.md)
 - [Development](development/index.md)

doc/manual/source/protocols/flake-schemas.md

@@ -0,0 +1,64 @@
+# Flake Schemas
+
+Flake schemas are a mechanism to allow tools like `nix flake show` and `nix flake check` to enumerate and check the contents of a flake
+in a generic way, without requiring built-in knowledge of specific flake output types like `packages` or `nixosConfigurations`.
+
+A flake can define schemas for its outputs by defining a `schemas` output. `schemas` should be an attribute set with an attribute for
+every output type that you want to be supported. If a flake does not have a `schemas` attribute, Nix uses a built-in set of schemas (namely https://github.com/DeterminateSystems/flake-schemas).
+
+A schema is an attribute set with the following attributes:
+
+| Attribute   | Description                                                                                     | Default |
+| :---------- | :---------------------------------------------------------------------------------------------- | :------ |
+| `version`   | Should be set to 1                                                                              |         |
+| `doc`       | A string containing documentation about the flake output type in Markdown format.               |         |
+| `allowIFD`  | Whether the evaluation of the output attributes of this flake can read from derivation outputs. | `true`  |
+| `inventory` | A function that returns the contents of the flake output (described [below](#inventory)).       |         |
+
+# Inventory
+
+The `inventory` function returns a _node_ describing the contents of the flake output. A node is either a _leaf node_ or a _non-leaf node_. This allows nested flake output attributes to be described (e.g. `x86_64-linux.hello` inside a `packages` output).
+
+Non-leaf nodes must have the following attribute:
+
+| Attribute  | Description                                                                            |
+| :--------- | :------------------------------------------------------------------------------------- |
+| `children` | An attribute set of nodes. If this attribute is missing, the attribute is a leaf node. |
+
+Leaf nodes can have the following attributes:
+
+| Attribute          | Description                                                                                                                                                                                      |
+| :----------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `derivation`       | The main derivation of this node, if any. It must evaluate for `nix flake check` and `nix flake show` to succeed.                                                                                |
+| `evalChecks`       | An attribute set of Boolean values, used by `nix flake check`. Each attribute must evaluate to `true`.                                                                                           |
+| `isFlakeCheck`     | Whether `nix flake check` should build the `derivation` attribute of this node.                                                                                                                  |
+| `shortDescription` | A one-sentence description of the node (such as the `meta.description` attribute in Nixpkgs).                                                                                                    |
+| `what`             | A brief human-readable string describing the type of the node, e.g. `"package"` or `"development environment"`. This is used by tools like `nix flake show` to describe the contents of a flake. |
+
+Both leaf and non-leaf nodes can have the following attributes:
+
+| Attribute    | Description                                                                                                                                                                                                                                                                                                                                            |
+| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `forSystems` | A list of Nix system types (e.g. `["x86_64-linux"]`) supported by this node. This is used by tools to skip nodes that cannot be built on the user's system. Setting this on a non-leaf node allows all the children to be skipped, regardless of the `forSystems` attributes of the children. If this attribute is not set, the node is never skipped. |
+
+# Example
+
+Here is a schema that checks that every element of the `nixosConfigurations` flake output evaluates and builds correctly (meaning that it has a `config.system.build.toplevel` attribute that yields a buildable derivation).
+
+```nix
+outputs = {
+  schemas.nixosConfigurations = {
+    version = 1;
+    doc = ''
+      The `nixosConfigurations` flake output defines NixOS system configurations.
+    '';
+    inventory = output: {
+      children = builtins.mapAttrs (configName: machine:
+        {
+          what = "NixOS configuration";
+          derivation = machine.config.system.build.toplevel;
+        }) output;
+    };
+  };
+};
+```

src/libcmd/installables.cc

@@ -454,11 +454,6 @@ ref<eval_cache::EvalCache> openEvalCache(
         : std::nullopt;
     auto rootLoader = [&state, lockedFlake]()
         {
-            /* For testing whether the evaluation cache is
-               complete. */
-            if (getEnv("NIX_ALLOW_EVAL").value_or("1") == "0")
-                throw Error("not everything is cached, but evaluation is not allowed");
-
             auto vFlake = state.allocValue();
             flake::callFlake(state, *lockedFlake, *vFlake);
 

src/libexpr/eval-cache.cc

@@ -370,6 +370,12 @@ Value * EvalCache::getRootValue()
 {
     if (!value) {
         debug("getting root value");
+
+        /* For testing whether the evaluation cache is
+           complete. */
+        if (getEnv("NIX_ALLOW_EVAL").value_or("1") == "0")
+            throw Error("not everything is cached, but evaluation is not allowed");
+
         value = allocRootValue(rootLoader());
     }
     return *value;

src/libexpr/eval-cache.hh

@@ -34,7 +34,11 @@ class EvalCache : public std::enable_shared_from_this<EvalCache>
     friend struct CachedEvalError;
 
     std::shared_ptr<AttrDb> db;
+
+public:
     EvalState & state;
+
+private:
     typedef std::function<Value *()> RootLoader;
     RootLoader rootLoader;
     RootValue value;
@@ -89,7 +93,10 @@ class AttrCursor : public std::enable_shared_from_this<AttrCursor>
     friend class EvalCache;
     friend struct CachedEvalError;
 
+public:
     ref<EvalCache> root;
+
+private:
     typedef std::optional<std::pair<std::shared_ptr<AttrCursor>, Symbol>> Parent;
     Parent parent;
     RootValue _value;

src/libflake/flake/flake.cc

@@ -270,7 +270,7 @@ static std::pair<std::map<FlakeId, FlakeInput>, fetchers::Attrs> parseFlakeInput
     return {inputs, selfAttrs};
 }
 
-static Flake readFlake(
+Flake readFlake(
     EvalState & state,
     const FlakeRef & originalRef,
     const FlakeRef & resolvedRef,
@@ -441,22 +441,18 @@ static LockFile readLockFile(
         : LockFile();
 }
 
-/* Compute an in-memory lock file for the specified top-level flake,
-   and optionally write it to file, if the flake is writable. */
 LockedFlake lockFlake(
     const Settings & settings,
     EvalState & state,
     const FlakeRef & topRef,
-    const LockFlags & lockFlags)
+    const LockFlags & lockFlags,
+    Flake flake,
+    FlakeCache & flakeCache)
 {
     experimentalFeatureSettings.require(Xp::Flakes);
 
-    FlakeCache flakeCache;
-
     auto useRegistries = lockFlags.useRegistries.value_or(settings.useRegistries);
 
-    auto flake = getFlake(state, topRef, useRegistries, flakeCache, {});
-
     if (lockFlags.applyNixConfig) {
         flake.config.apply(settings);
         state.store->setOptions();
@@ -921,6 +917,30 @@ LockedFlake lockFlake(
     }
 }
 
+LockedFlake lockFlake(
+    const Settings & settings,
+    EvalState & state,
+    const FlakeRef & topRef,
+    const LockFlags & lockFlags)
+{
+    FlakeCache flakeCache;
+
+    auto useRegistries = lockFlags.useRegistries.value_or(settings.useRegistries);
+
+    return lockFlake(settings, state, topRef, lockFlags, getFlake(state, topRef, useRegistries, flakeCache, {}), flakeCache);
+}
+
+LockedFlake lockFlake(
+    const Settings & settings,
+    EvalState & state,
+    const FlakeRef & topRef,
+    const LockFlags & lockFlags,
+    Flake flake)
+{
+    FlakeCache flakeCache;
+    return lockFlake(settings, state, topRef, lockFlags, std::move(flake), flakeCache);
+}
+
 void callFlake(EvalState & state,
     const LockedFlake & lockedFlake,
     Value & vRes)

src/libflake/flake/flake.hh

@@ -223,12 +223,35 @@ struct LockFlags
     std::set<InputAttrPath> inputUpdates;
 };
 
+/**
+ * Return a `Flake` object representing the flake read from the
+ * `flake.nix` file in `rootDir`.
+ */
+Flake readFlake(
+    EvalState & state,
+    const FlakeRef & originalRef,
+    const FlakeRef & resolvedRef,
+    const FlakeRef & lockedRef,
+    const SourcePath & rootDir,
+    const InputAttrPath & lockRootPath);
+
+/**
+ * Compute an in-memory lock file for the specified top-level flake,
+ * and optionally write it to file, if the flake is writable.
+ */
 LockedFlake lockFlake(
     const Settings & settings,
     EvalState & state,
     const FlakeRef & flakeRef,
     const LockFlags & lockFlags);
 
+LockedFlake lockFlake(
+    const Settings & settings,
+    EvalState & state,
+    const FlakeRef & topRef,
+    const LockFlags & lockFlags,
+    Flake flake);
+
 void callFlake(
     EvalState & state,
     const LockedFlake & lockedFlake,