From 5cd08118d953bba08936914318e29cabc4301862 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9o=20Zimmermann?=
 <theo.zimmermann@univ-paris-diderot.fr>
Date: Tue, 6 Nov 2018 18:18:27 +0100
Subject: [PATCH] duneBuildPackage: document

---
 doc/languages-frameworks/index.xml |   1 +
 doc/languages-frameworks/ocaml.xml | 101 +++++++++++++++++++++++++++++
 2 files changed, 102 insertions(+)
 create mode 100644 doc/languages-frameworks/ocaml.xml

diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml
index f22984cb56b0..ac0ad7125324 100644
--- a/doc/languages-frameworks/index.xml
+++ b/doc/languages-frameworks/index.xml
@@ -19,6 +19,7 @@
  <xi:include href="java.xml" />
  <xi:include href="lua.xml" />
  <xi:include href="node.section.xml" />
+ <xi:include href="ocaml.xml" />
  <xi:include href="perl.xml" />
  <xi:include href="python.section.xml" />
  <xi:include href="qt.xml" />
diff --git a/doc/languages-frameworks/ocaml.xml b/doc/languages-frameworks/ocaml.xml
new file mode 100644
index 000000000000..d1c29c72f726
--- /dev/null
+++ b/doc/languages-frameworks/ocaml.xml
@@ -0,0 +1,101 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="sec-language-ocaml">
+ <title>OCaml</title>
+
+ <para>
+   OCaml libraries should be installed in
+   <literal>$(out)/lib/ocaml/${ocaml.version}/site-lib/</literal>. Such
+   directories are automatically added to the <literal>$OCAMLPATH</literal>
+   environment variable when building another package that depends on them
+   or when opening a <literal>nix-shell</literal>.
+ </para>
+
+ <para>
+   Given that most of the OCaml ecosystem is now built with dune,
+   nixpkgs includes a convenience build support function called
+   <literal>buildDunePackage</literal> that will build an OCaml package
+   using dune, OCaml and findlib and any additional dependencies provided
+   as <literal>buildInputs</literal> or <literal>propagatedBuildInputs</literal>.
+ </para>
+
+ <para>
+   Here is a simple package example. It defines an (optional) attribute
+   <literal>minimumOCamlVersion</literal> that will be used to throw a
+   descriptive evaluation error if building with an older OCaml is attempted.
+   It uses the <literal>fetchFromGitHub</literal> fetcher to get its source.
+   It sets the <literal>doCheck</literal> (optional) attribute to
+   <literal>true</literal> which means that tests will be run with
+   <literal>dune runtest -p angstrom</literal> after the build
+   (<literal>dune build -p angstrom</literal>) is complete.
+   It uses <literal>alcotest</literal> as a build input (because it is needed
+   to run the tests) and <literal>bigstringaf</literal> and
+   <literal>result</literal> as propagated build inputs (thus they will also
+   be available to libraries depending on this library).
+   The library will be installed using the <literal>angstrom.install</literal>
+   file that dune generates.
+ </para>
+
+ <programlisting>
+{ stdenv, fetchFromGitHub, buildDunePackage, alcotest, result, bigstringaf }:
+
+buildDunePackage rec {
+  pname = "angstrom";
+  version = "0.10.0";
+
+  minimumOCamlVersion = "4.03";
+
+  src = fetchFromGitHub {
+    owner  = "inhabitedtype";
+    repo   = pname;
+    rev    = version;
+    sha256 = "0lh6024yf9ds0nh9i93r9m6p5psi8nvrqxl5x7jwl13zb0r9xfpw";
+  };
+
+  buildInputs = [ alcotest ];
+  propagatedBuildInputs = [ bigstringaf result ];
+  doCheck = true;
+
+  meta = {
+    homepage = https://github.com/inhabitedtype/angstrom;
+    description = "OCaml parser combinators built for speed and memory efficiency";
+    license = stdenv.lib.licenses.bsd3;
+    maintainers = with stdenv.lib.maintainers; [ sternenseemann ];
+  };
+}
+ </programlisting>
+
+ <para>
+   Here is a second example, this time using a source archive generated with
+   <literal>dune-release</literal>. The <literal>unpackCmd</literal>
+   redefinition is necessary to be able to unpack the kind of tarball that
+   <literal>dune-release</literal> generates. This library does not depend
+   on any other OCaml library and no tests are run after building it.
+ </para>
+
+ <programlisting>
+{ stdenv, fetchurl, buildDunePackage }:
+
+buildDunePackage rec {
+  pname = "wtf8";
+  version = "1.0.1";
+
+  minimumOCamlVersion = "4.01";
+
+  src = fetchurl {
+    url = "https://github.com/flowtype/ocaml-${pname}/releases/download/v${version}/${pname}-${version}.tbz";
+    sha256 = "1msg3vycd3k8qqj61sc23qks541cxpb97vrnrvrhjnqxsqnh6ygq";
+  };
+
+  unpackCmd = "tar xjf $src";
+
+  meta = with stdenv.lib; {
+    homepage = https://github.com/flowtype/ocaml-wtf8;
+    description = "WTF-8 is a superset of UTF-8 that allows unpaired surrogates.";
+    license = licenses.mit;
+    maintainers = [ maintainers.eqyiel ];
+  };
+}
+ </programlisting>
+
+</section>