From 077925c9e5a4f880b99257b54dbe4057f0f71849 Mon Sep 17 00:00:00 2001 From: Cody Allen Date: Sun, 2 Dec 2018 09:01:59 -0800 Subject: [PATCH] Add a shell.nix and instructions for using it I have mixed feelings about this. On the one hand, it feels like which tools a developer uses in their environment shouldn't bleed into the source repository. On the other hand, getting a proper Cats development environment includes wrangling some finicky bits that can be tricky for a Scala developer (such as managing Jekyll and Node.js versions). I'm generally in favor of lowering this barrier and using a deterministic build environment. I've been using something like this for a while when working on Cats and thought that I'd put together this PR in case others are interested in doing the same. If people aren't crazy about this, it's no big deal; it's easy enough to have it ignored by git. --- CONTRIBUTING.md | 17 ++++++++++++++++- shell.nix | 25 +++++++++++++++++++++++++ 2 files changed, 41 insertions(+), 1 deletion(-) create mode 100644 shell.nix diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 29d9091ccf9..5abde3b55fe 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 00000000000..ce45b8c6e5d --- /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 = with pkgs; [ + 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 + ]; + }