docs: document issue with direnv and nix-shell on macOS (#15990) (#16015)

EdwardAngert · paulroub · web-flow · commit 761a19663f70 · 2025-01-02T14:55:59.000-05:00
- @paulroub's contribution to `CONTRIBUTING.md` adds a workaround and a link to the direnv issue - some editing to the format/layout of the doc --------- Co-authored-by: Paul Roub <paul@roub.net>
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -2,51 +2,61 @@
 
 ## Requirements
 
-We recommend using the [Nix](https://nix.dev/) package manager as it makes any
-pain related to maintaining dependency versions
-[disappear](https://nixos.org/guides/how-nix-works). Once nix
-[has been installed](https://nixos.org/download.html) the development
-environment can be _manually instantiated_ through the `nix-shell` command:
+<div class="tabs">
 
-```shell
-cd ~/code/coder
+We recommend that you use [Nix](https://nix.dev/) package manager to
+[maintain dependency versions](https://nixos.org/guides/how-nix-works).
 
-# https://nix.dev/tutorials/declarative-and-reproducible-developer-environments
-nix-shell
+### Nix
 
-...
-copying path '/nix/store/3ms6cs5210n8vfb5a7jkdvzrzdagqzbp-iana-etc-20210225' from 'https://cache.nixos.org'...
-copying path '/nix/store/dxg5aijpyy36clz05wjsyk90gqcdzbam-iana-etc-20220520' from 'https://cache.nixos.org'...
-copying path '/nix/store/v2gvj8whv241nj4lzha3flq8pnllcmvv-ignore-5.2.0.tgz' from 'https://cache.nixos.org'...
-...
-```
+1. [Install Nix](https://nix.dev/install-nix#install-nix)
 
-If [direnv](https://direnv.net/) is installed and the
-[hooks are configured](https://direnv.net/docs/hook.html) then the development
-environment can be _automatically instantiated_ by creating the following
-`.envrc`, thus removing the need to run `nix-shell` by hand!
+1. After you've installed Nix, instantiate the development with the `nix-shell`
+   command:
 
-```shell
-cd ~/code/coder
-echo "use nix" >.envrc
-direnv allow
-```
+   ```shell
+   cd ~/code/coder
 
-Now, whenever you enter the project folder,
-[`direnv`](https://direnv.net/docs/hook.html) will prepare the environment for
-you:
+   # https://nix.dev/tutorials/declarative-and-reproducible-developer-environments
+   nix-shell
 
-```shell
-cd ~/code/coder
+   ...
+   copying path '/nix/store/3ms6cs5210n8vfb5a7jkdvzrzdagqzbp-iana-etc-20210225' from 'https://   cache.nixos.org'...
+   copying path '/nix/store/dxg5aijpyy36clz05wjsyk90gqcdzbam-iana-etc-20220520' from 'https://   cache.nixos.org'...
+   copying path '/nix/store/v2gvj8whv241nj4lzha3flq8pnllcmvv-ignore-5.2.0.tgz' from 'https://cache.   nixos.org'...
+   ...
+   ```
 
-direnv: loading ~/code/coder/.envrc
-direnv: using nix
-direnv: export +AR +AS +CC +CONFIG_SHELL +CXX +HOST_PATH +IN_NIX_SHELL +LD +NIX_BINTOOLS +NIX_BINTOOLS_WRAPPER_TARGET_HOST_x86_64_unknown_linux_gnu +NIX_BUILD_CORES +NIX_BUILD_TOP +NIX_CC +NIX_CC_WRAPPER_TARGET_HOST_x86_64_unknown_linux_gnu +NIX_CFLAGS_COMPILE +NIX_ENFORCE_NO_NATIVE +NIX_HARDENING_ENABLE +NIX_INDENT_MAKE +NIX_LDFLAGS +NIX_STORE +NM +NODE_PATH +OBJCOPY +OBJDUMP +RANLIB +READELF +SIZE +SOURCE_DATE_EPOCH +STRINGS +STRIP +TEMP +TEMPDIR +TMP +TMPDIR +XDG_DATA_DIRS +buildInputs +buildPhase +builder +cmakeFlags +configureFlags +depsBuildBuild +depsBuildBuildPropagated +depsBuildTarget +depsBuildTargetPropagated +depsHostHost +depsHostHostPropagated +depsTargetTarget +depsTargetTargetPropagated +doCheck +doInstallCheck +mesonFlags +name +nativeBuildInputs +out +outputs +patches +phases +propagatedBuildInputs +propagatedNativeBuildInputs +shell +shellHook +stdenv +strictDeps +system ~PATH
+1. Optional: If you have [direnv](https://direnv.net/) installed with
+   [hooks configured](https://direnv.net/docs/hook.html), you can add `use nix`
+   to `.envrc` to automatically instantiate the development environment:
 
-🎉
-```
+   ```shell
+   cd ~/code/coder
+   echo "use nix" >.envrc
+   direnv allow
+   ```
+
+   Now, whenever you enter the project folder,
+   [`direnv`](https://direnv.net/docs/hook.html) will prepare the environment
+   for you:
+
+   ```shell
+   cd ~/code/coder
+
+   direnv: loading ~/code/coder/.envrc
+   direnv: using nix
+   direnv: export +AR +AS +CC +CONFIG_SHELL +CXX +HOST_PATH +IN_NIX_SHELL +LD +NIX_BINTOOLS +NIX_BINTOOLS_WRAPPER_TARGET_HOST_x86_64_unknown_linux_gnu +NIX_BUILD_CORES +NIX_BUILD_TOP +NIX_CC +NIX_CC_WRAPPER_TARGET_HOST_x86_64_unknown_linux_gnu +NIX_CFLAGS_COMPILE +NIX_ENFORCE_NO_NATIVE +NIX_HARDENING_ENABLE +NIX_INDENT_MAKE +NIX_LDFLAGS +NIX_STORE +NM +NODE_PATH +OBJCOPY +OBJDUMP +RANLIB +READELF +SIZE +SOURCE_DATE_EPOCH +STRINGS +STRIP +TEMP +TEMPDIR +TMP +TMPDIR +XDG_DATA_DIRS +buildInputs +buildPhase +builder +cmakeFlags +configureFlags +depsBuildBuild +depsBuildBuildPropagated +depsBuildTarget +depsBuildTargetPropagated +depsHostHost +depsHostHostPropagated +depsTargetTarget +depsTargetTargetPropagated +doCheck +doInstallCheck +mesonFlags +name +nativeBuildInputs +out +outputs +patches +phases +propagatedBuildInputs +propagatedNativeBuildInputs +shell +shellHook +stdenv +strictDeps +system ~PATH
+
+   🎉
+   ```
 
-Alternatively if you do not want to use nix then you'll need to install the need
+   - If you encounter a `creating directory` error on macOS, check the
+     [troubleshooting](#troubleshooting) section below.
+
+### Without Nix
+
+Alternatively if you do not want to use Nix then you'll need to install the need
 the following tools by hand:
 
 - Go 1.18+
@@ -73,7 +83,9 @@ the following tools by hand:
 - `pandoc`
   - on macOS, run `brew install pandocomatic`
 
-### Development workflow
+</div>
+
+## Development workflow
 
 Use the following `make` commands and scripts in development:
 
@@ -203,8 +215,7 @@ This helps in naming the dump (e.g. `000069` above).
 
 ### Documentation
 
-Our style guide for authoring documentation can be found
-[here](./contributing/documentation.md).
+Visit our [documentation style guide](./contributing/documentation.md).
 
 ### Backend
 
@@ -334,3 +345,17 @@ The
 [`release/experimental`](https://github.com/coder/coder/issues?q=sort%3Aupdated-desc+label%3Arelease%2Fexperimental)
 label can be used to move the note to the bottom of the release notes under a
 separate title.
+
+## Troubleshooting
+
+### Nix on macOS: `error: creating directory`
+
+On macOS, a [direnv bug](https://github.com/direnv/direnv/issues/1345) can cause
+`nix-shell` to fail to build or run `coder`. If you encounter
+`error: creating directory` when you attempt to run, build, or test, add a
+`mkdir` line to your `.envrc`:
+
+```shell
+use nix
+mkdir -p "$TMPDIR"
+```
