This Draft of an RFC could be the first step to improve how nix is used as a language.
🚧 🚧 Any help welcome! 🚧 🚧
A very large set of doc-strings is already available in nixpkgs.
But they don't follow strict conventions and thus it is very hard to write a parser for them. There is highly valuable information inside them:
Example:
| Required | Attribute | Type | Default | Description |
|---|---|---|---|---|
| ✅ | name | String | The name of the Derivation |
|
| ❓ | builder | String | "setup.sh" | Uses the predefined setup.sh script. Usually you want to define scripts for the different phases. |
| ❓ | buildInputs | List[Derivation] | List of Packages needed inside the build-sandbox of this Derivation. Will be built beforehand and made available in $PATH of that build. e.g python is needed for python command executed during build time. |
|
| ❓ | buildPhase | String | String is interpreted and executed as bash script. Use magic quotes '' {script} '' for multiline scripts. It is important that all outputs defined in the outputs attribute are generated e.g. touch $out |
|
| ❓ | outputs | List[String] | ["out"] | List of outputs. All outputs must have been touched / generated after the build time. Every output is available as env variable e.g. $out |
Defined in: pkgs/stdenv/generic/make-derivation.nix
The full content is available as mdbook here.
The current documentation as well as some other external tools have generated content from that inline comments. Thus it is highly desirable to standardize and enhance them.