diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 29d9091ccf..5abde3b55f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -97,7 +97,9 @@ git clone git@github.com:typelevel/cats.git To build Cats you should have [sbt](http://www.scala-sbt.org/0.13/tutorial/Setup.html) and [Node.js](https://nodejs.org/) - installed. Run `sbt`, and then use any of the following commands: + installed. If you'd like, you can use the [Nix Cats development environment](#nix-cats-development-environment). + + Run `sbt`, and then use any of the following commands: * `compile`: compile the code * `console`: launch a REPL @@ -202,6 +204,8 @@ run `sbt docs/makeMicrosite` `gem install jekyll` + Or just dropping into a `nix-shell` if you are using the [Nix Cats development environment](#nix-cats-development-environment). + 2. In a shell, navigate to the generated site directory in `docs/target/site` 3. Start jekyll with `jekyll serve` @@ -278,3 +282,14 @@ escalate into larger problems. If you are being harassed, please contact one of [us](https://github.com/typelevel/cats#maintainers) immediately so that we can support you. + +## Nix Cats Development Environment + +Since Cats development can include the Scala runtime, the Scala.js runtime, the Cats website, and more; a number of dependencies (SBT, Node.js, Jekyll, etc) can be needed to work on Cats. Managing these dependencies globally can be a hassle and can lead to version conflicts. To make this easier to manage in an isolated development environment, Cats provides a `shell.nix` for anyone using the [Nix package manager](https://nixos.org/nix/). + +To use the Nix-based Cats development environment: + +1. [Install](https://nixos.org/nix/download.html) the Nix package manager. +2. At the root level of the Cats repository, run `nix-shell --pure`. This will drop you into a minimal bash shell that has just the required dependencies on the `PATH`. Note that the first time that you run this it will take some extra time to download the necessary dependencies into your local Nix store. +3. Run `sbt`, `jekyll`, etc as required from the `nix-shell`. +4. When you are finished you can `exit` the `nix-shell`. diff --git a/shell.nix b/shell.nix new file mode 100644 index 0000000000..661b5e4141 --- /dev/null +++ b/shell.nix @@ -0,0 +1,25 @@ +let + + # use a pinned version of nixpkgs for reproducability + nixpkgs-version = "18.09"; + pkgs = import (builtins.fetchTarball { + # Descriptive name to make the store path easier to identify + name = "nixpkgs-${nixpkgs-version}"; + url = "https://github.com/nixos/nixpkgs/archive/${nixpkgs-version}.tar.gz"; + # Hash obtained using `nix-prefetch-url --unpack ` + sha256 = "1ib96has10v5nr6bzf7v8kw7yzww8zanxgw2qi1ll1sbv6kj6zpd"; + }) {}; +in + with pkgs; + stdenv.mkDerivation { + name = "cats-dev-env"; + + buildInputs = [ + sbt + git # used by sbt-buildinfo + nodejs # used by scala.js + jekyll # used by sbt-microsites + gawk # used by scripts/parse-test-durations.awk + graphviz # used for ScalaDoc diagrams + ]; + }