From 71aaede50debe53a1729603af686398a08fa10fe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?St=C3=A9phan=20Kochen?= <git@stephank.nl>
Date: Thu, 27 Aug 2020 17:57:04 +0200
Subject: [PATCH] Tweak docs

---
 README.md                    | 63 +++++++++++++++++++++++++++++++-----
 src/tmpl/yarn-project.nix.in |  1 -
 2 files changed, 55 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 49cb42e..e92640f 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,41 @@
 # yarn-plugin-nixify
 
-**WORK IN PROGRESS**
+Generates a Nix expression to build a [Yarn] v2 project (not using
+zero-install).
 
-Generates a Nix expression to build a Yarn v2 project (not using zero-install).
+- Provides a build environment where a `yarn` shell alias is readily available
+  — no global Yarn v1 install needed.
+
+- A default configure-phase that runs `yarn` in your project. (Should be enough
+  for plain JavaScript projects.)
+
+- A default install-phase that creates executables for you based on `"bin"` in
+  your `package.json`, making your package readily installable.
+
+- Granular fetching of dependencies in Nix, speeding up rebuilds and
+  potentially allowing downloads to be shared between projects.
+
+- Preloading of your Yarn cache into the Nix store, speeding up local
+  `nix-build`.
+
+- _No Nix installation required_ for the plugin itself, so it should be safe to
+  add to your project even if some developers don't use Nix.
+
+[nix]: https://nixos.org
+[yarn]: https://yarnpkg.com
 
 ## Usage
 
+**This plugin currently depends on Yarn v2 master.**
+
+To get a compatible version, you currently need to install Yarn as follows:
+
+```sh
+yarn set version from sources
+```
+
+To then use the Nixify plugin:
+
 ```sh
 # Install the plugin.
 yarn plugin import https://raw.githubusercontent.com/stephank/yarn-plugin-nixify/main/dist/yarn-plugin-nixify.js
@@ -25,12 +55,9 @@ Running `yarn` with this plugin enabled will generate two files:
 - `default.nix`: Only generated if it does not exist yet. This file is intended
   to be customized with any project-specific logic you need.
 
-When building the basic derivation without any customization, it'll run `yarn`
-inside your project, copy your project to `$out/libexec/<name>`, and setup
-wrappers in `$out/bin` for any executables declared in the `bin` field of your
-top-level `package.json`.
-
-Some examples of how to customize your build from within `default.nix`:
+This should already build successfully! But if your project needs extra build
+steps, you may have to customize `default.nix` a bit. Some examples of what's
+possible:
 
 ```nix
 { pkgs ? import <nixpkgs> { } }:
@@ -64,6 +91,26 @@ in project.overrideAttrs (oldAttrs: {
 })
 ```
 
+## Settings
+
+Some additional settings are available in `.yarnrc.yml`:
+
+- `nixExprPath` can be set to customize the path where the Nixify plugin writes
+  `yarn-project.nix`. For example, if you're also using [Niv] in your project,
+  you may prefer to set this to `nix/yarn-project.nix`.
+
+- `generateDefaultNix` can be set to `false` to disable generating a
+  `default.nix`. This file is only generated if it doesn't exist yet, but this
+  flag can be useful if you don't want a `default.nix` at all.
+
+- `enableNixPreload` can be set to `false` to disable preloading Yarn cache
+  into the Nix store. This preloading is intended to speed up local
+  `nix-build`, because Nix will not have to download dependencies again.
+  Preloading does mean another copy of dependencies on disk even if you don't
+  do local Nix builds, but the size is usually not an issue on modern disks.
+
+[niv]: https://github.com/nmattia/niv
+
 ## Hacking
 
 ```sh
diff --git a/src/tmpl/yarn-project.nix.in b/src/tmpl/yarn-project.nix.in
index 2d8c813..0d97f9b 100644
--- a/src/tmpl/yarn-project.nix.in
+++ b/src/tmpl/yarn-project.nix.in
@@ -57,7 +57,6 @@ in stdenv.mkDerivation {
     runHook preConfigure
 
     # Copy over the Yarn cache.
-    # TODO: Can we do without the copy somehow? Links don't work.
     rm -fr '${cacheFolder}'
     mkdir -p '${cacheFolder}'
     pushd '${cacheFolder}' > /dev/null