Merge master into staging-next

6 files changed, 168 insertions, 27 deletions

diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml
index f22984cb56b0a..ac0ad7125324c 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 0000000000000..d1c29c72f7260
--- /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>
diff --git a/doc/languages-frameworks/python.section.md b/doc/languages-frameworks/python.section.md
index 857463c578795..81ce4d94ad21c 100644
--- a/doc/languages-frameworks/python.section.md
+++ b/doc/languages-frameworks/python.section.md
@@ -483,12 +483,12 @@ and in this case the `python35` interpreter is automatically used.
 
 ### Interpreters
 
-Versions 2.7, 3.4, 3.5, 3.6 and 3.7 of the CPython interpreter are available as
-respectively `python27`, `python34`, `python35`, `python36` and `python37`. The PyPy interpreter
-is available as `pypy`. The aliases `python2` and `python3` correspond to respectively `python27` and
-`python37`. The default interpreter, `python`, maps to `python2`.
-The Nix expressions for the interpreters can be found in
-`pkgs/development/interpreters/python`.
+Versions 2.7, 3.5, 3.6 and 3.7 of the CPython interpreter are available as
+respectively `python27`, `python35`, `python36` and `python37`. The PyPy
+interpreter is available as `pypy`. The aliases `python2` and `python3`
+correspond to respectively `python27` and `python37`. The default interpreter,
+`python`, maps to `python2`. The Nix expressions for the interpreters can be
+found in `pkgs/development/interpreters/python`.
 
 All packages depending on any Python interpreter get appended
 `out/{python.sitePackages}` to `$PYTHONPATH` if such directory
@@ -507,7 +507,7 @@ Each interpreter has the following attributes:
 - `buildEnv`. Function to build python interpreter environments with extra packages bundled together. See section *python.buildEnv function* for usage and documentation.
 - `withPackages`. Simpler interface to `buildEnv`. See section *python.withPackages function* for usage and documentation.
 - `sitePackages`. Alias for `lib/${libPrefix}/site-packages`.
-- `executable`. Name of the interpreter executable, e.g. `python3.4`.
+- `executable`. Name of the interpreter executable, e.g. `python3.7`.
 - `pkgs`. Set of Python packages for that specific interpreter. The package set can be modified by overriding the interpreter and passing `packageOverrides`.
 
 ### Building packages and applications
@@ -529,7 +529,6 @@ attribute set is created for each available Python interpreter. The available
 sets are
 
 * `pkgs.python27Packages`
-* `pkgs.python34Packages`
 * `pkgs.python35Packages`
 * `pkgs.python36Packages`
 * `pkgs.python37Packages`
@@ -837,7 +836,7 @@ community to help save time. No tool is preferred at the moment.
 
 ### Deterministic builds
 
-Python 2.7, 3.5 and 3.6 are now built deterministically and 3.4 mostly.
+The Python interpreters are now built deterministically.
 Minor modifications had to be made to the interpreters in order to generate
 deterministic bytecode. This has security implications and is relevant for
 those using Python in a `nix-shell`.
diff --git a/doc/meta.xml b/doc/meta.xml
index 496b32916552b..51c7b2dfc88f0 100644
--- a/doc/meta.xml
+++ b/doc/meta.xml
@@ -252,6 +252,61 @@ meta.platforms = stdenv.lib.platforms.linux;
    </varlistentry>
    <varlistentry>
     <term>
+     <varname>tests</varname>
+    </term>
+    <listitem>
+     <para>
+      An attribute set with as values tests. A test is a derivation, which
+      builds successfully when the test passes, and fails to build otherwise. A
+      derivation that is a test requires some <literal>meta</literal> elements
+      to be defined: <literal>needsVMSupport</literal> (automatically filled-in
+      for NixOS tests) and <literal>timeout</literal>.
+     </para>
+     <para>
+      The NixOS tests are available as <literal>nixosTests</literal> in
+      parameters of derivations. For instance, the OpenSMTPD derivation
+      includes lines similar to:
+<programlisting>
+{ /* ... */, nixosTests }:
+{
+  # ...
+  meta.tests = {
+    basic-functionality-and-dovecot-integration = nixosTests.opensmtpd;
+  };
+}
+</programlisting>
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <varname>timeout</varname>
+    </term>
+    <listitem>
+     <para>
+      A timeout (in seconds) for building the derivation. If the derivation
+      takes longer than this time to build, it can fail due to breaking the
+      timeout. However, all computers do not have the same computing power,
+      hence some builders may decide to apply a multiplicative factor to this
+      value. When filling this value in, try to keep it approximately
+      consistent with other values already present in
+      <literal>nixpkgs</literal>.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <varname>needsVMSupport</varname>
+    </term>
+    <listitem>
+     <para>
+      A boolan that states whether the derivation requires build-time support
+      for Virtual Machine to build successfully.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
      <varname>hydraPlatforms</varname>
     </term>
     <listitem>
diff --git a/doc/quick-start.xml b/doc/quick-start.xml
index b9e6d789404a8..8dd673ed2733f 100644
--- a/doc/quick-start.xml
+++ b/doc/quick-start.xml
@@ -147,8 +147,8 @@ $ git add pkgs/development/libraries/libfoo/default.nix</screen>
       </listitem>
       <listitem>
        <para>
-        You can use <command>nix-prefetch-url</command> (or similar
-        nix-prefetch-git, etc) <replaceable>url</replaceable> to get the
+        You can use <command>nix-prefetch-url</command>
+        <replaceable>url</replaceable> to get the
         SHA-256 hash of source distributions. There are similar commands as
         <command>nix-prefetch-git</command> and
         <command>nix-prefetch-hg</command> available in
diff --git a/doc/stdenv.xml b/doc/stdenv.xml
index b2f30bf08db12..ef45ec301a6b4 100644
--- a/doc/stdenv.xml
+++ b/doc/stdenv.xml
@@ -618,7 +618,7 @@ let f(h, h + 1, i) = i + h
   </variablelist>
 
   <variablelist>
-   <title>Variables affecting build properties</title>
+   <title>Attributes affecting build properties</title>
    <varlistentry>
     <term>
      <varname>enableParallelBuilding</varname>
@@ -637,21 +637,6 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
-    <term>
-     <varname>preferLocalBuild</varname>
-    </term>
-    <listitem>
-     <para>
-      If set, specifies that the package is so lightweight in terms of build
-      operations (e.g. write a text file from a Nix string to the store) that
-      there's no need to look for it in binary caches -- it's faster to just
-      build it locally. It also tells Hydra and other facilities that this
-      package doesn't need to be exported in binary caches (noone would use it,
-      after all).
-     </para>
-    </listitem>
-   </varlistentry>
   </variablelist>
 
   <variablelist>