doc: improve documentation for writeText* functions #277171
Conversation
|
Suggested improvements at https://gist.github.com/mcdonc/978487ae51fa1cf4d305bbebcdf40f86 |
ofborg
bot
added
10.rebuild-darwin: 0
| Note that the output of `writeText` is a derivation, which will coerce to the store path of its output, | ||
| which will not match the path of the actual file if `destination` is set. | ||
|
|
||
| Many more functions wrap `writeTextFile`, including `writeText`, `writeTextDir`, `writeScript`, and `writeScriptBin`. |
There was a problem hiding this comment.
I know this is already like this in the manual, but instead of including, could we list them all?
There was a problem hiding this comment.
Oh no! This documentation has been duplicated across
doc/build-helpers/trivial-build-helpers.chapter.md, andpkgs/build-support/trivial-builders/default.nix
We should either use nixdoc (like lib/), or replace all the doc comments by # See doc/build-helpers/trivial-build-helpers.chapter.md.
There's no point doing anything without addressing this duplication first.
There was a problem hiding this comment.
There's no point doing anything without addressing this duplication first.
Maybe I should tone that down, but it is a very very serious problem nonetheless.
There was a problem hiding this comment.
As much as I don't want to throw this over the fence, I'm not sure I have it in me right now to handle a large scale cleanup like this. If anyone's interested, feel free to take over.
| destination = "some/subpath/my-cool-script"; | ||
|
|
||
| # (Optional) Commands to run after generating the file, e.g. lints. | ||
| # Defaults to ""; |
There was a problem hiding this comment.
| # Defaults to ""; | |
| # Defaults to "". |
| # (Optional) Commands to run after generating the file, e.g. lints. | ||
| # Defaults to ""; | ||
| checkPhase = '' | ||
| ${pkgs.shellcheck}/bin/shellcheck $out/some/subpath/my-cool-script |
There was a problem hiding this comment.
Can we use destination here to avoid duplication?
There was a problem hiding this comment.
Make sure to test it if you do.
|
|
||
| # (Optional) Whether to prefer building locally, even if faster remote builders are available. | ||
| # Defaults to true for similar reasons. | ||
| preferLocalBuild = false; |
There was a problem hiding this comment.
So does this take precedence on the above, so that if e.g. allowSubstitutes = true && preferLocalBuild = true, the build is kept local?
There was a problem hiding this comment.
This should refer to the Nix manual and not copy the explanation.
It may be subject to change and documenting it here would suggest that it's unique.
| ``` | ||
|
|
||
| Note that the output of `writeText` is a derivation, which will coerce to the store path of its output, | ||
| which will not match the path of the actual file if `destination` is set. |
There was a problem hiding this comment.
An example could be nice here IMO.
There was a problem hiding this comment.
Description of changes
Things done
nix.conf? (See Nix manual)sandbox = relaxedsandbox = truenix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage./result/bin/)Add a 👍 reaction to pull requests you find important.