From c51c4971defcbca0f2967d9663f9a1c029f37c4e Mon Sep 17 00:00:00 2001
From: mitchmindtree <mitchell.nordine@gmail.com>
Date: Sun, 21 Jan 2024 19:24:19 +1100
Subject: [PATCH] Add contributing.md chapter on Nix

---
 guide/src/contributing.md           |  1 +
 guide/src/contributing/nix-shell.md | 54 +++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)
 create mode 100644 guide/src/contributing/nix-shell.md

diff --git a/guide/src/contributing.md b/guide/src/contributing.md
index df85a518d..eb74fc360 100644
--- a/guide/src/contributing.md
+++ b/guide/src/contributing.md
@@ -7,6 +7,7 @@ you in the right direction.
 - [**PR Checklist**](./contributing/pr-checklist.md)
 - [**PR Reviews**](./contributing/pr-reviews.md)
 - [**Publishing New Versions**](./contributing/publishing-new-versions.md)
+- [**Nix Shell**](./contributing/nix-shell.md)
 
 ## Still have questions?
 
diff --git a/guide/src/contributing/nix-shell.md b/guide/src/contributing/nix-shell.md
new file mode 100644
index 000000000..27c5bf428
--- /dev/null
+++ b/guide/src/contributing/nix-shell.md
@@ -0,0 +1,54 @@
+# Nix Shell
+
+The nannou repo offers a Nix shell as a way of providing a reproducible
+environment across both macOS and Linux. This simplifies the nannou repo CI a
+little while making it easier to experiment with nannou using a known working
+environment.
+
+### Installing Nix
+
+The [Determinate Systems installer](https://github.com/DeterminateSystems/nix-installer)
+is one of the easiest ways to get started with Nix.
+
+### Nannou's Nix Files
+
+- **default.nix** - A derivation that describes how to build the nannou Rust
+  package, including all of its examples and with all of the necessary environment
+  variables. This is what is built by default when running `nix build`. When
+- **shell.nix** - A derivation that describes a development shell providing all
+  of the necessary system dependencies and environment variables for working on
+  nannou and its examples.
+- **flake.nix** - A Nix manifest standard declaring the `nannou` package and
+  devShell.
+
+### Adding a `nannou` Dependency
+
+When adding a new package (e.g. system dependency):
+
+1. Find the package in nixpkgs (`nix search nixpkgs <name>` is handy)
+2. Add the package to the `default.nix` input attribute set.
+3. Add the package to `buildInputs` if its a runtime dependency, or
+   `nativeBuildInputs` if its a build-time dependency.
+
+### Adding a Development Shell Dependency
+
+To add handy development dependencies (e.g. rustfmt, rust-analyser), do the same
+but add them to `shell.nix` instead.
+
+### Adding Environment Variables
+
+Add these to the `env` attributes within either `default.nix` or `shell.nix`.
+
+### Build Everything
+
+Build all binaries, examples and dylibs within the `nannou` workspace with
+`nix build`. When finished, look in the `result` symlink directory to find all
+of the built binaries.
+
+### Enter a nannou `devShell`
+
+To enter a development shell with all of the tools and env vars necessary for
+nannou dev, use `nix develop`.
+
+To quickly enter a nannou dev shell to build a downstream nannou project, you
+can use: `nix develop github:nannou-org/nannou`.