Merge pull request #44439 from Ekleog/meta-tests

[RFC] Use `meta.tests` to link from packages to the tests that test them

1 files changed, 55 insertions, 0 deletions

diff --git a/doc/meta.xml b/doc/meta.xml
index 496b32916552..51c7b2dfc88f 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>