Home • Explore • Blog • Models • CI
☰



nixpkgs
1st chunk of `doc/languages-frameworks/nim.section.md`
d50362cb160647c014fcea9f985bb0bd433c5820b27e470e0000000100000ae5
# Nim {#sec-language-nim}

The Nim compiler and a builder function is available.
Nim programs are built using a lockfile and either `buildNimPackage` or `buildNimSbom`.

## buildNimPackage {#buildNimPackage}

The following example shows a Nim program that depends only on Nim libraries:
```nix
{
  lib,
  buildNimPackage,
  fetchFromGitHub,
}:

buildNimPackage (finalAttrs: {
  pname = "ttop";
  version = "1.2.7";

  src = fetchFromGitHub {
    owner = "inv2004";
    repo = "ttop";
    rev = "v${finalAttrs.version}";
    hash = lib.fakeHash;
  };

  lockFile = ./lock.json;

  nimFlags = [ "-d:NimblePkgVersion=${finalAttrs.version}" ];
})
```

### `buildNimPackage` parameters {#buildnimpackage-parameters}

The `buildNimPackage` function takes an attrset of parameters that are passed on to `stdenv.mkDerivation`.

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.
* `nimDefines ? []`: A list of Nim defines. Key-value tuples are not supported.
* `nimFlags ? []`: A list of command line arguments to pass to the Nim compiler.
  Use this to specify defines with arguments in the form of `-d:${name}=${value}`.
* `nimDoc` ? false`: Build and install HTML documentation.

### 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
```

## buildNimSbom {#buildNimSbom}

An alternative to `buildNimPackage` is `buildNimSbom` which builds packages from [CycloneDX SBOM](https://cyclonedx.org/) files.
`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).

In the following minimal example only the source code checkout and a `buildInput` are specified.
The SBOM file provides metadata such as `pname` and `version` as well as the sources to Nim dependencies.
```nix
# pkgs/by-name/ni/nim_lk/package.nix
{
  lib,
  buildNimSbom,
  fetchFromSourcehut,
  openssl,
}:

buildNimSbom (finalAttrs: {
  src = fetchFromSourcehut {
    owner = "~ehmry";
    repo = "nim_lk";
    rev = finalAttrs.version;
    hash = lib.fakeHash;
  };
  buildInputs = [ openssl ];
}) ./sbom.json
```

### Generating SBOMs {#generating-nim-sboms}

The [nim_lk](https://git.sr.ht/~ehmry/nim_lk) utility can generate SBOMs from [Nimble](https://github.com/nim-lang/nimble) package metadata.
Title: Nim Package Building in Nix
Summary
This section details how to build Nim programs using Nix, offering two primary functions: `buildNimPackage` and `buildNimSbom`. `buildNimPackage` is used for Nim programs depending on Nim libraries, requiring a `lockFile` (generated by the `nim_lk` utility) and accepting various parameters like `nimFlags` and `nimDefines`. Alternatively, `buildNimSbom` builds packages from CycloneDX SBOM files, resolving Nim dependencies to fixed-output derivations, and also uses the `nim_lk` utility for SBOM generation from Nimble package metadata.