-
-
Notifications
You must be signed in to change notification settings - Fork 1.2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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.
- Loading branch information
Showing
2 changed files
with
41 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -97,7 +97,9 @@ git clone [email protected]: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`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 <url>` | ||
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 | ||
]; | ||
} |