Skip to content

Commit

Permalink
Use Markdown tables for config
Browse files Browse the repository at this point in the history
  • Loading branch information
@lucperkins @edolstra
lucperkins authored and edolstra committed Jul 12, 2024
1 parent 7420b5f commit d506779
Showing 1 changed file with 20 additions and 16 deletions.
36 changes: 20 additions & 16 deletions doc/manual/src/protocols/flake-schemas.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,34 +8,38 @@ every output type that you want to be supported. If a flake does not have a `sch

A schema is an attribute set with the following attributes:

* `version`: Should be set to 1.
* `doc`: A string containing documentation about the flake output type in Markdown format.
* `allowIFD` (defaults to `true`): Whether the evaluation of the output attributes of this flake can read from derivation outputs.
* `inventory`: A function that returns the contents of the flake output (described below).
| 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).
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:

* `children`: An attribute set of nodes. If this attribute is missing, the attribute if a leaf node.
| 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:

* `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.
| 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:

* `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.
| 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

Expand Down

0 comments on commit d506779

Please sign in to comment.