From 444c2b6dd06e02f4bd8f153fb6a574e2350d861f Mon Sep 17 00:00:00 2001
From: Doron Behar <doron.behar@gmail.com>
Date: Wed, 29 May 2024 15:29:39 +0300
Subject: [PATCH] doc/meta: Mention --version as a good usecase for
 installCheckPhase

---
 doc/stdenv/meta.chapter.md | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/doc/stdenv/meta.chapter.md b/doc/stdenv/meta.chapter.md
index f9044fdfc9d2..e2a5a5c31a6e 100644
--- a/doc/stdenv/meta.chapter.md
+++ b/doc/stdenv/meta.chapter.md
@@ -129,9 +129,29 @@ Note that Hydra and [`nixpkgs-review`](https://github.com/Mic92/nixpkgs-review)
 
 #### Package tests {#var-meta-tests-packages}
 
-Tests that are part of the source package are often executed in the `installCheckPhase`.
+Tests that are part of the source package are often executed in the `installCheckPhase`. This phase is also suitable for performing a `--version` test for packages that support such flag. Here's an example:
 
-Prefer `passthru.tests` for tests that are introduced in nixpkgs because:
+```nix
+# Say the package is git
+stdenv.mkDerivation(finalAttrs: {
+  pname = "git";
+  version = "...";
+  # ...
+
+  doInstallCheck = true;
+  installCheckPhase = ''
+    runHook preInstallCheck
+
+    echo checking if 'git --version' mentions ${finalAttrs.version}
+    $out/bin/git --version | grep ${finalAttrs.version}
+
+    runHook postInstallCheck
+  '';
+  # ...
+})
+```
+
+Most programs distributed by Nixpkgs support such a `--version` flag, and it can help give confidence that the package at least got compiled properly. However, tests that are slightly non trivial will better fit into `passthru.tests`, because:
 
 * `passthru.tests` tests the 'real' package, independently from the environment in which it was built
 * We can run and debug a `passthru.tests` independently, after the package was built (useful if it takes a long time).