mirror of
https://github.com/coder/coder.git
synced 2025-07-15 22:20:27 +00: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>
This commit is contained in:
Edward Angert
GitHub
@ -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
|
||||
```
|
||||
|
||||
Alternatively if you do not want to use nix then you'll need to install the need
|
||||
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
|
||||
|
||||
🎉
|
||||
```
|
||||
|
||||
- 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"
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user