This project illustrates using the Nix package manager for programming heterogeneous, multi-module projects. Notably, it provides a Nix library called Pkgs-make to save some the boilerplate we might have to write when using Nix for managing a software lifecycle. Pkgs-make currently directly supports Haskell and Python development, but has the potential to support other language platforms.
Use this project to learn and explore what's possible. It's set up for pedagogy, but you should be able to use Pkgs-make in real projects (a group of us does). There are many ways to organize code, and the beauty of Nix is that it's very flexible. So use Pkgs-make if you can, but be aware that there's many ways to achieve the same goal, and your needs will determine what's best.
We've tried hard to keep the code clean and self-documenting. Here's a survey of the project's layout with some links, each with their own README files explaining more:
| File/Directory | Description |
|---|---|
| tutorials/0-nix-intro/ | tutorial of basic Nix usage |
| tutorials/1-pkgs-make/ | tutorial of basic Pkgs-make usage |
| tutorials/2-haskell/ | tutorial of Haskell example using Pkgs-make |
| tutorials/2-python/ | tutorial of Python example using Pkgs-make |
| tools/ | tool configuration for a nice developer experience |
| run/ | scripts to illustrate this project |
| pkgs-make/ | Pkgs-make, the Nix library driving this project |
The links are presented in loose recommended reading order, starting with tutorials on usage, and ending with the implementation of Pkgs-make. If you don't know what Nix is or the motivation to use it over the alternatives, the first tutorial is a good place to start.
If you don't have a preferred Markdown or Org-mode viewer, we recommend just using Github's Markdown rendering at https://github.com/shajra/example-nix.
We've tried to make this project explanatory enough that you don't need to read external references first. But covering Nix in its entirety is beyond the scope of this project, so it's really good to have the official documentation available for reference:
There are also many good tutorials. Here are few that some of us have found useful personally:
Because this project is really about Nix, you should have the Nix package manager installed.
Unless you're running NixOS as your operating system (which provides Nix intrinsically) the primary way to install Nix on another operating system is by running Nix's install script:
curl https://nixos.org/nix/install | shAlso, be aware that this project is actively tested on a GNU/Linux OS, and only loosely tested on Macs. Nix support for Macs is always improving, but is known to be idiosyncratic.
If for some reason you can't install Nix, we can still use Docker to build some of the projects in the tutorials. We just won't be able to showcase development tools without Nix installed on the host system.
This project illustrates how to build and package up applications in Docker.
See the Docker installation guide for instructions on how to install Docker for your system.
This project also provides some configuration for some developers tools for a nice Nix-based developer experience with this project. Some of us have used these tools on real projects, and we've been pleased with the results.
Beyond Docker and these developer tools, you don't need to install language-specific tooling like interpreters/compilers, build systems, or static analysis tools.
Once you have Nix, we can use it as a bootstrap to get all the other tools you might need that are more likely to vary from project to project. Pkgs-make can help with this.
If you have an idea to improve this project's documentation or features, please submit an issue or pull request. Otherwise, feel free to fork/modify it.
This repository has been around for a few years, but we've not yet officially released it to allow it some time to get some heavier refactoring. If you're please interested, please leave an issue suggesting so, and we can take the necessary steps.