builtins: fix builtins.langVersion docs to state it's deprecated

This builtin was always a problem and nixpkgs uses it in exactly one
place, to give up if the Nix version is absurdly old. It has no other
use cases, and doesn't work in a multi-implementation world anyway.

Change-Id: I03c36e118591029e2ef14b091fe14a311c66a08a

2 files changed, 29 insertions, 14 deletions

diff --git a/doc/manual/rl-next/nixversion-fake.md b/doc/manual/rl-next/nixversion-fake.md
index 93f75611d..725b8e609 100644
--- a/doc/manual/rl-next/nixversion-fake.md
+++ b/doc/manual/rl-next/nixversion-fake.md
@@ -1,13 +1,17 @@
 ---
-synopsis: "`builtins.nixVersion` now returns a fixed value \"2.18.3-lix\""
-cls: 558
+synopsis: "`builtins.nixVersion` and `builtins.langVersion` return fixed values"
+cls: [558, 1144]
 credits: jade
 category: Breaking Changes
 ---
 
-`builtins.nixVersion` now returns a fixed value `"2.18.3-lix"`. This prevents
-feature detection assuming that features that exist in Nix post-Lix-branch-off
-might exist, even though the Lix version is greater than the Nix version.
+`builtins.nixVersion` now returns a fixed value `"2.18.3-lix"`.
+
+`builtins.langVersion` returns a fixed value `6`, matching CppNix 2.18.
+
+This prevents feature detection assuming that features that exist in Nix
+post-Lix-branch-off might exist, even though the Lix version is greater than
+the Nix version.
 
 In the future, check for builtins for feature detection. If a feature cannot be
 detected by *those* means, please file a Lix bug.
diff --git a/src/libexpr/primops.cc b/src/libexpr/primops.cc
index 33a2688f1..e36b800c3 100644
--- a/src/libexpr/primops.cc
+++ b/src/libexpr/primops.cc
@@ -4355,10 +4355,13 @@ void EvalState::createBaseEnv()
         .doc = R"(
           Legacy version of Nix. Always returns "2.18.3-lix" on Lix.
 
-          To determine if features exist, Nix scripts should instead use direct
-          means of feature detection, such as checking for existence of
-          builtins they want to use. Doing so allows for much better compatibility
-          across implementations.
+          Code in the Nix language should use other means of feature detection
+          like detecting the presence of builtins, rather than trying to find
+          the version of the Nix implementation, as there may be other Nix
+          implementations with different feature combinations.
+
+          If the feature you want to write compatibility code for cannot be
+          detected by any means, please file a Lix bug.
         )",
     });
 
@@ -4377,15 +4380,23 @@ void EvalState::createBaseEnv()
         )",
     });
 
-    /* Language version.  This should be increased every time a new
-       language feature gets added.  It's not necessary to increase it
-       when primops get added, because you can just use `builtins ?
-       primOp' to check. */
+    /* Legacy language version.
+     * This is fixed at 6, and will never change in the future on Lix.
+     * A better language versioning construct needs to be built instead. */
     v.mkInt(6);
     addConstant("__langVersion", v, {
         .type = nInt,
         .doc = R"(
-          The current version of the Nix language.
+          The legacy version of the Nix language. Always is `6` on Lix,
+          matching Nix 2.18.
+
+          Code in the Nix language should use other means of feature detection
+          like detecting the presence of builtins, rather than trying to find
+          the version of the Nix implementation, as there may be other Nix
+          implementations with different feature combinations.
+
+          If the feature you want to write compatibility code for cannot be
+          detected by any means, please file a Lix bug.
         )",
     });