doc/languages-frameworks/ocaml.section.md

   1 # OCaml {#sec-language-ocaml}
   2
   3 ## User guide {#sec-language-ocaml-user-guide}
   4
   5 OCaml libraries are available in attribute sets of the form `ocaml-ng.ocamlPackages_X_XX` where X is to be replaced with the desired compiler version. For example, ocamlgraph compiled with OCaml 4.12 can be found in `ocaml-ng.ocamlPackages_4_12.ocamlgraph`. The compiler itself is also located in this set, under the name `ocaml`.
   6
   7 If you don't care about the exact compiler version, `ocamlPackages` is a top-level alias pointing to a recent version of OCaml.
   8
   9 OCaml applications are usually available top-level, and not inside `ocamlPackages`. Notable exceptions are build tools that must be built with the same compiler version as the compiler you intend to use like `dune` or `ocaml-lsp`.
  10
  11 To open a shell able to build a typical OCaml project, put the dependencies in `buildInputs` and add `ocamlPackages.ocaml` and `ocamlPackages.findlib` to `nativeBuildInputs` at least.
  12 For example:
  13 ```nix
  14 let
  15  pkgs = import <nixpkgs> {};
  16  # choose the ocaml version you want to use
  17  ocamlPackages = pkgs.ocaml-ng.ocamlPackages_4_12;
  18 in
  19 pkgs.mkShell {
  20   # build tools
  21   nativeBuildInputs = with ocamlPackages; [ ocaml findlib dune_2 ocaml-lsp ];
  22   # dependencies
  23   buildInputs = with ocamlPackages; [ ocamlgraph ];
  24 }
  25 ```
  26
  27 ## Packaging guide {#sec-language-ocaml-packaging}
  28
  29 OCaml libraries should be installed in `$(out)/lib/ocaml/${ocaml.version}/site-lib/`. Such directories are automatically added to the `$OCAMLPATH` environment variable when building another package that depends on them or when opening a `nix-shell`.
  30
  31 Given that most of the OCaml ecosystem is now built with dune, nixpkgs includes a convenience build support function called `buildDunePackage` that will build an OCaml package using dune, OCaml and findlib and any additional dependencies provided as `buildInputs` or `propagatedBuildInputs`.
  32
  33 Here is a simple package example.
  34
  35 - It defines an (optional) attribute `minimalOCamlVersion` (see note below)
  36   that will be used to throw a descriptive evaluation error if building with
  37   an older OCaml is attempted.
  38
  39 - It uses the `fetchFromGitHub` fetcher to get its source.
  40
  41 - `duneVersion = "2"` ensures that Dune version 2 is used for the
  42   build (this is the default; valid values are `"1"`, `"2"`, and `"3"`);
  43   note that there is also a legacy `useDune2` boolean attribute:
  44   set to `false` it corresponds to `duneVersion = "1"`; set to `true` it
  45   corresponds to `duneVersion = "2"`. If both arguments (`duneVersion` and
  46   `useDune2`) are given, the second one (`useDune2`) is silently ignored.
  47
  48 - It sets the optional `doCheck` attribute such that tests will be run with
  49   `dune runtest -p angstrom` after the build (`dune build -p angstrom`) is
  50   complete, but only if the Ocaml version is at at least `"4.05"`.
  51
  52 - It uses the package `ocaml-syntax-shims` as a build input, `alcotest` and
  53   `ppx_let` as check inputs (because they are needed to run the tests), and
  54   `bigstringaf` and `result` as propagated build inputs (thus they will also be
  55   available to libraries depending on this library).
  56
  57 - The library will be installed using the `angstrom.install` file that dune
  58   generates.
  59
  60 ```nix
  61 { lib,
  62   fetchFromGitHub,
  63   buildDunePackage,
  64   ocaml,
  65   ocaml-syntax-shims,
  66   alcotest,
  67   result,
  68   bigstringaf,
  69   ppx_let }:
  70
  71 buildDunePackage rec {
  72   pname = "angstrom";
  73   version = "0.15.0";
  74   duneVersion = "2";
  75
  76   minimalOCamlVersion = "4.04";
  77
  78   src = fetchFromGitHub {
  79     owner  = "inhabitedtype";
  80     repo   = pname;
  81     rev    = version;
  82     sha256 = "1hmrkdcdlkwy7rxhngf3cv3sa61cznnd9p5lmqhx20664gx2ibrh";
  83   };
  84
  85   checkInputs = [ alcotest ppx_let ];
  86   buildInputs = [ ocaml-syntax-shims ];
  87   propagatedBuildInputs = [ bigstringaf result ];
  88   doCheck = lib.versionAtLeast ocaml.version "4.05";
  89
  90   meta = {
  91     homepage = "https://github.com/inhabitedtype/angstrom";
  92     description = "OCaml parser combinators built for speed and memory efficiency";
  93     license = lib.licenses.bsd3;
  94     maintainers = with lib.maintainers; [ sternenseemann ];
  95   };
  96 ```
  97
  98 Here is a second example, this time using a source archive generated with `dune-release`. It is a good idea to use this archive when it is available as it will usually contain substituted variables such as a `%%VERSION%%` field. This library does not depend on any other OCaml library and no tests are run after building it.
  99
 100 ```nix
 101 { lib, fetchurl, buildDunePackage }:
 102
 103 buildDunePackage rec {
 104   pname = "wtf8";
 105   version = "1.0.2";
 106
 107   useDune2 = true;
 108
 109   minimalOCamlVersion = "4.02";
 110
 111   src = fetchurl {
 112     url = "https://github.com/flowtype/ocaml-${pname}/releases/download/v${version}/${pname}-v${version}.tbz";
 113     sha256 = "09ygcxxd5warkdzz17rgpidrd0pg14cy2svvnvy1hna080lzg7vp";
 114   };
 115
 116   meta = with lib; {
 117     homepage = "https://github.com/flowtype/ocaml-wtf8";
 118     description = "WTF-8 is a superset of UTF-8 that allows unpaired surrogates.";
 119     license = licenses.mit;
 120     maintainers = [ maintainers.eqyiel ];
 121   };
 122 }
 123 ```
 124
 125 Note about `minimalOCamlVersion`.  A deprecated version of this argument was
 126 spelled `minimumOCamlVersion`; setting the old attribute wrongly modifies the
 127 derivation hash and is therefore inappropriate. As a technical dept, currently
 128 packaged libraries may still use the old spelling: maintainers are invited to
 129 fix this when updating packages. Massive renaming is strongly discouraged as it
 130 would be challenging to review, difficult to test, and will cause unnecessary
 131 rebuild.