Merge https://github.com/NixOS/nixpkgs

1 files changed, 83 insertions, 53 deletions

diff --git a/nixpkgs/doc/languages-frameworks/nim.section.md b/nixpkgs/doc/languages-frameworks/nim.section.md
index 6b0fb3df0311..45cd07b3a3d8 100644
--- a/nixpkgs/doc/languages-frameworks/nim.section.md
+++ b/nixpkgs/doc/languages-frameworks/nim.section.md
@@ -1,74 +1,38 @@
 # Nim {#nim}
 
-## Overview {#nim-overview}
-
-The Nim compiler, a builder function, and some packaged libraries are available
-in Nixpkgs. Until now each compiler release has been effectively backwards
-compatible so only the latest version is available.
-
-## Nim program packages in Nixpkgs {#nim-program-packages-in-nixpkgs}
-
-Nim programs can be built using `nimPackages.buildNimPackage`. In the
-case of packages not containing exported library code the attribute
-`nimBinOnly` should be set to `true`.
+The Nim compiler and a builder function is available.
+Nim programs are built using `buildNimPackage` and a lockfile containing Nim dependencies.
 
 The following example shows a Nim program that depends only on Nim libraries:
-
 ```nix
-{ lib, nimPackages, fetchFromGitHub }:
+{ lib, buildNimPackage, fetchFromGitHub }:
 
-nimPackages.buildNimPackage (finalAttrs: {
+buildNimPackage { } (finalAttrs: {
   pname = "ttop";
-  version = "1.0.1";
-  nimBinOnly = true;
+  version = "1.2.7";
 
   src = fetchFromGitHub {
     owner = "inv2004";
     repo = "ttop";
     rev = "v${finalAttrs.version}";
-    hash = "sha256-x4Uczksh6p3XX/IMrOFtBxIleVHdAPX9e8n32VAUTC4=";
+    hash = "sha256-oPdaUqh6eN1X5kAYVvevOndkB/xnQng9QVLX9bu5P5E=";
   };
 
-  buildInputs = with nimPackages; [ asciigraph illwill parsetoml zippy ];
+  lockFile = ./lock.json;
 
-})
-```
-
-## Nim library packages in Nixpkgs {#nim-library-packages-in-nixpkgs}
-
-
-Nim libraries can also be built using `nimPackages.buildNimPackage`, but
-often the product of a fetcher is sufficient to satisfy a dependency.
-The `fetchgit`, `fetchFromGitHub`, and `fetchNimble` functions yield an
-output that can be discovered during the `configurePhase` of `buildNimPackage`.
-
-Nim library packages are listed in
-[pkgs/top-level/nim-packages.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/nim-packages.nix) and implemented at
-[pkgs/development/nim-packages](https://github.com/NixOS/nixpkgs/tree/master/pkgs/development/nim-packages).
-
-The following example shows a Nim library that propagates a dependency on a
-non-Nim package:
-```nix
-{ lib, buildNimPackage, fetchNimble, SDL2 }:
-
-buildNimPackage (finalAttrs: {
-  pname = "sdl2";
-  version = "2.0.4";
-  src = fetchNimble {
-    inherit (finalAttrs) pname version;
-    hash = "sha256-Vtcj8goI4zZPQs2TbFoBFlcR5UqDtOldaXSH/+/xULk=";
-  };
-  propagatedBuildInputs = [ SDL2 ];
+  nimFlags = [
+    "-d:NimblePkgVersion=${finalAttrs.version}"
+  ];
 })
 ```
 
 ## `buildNimPackage` parameters {#buildnimpackage-parameters}
 
-All parameters from `stdenv.mkDerivation` function are still supported. The
-following are specific to `buildNimPackage`:
+The `buildNimPackage` function takes an attrset of parameters that are passed on to `stdenv.mkDerivation`.
 
-* `nimBinOnly ? false`: If `true` then build only the programs listed in
-  the Nimble file in the packages sources.
+The following parameters are specific to `buildNimPackage`:
+
+* `lockFile`: JSON formatted lockfile.
 * `nimbleFile`: Specify the Nimble file location of the package being built
   rather than discover the file at build-time.
 * `nimRelease ? true`: Build the package in *release* mode.
@@ -77,6 +41,72 @@ following are specific to `buildNimPackage`:
   Use this to specify defines with arguments in the form of `-d:${name}=${value}`.
 * `nimDoc` ? false`: Build and install HTML documentation.
 
-* `buildInputs` ? []: The packages listed here will be searched for `*.nimble`
-  files which are used to populate the Nim library path. Otherwise the standard
-  behavior is in effect.
+## Lockfiles {#nim-lockfiles}
+Nim lockfiles are created with the `nim_lk` utility.
+Run `nim_lk` with the source directory as an argument and it will print a lockfile to stdout.
+```sh
+$ cd nixpkgs
+$ nix build -f . ttop.src
+$ nix run -f . nim_lk ./result | jq --sort-keys > pkgs/by-name/tt/ttop/lock.json
+```
+
+## Lockfile dependency overrides {#nimoverrides}
+
+The `buildNimPackage` function matches the libraries specified by `lockFile` to attrset of override functions that are then applied to the package derivation.
+The default overrides are maintained as the top-level `nimOverrides` attrset at `pkgs/top-level/nim-overrides.nix`.
+
+For example, to propagate a dependency on SDL2 for lockfiles that select the Nim `sdl2` library, an overlay is added to the set in the `nim-overrides.nix` file:
+```nix
+{ lib
+/* … */
+, SDL2
+/* … */
+}:
+
+{
+  /* … */
+  sdl2 =
+    lockAttrs:
+    finalAttrs:
+    { buildInputs ? [ ], ... }:
+    {
+      buildInputs = buildInputs ++ [ SDL2 ];
+    };
+  /* … */
+}
+```
+
+The annotations in the `nim-overrides.nix` set are functions that take three arguments and return a new attrset to be overlayed on the package being built.
+- lockAttrs: the attrset for this library from within a lockfile. This can be used to implement library version constraints, such as marking libraries as broken or insecure.
+- finalAttrs: the final attrset passed by `buildNimPackage` to `stdenv.mkDerivation`.
+- prevAttrs: the attrset produced by initial arguments to `buildNimPackage` and any preceding lockfile overlays.
+
+### Overriding an Nim library override {#nimoverrides-overrides}
+
+The `nimOverrides` attrset makes it possible to modify overrides in a few different ways.
+
+Override a package internal to its definition:
+```nix
+{ lib, buildNimPackage, nimOverrides, libressl }:
+
+let
+  buildNimPackage' = buildNimPackage.override {
+    nimOverrides = nimOverrides.override { openssl = libressl; };
+  };
+in buildNimPackage' (finalAttrs: {
+  pname = "foo";
+  # …
+})
+
+```
+
+Override a package externally:
+```nix
+{ pkgs }: {
+  foo = pkgs.foo.override {
+    buildNimPackage = pkgs.buildNimPackage.override {
+      nimOverrides = pkgs.nimOverrides.override { openssl = libressl; };
+    };
+  };
+}
+```