pyrox.dev
1# Nim {#nim}
2
3The Nim compiler and a builder function is available.
4Nim programs are built using `buildNimPackage` and a lockfile containing Nim dependencies.
5
6The following example shows a Nim program that depends only on Nim libraries:
7```nix
8{ lib, buildNimPackage, fetchFromGitHub }:
9
10buildNimPackage { } (finalAttrs: {
11 pname = "ttop";
12 version = "1.2.7";
13
14 src = fetchFromGitHub {
15 owner = "inv2004";
16 repo = "ttop";
17 rev = "v${finalAttrs.version}";
18 hash = "sha256-oPdaUqh6eN1X5kAYVvevOndkB/xnQng9QVLX9bu5P5E=";
19 };
20
21 lockFile = ./lock.json;
22
23 nimFlags = [
24 "-d:NimblePkgVersion=${finalAttrs.version}"
25 ];
26})
27```
28
29## `buildNimPackage` parameters {#buildnimpackage-parameters}
30
31The `buildNimPackage` function takes an attrset of parameters that are passed on to `stdenv.mkDerivation`.
32
33The following parameters are specific to `buildNimPackage`:
34
35* `lockFile`: JSON formatted lockfile.
36* `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.
39* `nimDefines ? []`: A list of Nim defines. Key-value tuples are not supported.
40* `nimFlags ? []`: A list of command line arguments to pass to the Nim compiler.
41 Use this to specify defines with arguments in the form of `-d:${name}=${value}`.
42* `nimDoc` ? false`: Build and install HTML documentation.
43
44## Lockfiles {#nim-lockfiles}
45Nim lockfiles are created with the `nim_lk` utility.
46Run `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## Overriding Nim packages {#nim-overrides}
54
55The `buildNimPackage` function generates flags and additional build dependencies from the `lockFile` parameter passed to `buildNimPackage`. Using [`overrideAttrs`](#sec-pkg-overrideAttrs) on the final package will apply after this has already been generated, so this can't be used to override the `lockFile` in a package built with `buildNimPackage`. To be able to override parameters before flags and build dependencies are generated from the `lockFile`, use `overrideNimAttrs` instead with the same syntax as `overrideAttrs`:
56
57```nix
58pkgs.nitter.overrideNimAttrs {
59 # using a different source which has different dependencies from the standard package
60 src = pkgs.fetchFromGithub { /* … */ };
61 # new lock file generated from the source
62 lockFile = ./custom-lock.json;
63}
64```
65
66## Lockfile dependency overrides {#nim-lock-overrides}
67
68The `buildNimPackage` function matches the libraries specified by `lockFile` to attrset of override functions that are then applied to the package derivation.
69The default overrides are maintained as the top-level `nimOverrides` attrset at `pkgs/top-level/nim-overrides.nix`.
70
71For 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:
72```nix
73{ lib
74/* … */
75, SDL2
76/* … */
77}:
78
79{
80 /* … */
81 sdl2 =
82 lockAttrs:
83 finalAttrs:
84 { buildInputs ? [ ], ... }:
85 {
86 buildInputs = buildInputs ++ [ SDL2 ];
87 };
88 /* … */
89}
90```
91
92The 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.
93- 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.
94- finalAttrs: the final attrset passed by `buildNimPackage` to `stdenv.mkDerivation`.
95- prevAttrs: the attrset produced by initial arguments to `buildNimPackage` and any preceding lockfile overlays.
96
97### Overriding an Nim library override {#nim-lock-overrides-overrides}
98
99The `nimOverrides` attrset makes it possible to modify overrides in a few different ways.
100
101Override a package internal to its definition:
102```nix
103{ lib, buildNimPackage, nimOverrides, libressl }:
104
105let
106 buildNimPackage' = buildNimPackage.override {
107 nimOverrides = nimOverrides.override { openssl = libressl; };
108 };
109in buildNimPackage' (finalAttrs: {
110 pname = "foo";
111 # …
112})
113
114```
115
116Override a package externally:
117```nix
118{ pkgs }: {
119 foo = pkgs.foo.override {
120 buildNimPackage = pkgs.buildNimPackage.override {
121 nimOverrides = pkgs.nimOverrides.override { openssl = libressl; };
122 };
123 };
124}
125```