From a4e708522768a30cd5120a65c979c87abd525336 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Tue, 20 Apr 2021 13:46:53 +0200
Subject: stdenv.mkDerivation: Allow overriding of recursive definitions

See updated manual for further explanation.
---
 doc/stdenv/meta.chapter.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

(limited to 'doc/stdenv/meta.chapter.md')

diff --git a/doc/stdenv/meta.chapter.md b/doc/stdenv/meta.chapter.md
index d3e1dd5b27d82..5f3e12ba00412 100644
--- a/doc/stdenv/meta.chapter.md
+++ b/doc/stdenv/meta.chapter.md
@@ -175,6 +175,36 @@ The NixOS tests are available as `nixosTests` in parameters of derivations. For
 
 NixOS tests run in a VM, so they are slower than regular package tests. For more information see [NixOS module tests](https://nixos.org/manual/nixos/stable/#sec-nixos-tests).
 
+Alternatively, you can specify other derivations as tests. You can make use of
+the optional parameter (here: `self`) to inject the correct package without
+relying on non-local definitions, even in the presence of `overrideAttrs`. This
+definition of `tests` does not rely on the original `mypkg` or overrides it in
+all places.
+
+```nix
+# my-package/default.nix
+{ stdenv, callPackage }:
+stdenv.mkDerivation (self: {
+  # ...
+  passthru.tests.example = callPackage ./example.nix { my-package = self; };
+})
+```
+
+```nix
+# my-package/example.nix
+{ runCommand, lib, my-package, ... }:
+runCommand "my-package-test" {
+  nativeBuildInputs = [ my-package ];
+  src = lib.sources.sourcesByRegex ./. [ ".*.in" ".*.expected" ];
+} ''
+  my-package --help
+  my-package <example.in >example.actual
+  diff -U3 --color=auto example.expected example.actual
+  mkdir $out
+''
+```
+
+
 ### `timeout` {#var-meta-timeout}
 
 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 `nixpkgs`.
-- 
cgit 1.4.1