doc/languages-frameworks/nim.section.md

   1 # Nim {#nim}
   2
   3 ## 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`.
  14
  15 The following example shows a Nim program that depends only on Nim libraries:
  16
  17 ```nix
  18 { lib, nimPackages, fetchurl }:
  19
  20 nimPackages.buildNimPackage rec {
  21   pname = "hottext";
  22   version = "1.4";
  23
  24   nimBinOnly = true;
  25
  26   src = fetchurl {
  27     url = "https://git.sr.ht/~ehmry/hottext/archive/v${version}.tar.gz";
  28     sha256 = "sha256-hIUofi81zowSMbt1lUsxCnVzfJGN3FEiTtN8CEFpwzY=";
  29   };
  30
  31   buildInputs = with nimPackages; [
  32     bumpy
  33     chroma
  34     flatty
  35     nimsimd
  36     pixie
  37     sdl2
  38     typography
  39     vmath
  40     zippy
  41   ];
  42 }
  43
  44 ```
  45
  46 ## Nim library packages in Nixpkgs {#nim-library-packages-in-nixpkgs}
  47
  48
  49 Nim libraries can also be built using `nimPackages.buildNimPackage`, but
  50 often the product of a fetcher is sufficient to satisfy a dependency.
  51 The `fetchgit`, `fetchFromGitHub`, and `fetchNimble` functions yield an
  52 output that can be discovered during the `configurePhase` of `buildNimPackage`.
  53
  54 Nim library packages are listed in
  55 [pkgs/top-level/nim-packages.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/nim-packages.nix) and implemented at
  56 [pkgs/development/nim-packages](https://github.com/NixOS/nixpkgs/tree/master/pkgs/development/nim-packages).
  57
  58 The following example shows a Nim library that propagates a dependency on a
  59 non-Nim package:
  60 ```nix
  61 { lib, buildNimPackage, fetchNimble, SDL2 }:
  62
  63 buildNimPackage rec {
  64   pname = "sdl2";
  65   version = "2.0.4";
  66   src = fetchNimble {
  67     inherit pname version;
  68     hash = "sha256-Vtcj8goI4zZPQs2TbFoBFlcR5UqDtOldaXSH/+/xULk=";
  69   };
  70   propagatedBuildInputs = [ SDL2 ];
  71 }
  72 ```
  73
  74 ## `buildNimPackage` parameters {#buildnimpackage-parameters}
  75
  76 All parameters from `stdenv.mkDerivation` function are still supported. The
  77 following are specific to `buildNimPackage`:
  78
  79 * `nimBinOnly ? false`: If `true` then build only the programs listed in
  80   the Nimble file in the packages sources.
  81 * `nimbleFile`: Specify the Nimble file location of the package being built
  82   rather than discover the file at build-time.
  83 * `nimRelease ? true`: Build the package in *release* mode.
  84 * `nimDefines ? []`: A list of Nim defines. Key-value tuples are not supported.
  85 * `nimFlags ? []`: A list of command line arguments to pass to the Nim compiler.
  86   Use this to specify defines with arguments in the form of `-d:${name}=${value}`.
  87 * `nimDoc` ? false`: Build and install HTML documentation.
  88
  89 * `buildInputs` ? []: The packages listed here will be searched for `*.nimble`
  90   files which are used to populate the Nim library path. Otherwise the standard
  91   behavior is in effect.