add outline for trivial builders tutorial #623
Conversation
|
|
||
| ## Assumptions | ||
|
|
||
| * The reader knows what a shell environment is. |
There was a problem hiding this comment.
clarify what you mean by shell environment - more specific?
Does it mean that they have seen shell.nix or more some familiarity with nix-shell?
| ## Assumptions | ||
|
|
||
| * The reader knows what a shell environment is. | ||
| * The reader has some familiarity with `nix-shell` |
There was a problem hiding this comment.
Anything in particular -
nix-shell -p?
(see above comment)
|
|
||
| ## Activity | ||
|
|
||
| * Start with a `shell.nix` which brings in some packages and dependencies for a `Process X` |
There was a problem hiding this comment.
more detail on process x - how can we make it more concrete? A contributor should be able to start with as few questions as possible.
| ## Steps | ||
|
|
||
| * Begin with a `shell.nix` which provides the dependencies for `Process X` | ||
| * Show the reader how to generate the config file using `writeTextFile` |
There was a problem hiding this comment.
if the config file for process x is a format that pkgs.formats is aware of, use that, otherwise writetextfile is fine.
|
|
||
| * Begin with a `shell.nix` which provides the dependencies for `Process X` | ||
| * Show the reader how to generate the config file using `writeTextFile` | ||
| * Show the reader how to take the generated config file and create a start script for `Process X` using `writeScript` |
There was a problem hiding this comment.
Is using write script intentionally running the user into problems
Skip straight to writescriptbin
| * Show the reader how to take the generated config file and create a start script for `Process X` using `writeScript` | ||
| * When they reload their shell and try to run the new script, they should see that it fails | ||
| * This is a good opportunity to introduce `writeScriptBin` and highlight how it is necessary to ensure their script is placed in `$out/bin` to be picked up by `mkShell`. | ||
| * Having created a working start script using `writeScriptBin` we point out that the generated script does not contain an interpreter: |
There was a problem hiding this comment.
It's not clear what is meant by missing interpreter. Is this a runtime dependency or something else?
| * `cat $(which start-server)` | ||
| * This is an opportunity to introduce `writeShellScriptBin` and show how the resulting script contains the interpreter with `cat $(which start-server)` | ||
| * Until now, the binary for `Process X` should have been referred to directly in the start script e.g. `${pkgs.process-x}/bin/process-x` | ||
| * We can now introduce the reader to `writeShellApplication`, providing the binary for `Process X` as a `runtimeInput` |
There was a problem hiding this comment.
why not show the reader writeshellapplication from the beginning?
Can we avoid intermediate steps?
Is there a way to use writescriptbin that isn't strictly less useful than using writeshellapplication?
| * Show how the `PATH` is being generated in the output script | ||
| * Demonstrate the inclusion of default shellopts | ||
| * Demonstrate how `shellcheck` is being applied by first encouraging the reader to try a script that will fail the check. | ||
| * To round things off, we can demonstrate the use of `symlinkJoin` to combine a few utility scripts to together into a single package. Whilst not strictly necessary for a devshell, I think it’s still worthwhile to point out |
There was a problem hiding this comment.
we think that buildenv would be the better choice here.
We cannot back this up with links in the documentation (yet).
| * Demonstrate the inclusion of default shellopts | ||
| * Demonstrate how `shellcheck` is being applied by first encouraging the reader to try a script that will fail the check. | ||
| * To round things off, we can demonstrate the use of `symlinkJoin` to combine a few utility scripts to together into a single package. Whilst not strictly necessary for a devshell, I think it’s still worthwhile to point out | ||
| * Have the reader create a `start` and `stop` `/bin/` script for `Process X` which starts in daemon mode and stops the daemon at a later point. It can be as simple as grabbing a pid and running kill. |
There was a problem hiding this comment.
Guide to a process monitor instead?
userspace process managers?
(like hivemind or process-compose openmind honcho etc.)
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2023-07-06-learning-journey-working-group-meeting-notes-16/30210/1 |
|
In light of our discussions about how these tutorials should be structured I think this just misses the mark entirely, so I'm closing it to let a fresh attempt to be made. |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2023-07-20-learning-journey-working-group-meeting-notes-18/30926/1 |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2023-07-27-learning-journey-working-group-meeting-notes-19/31151/1 |
This PR contains an outline for #602