The Learning Journey Working Group is starting a work process in which we focus on a small number of tutorials for a month so that we can get them into a state that contributors can pick them up and work on them as soon as possible.
Part of that process is acknowledging that the small number of people in the working group, who are mostly Nix beginners wanting to make it easier for other beginners to learn Nix, don’t know all the ins and outs of the Nix ecosystem or where the pitfalls are.
We’d like to leverage the community of experts and anyone else willing to pitch in.
Going forward we’ll solicit feedback and suggestions each month for the tutorials we’ve selected for development.
This is the first time we’re trying this so I’m sure there will be some trial and error and growing pains.
How you can help
Suggest activities
For each of these tutorials we’d like the user to walk through some activity that will put them into contact with the topic of the tutorial.
We’ll have some ideas of activities users can walk through on their own, but more suggestions at this stage of the process will always be better.
So, the first thing you can do is provide suggestions for activities that users can do on a particular topic.
Where do users get stuck?
The next thing you can do is provide us with insight into where users get stuck on these topics.
Even if all of us in the Working Group were experts, we don’t know everyone using Nix, and we certainly don’t know where everyone gets stuck.
If you have experience helping users with these topics, please point out the major pain points or stumbling blocks.
Make us aware of the traps
Anyone who has ever used a computer has had the “how hard could it be” experience that turns into a rabbit hole of complexity.
If you know that a particular topic we’ve chosen has hidden complexities, we’d like to hear about them so that we can keep the reader on a happy path until we intentionally decide to present any complexities.
For example, if you bring python310 and python310Packages.pip into a nix-shell -p environment, you can’t just install Python packages with pip install like you would outside of a Nix shell.
The tutorial ideas
Feel free to leave comments either on the GitHub issues linked below or in this thread.
Sharing dependencies between default.nix and shell.nix
The idea here is that we’d like to demonstrate how to set up a development environment, which means bringing packages into the shell other than those that are strictly part of the build.
One idea here is to take a project with a working default.nix that simply builds the project, duplicate the dependencies to shell.nix, then show how you can share the dependencies between shell.nix and default.nix via the inputsFrom attribute passed to mkShell.
Questions:
-
What kind of project should the user build?
-
Which other tools should the user bring into the shell? Examples could be linters, formatters, etc.
-
Anything we should watch out for?
-
Any best practices in this regard?
Packaging existing software
This is a big topic, but what we want to teach in this tutorial is the workflow, not necessarily every possible way to package existing software.
It’s common to have be missing dependencies that you didn’t know that you had, so we want to show users how to figure which ones they’re missing, where to find the packages they’re looking for, etc.
Also, it’s common for header files to be under a mypkg.dev attribute, so we’d like to make users aware of that as well.
One idea here is to take a working project that may have language-level dependencies (e.g. Rust crates, Python modules, etc), but also some system dependencies.
For example, if you want to use a library that wraps libcurl you’ll need to bring libcurl into your build even though you might only directly depend on a Python module called easy_curl (made up arbitrary package name).
Questions:
-
What kind of project should the user work on that would allow them to focus on the Nix aspects and not on the particularities of the language?
-
Are there common workflows you use to track down why your build is failing?
-
Can you think of a project that requires a variety of different methods to get it working e.g. requires more than “I’m missing
foo, add packagefoo”?
Trivial builders
Sometimes you don’t need the full Nix machinery of building and compiling an application.
Sometimes it’s fine to run a few commands and just make sure something is in $out by the time you’re done.
This is the use case for trivial builders that we’d like to demonstrate.
One idea is to build up a shell application starting from writeTextFile and manually put it in a /bin directory and make it executable, then show how you can accomplish the same task by using writeScriptBin or writeShellApplication.
Some really valuable feedback here would be use cases where you’ve done this yourself to solve a problem or accomplish a specific goal e.g. what can we show the user here that would be useful?
mkDerivation phases
Derivations can be broken down into various phases, and if you know the contract for each phase or when they run relative to one another you can better mold a derivation to suit your needs.
What we’d like to show the user here is how to use some of the more commonly overridden phases to solve their problems.
One idea could be to have the user build their own builder for a particular language, showing how the builder in nixpkgs implements each of the phases to handle the particularities of that language’s build process.
One pitfall in that example is that it could lead the user to focus too much on the language and less on the Nix aspects.
Questions:
-
Which phases would you focus on?
-
What are some use cases for specifying the phases manually?