Reworked Getting started guide #1012
Conversation
| 1. Import dream2nix and tell nix to use whatever version of nixpkgs dream2nix declares. You can use other versions, but this it what we run our automated tests with. | ||
| 2. Define a helper function that allows us to reduce boilerplate and still support all of of the listed systems for our package. | ||
| 3. Create our package, called `hello` here, by *evaluating* the given dream2nix [modules](../modules.md). | ||
| 4. Pass the given instance of nixpkgs to build our package with as a *module argument*. | ||
| 5. Include our package definition from `hello.nix`. See below for its contents! | ||
| 6. Define relative paths to aid dream2nix to find lock files and so on during *evaluation time*. These settings should work for repos containing multiple python projects as simpler ones. | ||
| 7. We declare `hello` to be the default package. This allows us to just call i.e. `nix build .#` instead of `nix build .#hello`. |
There was a problem hiding this comment.
Should these be inlined instead of referenced?
There was a problem hiding this comment.
After rendering via mkdocs those get inlined.
Try:
nix build .#website
python3 -m http.server -d ./result
There was a problem hiding this comment.
As regular comments? I tried both and found this to be a bit nicer in context, but don't know. Maybe newer users would tend to read it linearly from top to bottom anyway.
There was a problem hiding this comment.
I really like how much of the information is hidden behind clickable tooltips. It makes the guide short and concise. I wonder if we should have a hint at the beginning of the document telling the user to click on the plus icons to discover more. It took me a while to find that out.
| # (4) | ||
| # deps = {nixpkgs, ...}: { | ||
| # inherit | ||
| # (nixpkgs) | ||
| # stdenv | ||
| # ; | ||
| # }; |
There was a problem hiding this comment.
Maybe remove this for now? The deps concept could still be introduced in another guide.
Also I'm not even sure if we should keep deps, or if we better just provide access to pkgs. The user can still use overlays to override deps etc.
There was a problem hiding this comment.
Yeah, same applies for the lock mention. I'd suggest moving it into a modules guide when thats done :)
|
Merging this for now, going to remove the deps example later on. Think it's useful to show the rendered annotations, as that caused confusion earlier in the thread here. |
Our getting started guide previously mostly showed a template but didn't explain too much what's happening. I tried to improve that using code annotations.
Happy for any feedback, especially from people who do not have too much experience with nix & dream2nix yet as you are the target audience :)
I am also working on a Python & Pip guide, hope to push that one soonish.