···1# Nim {#nim}
23-## Overview {#nim-overview}
4-5-The Nim compiler, a builder function, and some packaged libraries are available
6-in Nixpkgs. Until now each compiler release has been effectively backwards
7-compatible so only the latest version is available.
8-9-## Nim program packages in Nixpkgs {#nim-program-packages-in-nixpkgs}
10-11-Nim programs can be built using `nimPackages.buildNimPackage`. In the
12-case of packages not containing exported library code the attribute
13-`nimBinOnly` should be set to `true`.
1415The following example shows a Nim program that depends only on Nim libraries:
16-17```nix
18-{ lib, nimPackages, fetchFromGitHub }:
1920-nimPackages.buildNimPackage (finalAttrs: {
21 pname = "ttop";
22- version = "1.0.1";
23- nimBinOnly = true;
2425 src = fetchFromGitHub {
26 owner = "inv2004";
27 repo = "ttop";
28 rev = "v${finalAttrs.version}";
29- hash = "sha256-x4Uczksh6p3XX/IMrOFtBxIleVHdAPX9e8n32VAUTC4=";
30 };
3132- buildInputs = with nimPackages; [ asciigraph illwill parsetoml zippy ];
33-34-})
35-```
36-37-## Nim library packages in Nixpkgs {#nim-library-packages-in-nixpkgs}
38-39-40-Nim libraries can also be built using `nimPackages.buildNimPackage`, but
41-often the product of a fetcher is sufficient to satisfy a dependency.
42-The `fetchgit`, `fetchFromGitHub`, and `fetchNimble` functions yield an
43-output that can be discovered during the `configurePhase` of `buildNimPackage`.
4445-Nim library packages are listed in
46-[pkgs/top-level/nim-packages.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/nim-packages.nix) and implemented at
47-[pkgs/development/nim-packages](https://github.com/NixOS/nixpkgs/tree/master/pkgs/development/nim-packages).
48-49-The following example shows a Nim library that propagates a dependency on a
50-non-Nim package:
51-```nix
52-{ lib, buildNimPackage, fetchNimble, SDL2 }:
53-54-buildNimPackage (finalAttrs: {
55- pname = "sdl2";
56- version = "2.0.4";
57- src = fetchNimble {
58- inherit (finalAttrs) pname version;
59- hash = "sha256-Vtcj8goI4zZPQs2TbFoBFlcR5UqDtOldaXSH/+/xULk=";
60- };
61- propagatedBuildInputs = [ SDL2 ];
62})
63```
6465## `buildNimPackage` parameters {#buildnimpackage-parameters}
6667-All parameters from `stdenv.mkDerivation` function are still supported. The
68-following are specific to `buildNimPackage`:
06970-* `nimBinOnly ? false`: If `true` then build only the programs listed in
71- the Nimble file in the packages sources.
72* `nimbleFile`: Specify the Nimble file location of the package being built
73 rather than discover the file at build-time.
74* `nimRelease ? true`: Build the package in *release* mode.
···77 Use this to specify defines with arguments in the form of `-d:${name}=${value}`.
78* `nimDoc` ? false`: Build and install HTML documentation.
7980-* `buildInputs` ? []: The packages listed here will be searched for `*.nimble`
81- files which are used to populate the Nim library path. Otherwise the standard
82- behavior is in effect.
000000000000000000000000000000000000000000000000000000000000000000
···1# Nim {#nim}
23+The Nim compiler and a builder function is available.
4+Nim programs are built using `buildNimPackage` and a lockfile containing Nim dependencies.
00000000056The following example shows a Nim program that depends only on Nim libraries:
07```nix
8+{ lib, buildNimPackage, fetchFromGitHub }:
910+buildNimPackage { } (finalAttrs: {
11 pname = "ttop";
12+ version = "1.2.7";
01314 src = fetchFromGitHub {
15 owner = "inv2004";
16 repo = "ttop";
17 rev = "v${finalAttrs.version}";
18+ hash = "sha256-oPdaUqh6eN1X5kAYVvevOndkB/xnQng9QVLX9bu5P5E=";
19 };
2021+ lockFile = ./lock.json;
000000000002223+ nimFlags = [
24+ "-d:NimblePkgVersion=${finalAttrs.version}"
25+ ];
0000000000000026})
27```
2829## `buildNimPackage` parameters {#buildnimpackage-parameters}
3031+The `buildNimPackage` function takes an attrset of parameters that are passed on to `stdenv.mkDerivation`.
32+33+The following parameters are specific to `buildNimPackage`:
3435+* `lockFile`: JSON formatted lockfile.
036* `nimbleFile`: Specify the Nimble file location of the package being built
37 rather than discover the file at build-time.
38* `nimRelease ? true`: Build the package in *release* mode.
···41 Use this to specify defines with arguments in the form of `-d:${name}=${value}`.
42* `nimDoc` ? false`: Build and install HTML documentation.
4344+## Lockfiles {#nim-lockfiles}
45+Nim lockfiles are created with the `nim_lk` utility.
46+Run `nim_lk` with the source directory as an argument and it will print a lockfile to stdout.
47+```sh
48+$ cd nixpkgs
49+$ nix build -f . ttop.src
50+$ nix run -f . nim_lk ./result | jq --sort-keys > pkgs/by-name/tt/ttop/lock.json
51+```
52+53+## Lockfile dependency overrides {#nimoverrides}
54+55+The `buildNimPackage` function matches the libraries specified by `lockFile` to attrset of override functions that are then applied to the package derivation.
56+The default overrides are maintained as the top-level `nimOverrides` attrset at `pkgs/top-level/nim-overrides.nix`.
57+58+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:
59+```nix
60+{ lib
61+/* … */
62+, SDL2
63+/* … */
64+}:
65+66+{
67+ /* … */
68+ sdl2 =
69+ lockAttrs:
70+ finalAttrs:
71+ { buildInputs ? [ ], ... }:
72+ {
73+ buildInputs = buildInputs ++ [ SDL2 ];
74+ };
75+ /* … */
76+}
77+```
78+79+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.
80+- 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.
81+- finalAttrs: the final attrset passed by `buildNimPackage` to `stdenv.mkDerivation`.
82+- prevAttrs: the attrset produced by initial arguments to `buildNimPackage` and any preceding lockfile overlays.
83+84+### Overriding an Nim library override {#nimoverrides-overrides}
85+86+The `nimOverrides` attrset makes it possible to modify overrides in a few different ways.
87+88+Override a package internal to its definition:
89+```nix
90+{ lib, buildNimPackage, nimOverrides, libressl }:
91+92+let
93+ buildNimPackage' = buildNimPackage.override {
94+ nimOverrides = nimOverrides.override { openssl = libressl; };
95+ };
96+in buildNimPackage' (finalAttrs: {
97+ pname = "foo";
98+ # …
99+})
100+101+```
102+103+Override a package externally:
104+```nix
105+{ pkgs }: {
106+ foo = pkgs.foo.override {
107+ buildNimPackage = pkgs.buildNimPackage.override {
108+ nimOverrides = pkgs.nimOverrides.override { openssl = libressl; };
109+ };
110+ };
111+}
112+```
···133 if err != 0: quit("build phase failed", err)
134135proc installPhase*() =
136- ## Install the Nim sources if ``nimBinOnly`` is not
137 ## set in the environment.
138- if not getEnvBool"nimBinOnly":
139 let
140 nf = getNimbleFilePath()
141 srcDir = nf.getNimbleValue("srcDir", ".")
···133 if err != 0: quit("build phase failed", err)
134135proc installPhase*() =
136+ ## Install the Nim sources if ``nimCopySources`` is
137 ## set in the environment.
138+ if getEnvBool"nimCopySources":
139 let
140 nf = getNimbleFilePath()
141 srcDir = nf.getNimbleValue("srcDir", ".")
···1+{ lib
2+, SDL2
3+}:
4+5+# The following is list of overrides that take three arguments each:
6+# - lockAttrs: - an attrset from a Nim lockfile, use this for making constraints on the locked library
7+# - finalAttrs: - final arguments to the depender package
8+# - prevAttrs: - preceding arguments to the depender package
9+{
10+11+ sdl2 = lockAttrs: finalAttrs:
12+ { buildInputs ? [ ], ... }: {
13+ buildInputs = buildInputs ++ [ SDL2 ];
14+ };
15+16+}