pyrox.dev
1# Nim {#sec-language-nim}
2
3The Nim compiler and a builder function is available.
4Nim programs are built using a lockfile and either `buildNimPackage` or `buildNimSbom`.
5
6## buildNimPackage {#buildNimPackage}
7
8The following example shows a Nim program that depends only on Nim libraries:
9```nix
10{
11 lib,
12 buildNimPackage,
13 fetchFromGitHub,
14}:
15
16buildNimPackage (finalAttrs: {
17 pname = "ttop";
18 version = "1.2.7";
19
20 src = fetchFromGitHub {
21 owner = "inv2004";
22 repo = "ttop";
23 rev = "v${finalAttrs.version}";
24 hash = lib.fakeHash;
25 };
26
27 lockFile = ./lock.json;
28
29 nimFlags = [ "-d:NimblePkgVersion=${finalAttrs.version}" ];
30})
31```
32
33### `buildNimPackage` parameters {#buildnimpackage-parameters}
34
35The `buildNimPackage` function takes an attrset of parameters that are passed on to `stdenv.mkDerivation`.
36
37The following parameters are specific to `buildNimPackage`:
38
39* `lockFile`: JSON formatted lockfile.
40* `nimbleFile`: Specify the Nimble file location of the package being built
41 rather than discover the file at build-time.
42* `nimRelease ? true`: Build the package in *release* mode.
43* `nimDefines ? []`: A list of Nim defines. Key-value tuples are not supported.
44* `nimFlags ? []`: A list of command line arguments to pass to the Nim compiler.
45 Use this to specify defines with arguments in the form of `-d:${name}=${value}`.
46* `nimDoc` ? false`: Build and install HTML documentation.
47
48### Lockfiles {#nim-lockfiles}
49Nim lockfiles are created with the `nim_lk` utility.
50Run `nim_lk` with the source directory as an argument and it will print a lockfile to stdout.
51```sh
52$ cd nixpkgs
53$ nix build -f . ttop.src
54$ nix run -f . nim_lk ./result | jq --sort-keys > pkgs/by-name/tt/ttop/lock.json
55```
56
57## buildNimSbom {#buildNimSbom}
58
59An alternative to `buildNimPackage` is `buildNimSbom` which builds packages from [CycloneDX SBOM](https://cyclonedx.org/) files.
60`buildNimSbom` resolves Nim dependencies to [fixed-output derivations](https://nixos.org/manual/nix/stable/glossary#gloss-fixed-output-derivation) using the [nix:fod namespace](#sec-interop.cylonedx-fod).
61
62In the following minimal example only the source code checkout and a `buildInput` are specified.
63The SBOM file provides metadata such as `pname` and `version` as well as the sources to Nim dependencies.
64```nix
65# pkgs/by-name/ni/nim_lk/package.nix
66{
67 lib,
68 buildNimSbom,
69 fetchFromSourcehut,
70 openssl,
71}:
72
73buildNimSbom (finalAttrs: {
74 src = fetchFromSourcehut {
75 owner = "~ehmry";
76 repo = "nim_lk";
77 rev = finalAttrs.version;
78 hash = lib.fakeHash;
79 };
80 buildInputs = [ openssl ];
81}) ./sbom.json
82```
83
84### Generating SBOMs {#generating-nim-sboms}
85
86The [nim_lk](https://git.sr.ht/~ehmry/nim_lk) utility can generate SBOMs from [Nimble](https://github.com/nim-lang/nimble) package metadata.
87See the [nim_lk documentation](https://git.sr.ht/~ehmry/nim_lk#nimble-to-cyclonedx-sbom) for more information.
88
89## Overriding Nim packages {#nim-overrides}
90
91The `buildNimPackage` and `buildNimSbom` functions generate 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`:
92
93```nix
94pkgs.nitter.overrideNimAttrs {
95 # using a different source which has different dependencies from the standard package
96 src = pkgs.fetchFromGithub {
97 # …
98 };
99 # new lock file generated from the source
100 lockFile = ./custom-lock.json;
101}
102```
103
104## Lockfile dependency overrides {#nim-lock-overrides}
105
106The `buildNimPackage` function matches the libraries specified by `lockFile` to attrset of override functions that are then applied to the package derivation.
107The default overrides are maintained as the top-level `nimOverrides` attrset at `pkgs/top-level/nim-overrides.nix`.
108
109For 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:
110```nix
111{
112 lib,
113 # …
114 SDL2,
115# …
116}:
117
118{
119 # …
120 sdl2 =
121 lockAttrs:
122 {
123 buildInputs ? [ ],
124 ...
125 }:
126 {
127 buildInputs = buildInputs ++ [ SDL2 ];
128 };
129 # …
130}
131```
132
133The annotations in the `nim-overrides.nix` set are functions that take two arguments and return a new attrset to be overlaid on the package being built.
134- 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.
135- prevAttrs: the attrset produced by initial arguments to `buildNimPackage` and any preceding lockfile overlays.
136
137### Overriding an Nim library override {#nim-lock-overrides-overrides}
138
139The `nimOverrides` attrset makes it possible to modify overrides in a few different ways.
140
141Override a package internal to its definition:
142```nix
143{
144 lib,
145 buildNimPackage,
146 nimOverrides,
147 libressl,
148}:
149
150let
151 buildNimPackage' = buildNimPackage.override {
152 nimOverrides = nimOverrides.override { openssl = libressl; };
153 };
154in
155buildNimPackage' (finalAttrs: {
156 pname = "foo";
157 # …
158})
159```
160
161Override a package externally:
162```nix
163{ pkgs }:
164{
165 foo = pkgs.foo.override {
166 buildNimPackage = pkgs.buildNimPackage.override {
167 nimOverrides = pkgs.nimOverrides.override { openssl = libressl; };
168 };
169 };
170}
171```