Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jan 2, 2025
Merged

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

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d10d9b5
docs: document issue with direnv and nix-shell on macOS (#15990)
paulroub Jan 2, 2025
ef24953
make fmt
EdwardAngert Jan 2, 2025
eeec289
adds nix/not nix tabs
EdwardAngert Jan 2, 2025
eacefb6
checkout origin/main -- **/XAxis.tsx
EdwardAngert Jan 2, 2025
a7b2690
add troubleshooting to bottom
EdwardAngert Jan 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 63 additions & 38 deletions docs/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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+
Expand All @@ -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:

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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"
```
Loading