Merge pull request #2524 from domenkozar/deprecate-toPath

Deprecate builtins.toPath

doc/manual/expressions/builtins.xml

@@ -1077,22 +1077,8 @@ Evaluates to <literal>[ "foo" ]</literal>.
     <replaceable>path</replaceable></term>
 
     <listitem><para>Return <literal>true</literal> if the path
-    <replaceable>path</replaceable> exists, and
+    <replaceable>path</replaceable> exists at evaluation time, and
-    <literal>false</literal> otherwise.  One application of this
+    <literal>false</literal> otherwise.
-    function is to conditionally include a Nix expression containing
-    user configuration:
-
-<programlisting>
-let
-  fileName = builtins.getEnv "CONFIG_FILE";
-  config =
-    if fileName != "" &amp;&amp; builtins.pathExists (builtins.toPath fileName)
-    then import (builtins.toPath fileName)
-    else { someSetting = false; }; <lineannotation># default configuration</lineannotation>
-in config.someSetting</programlisting>
-
-    (Note that <envar>CONFIG_FILE</envar> must be an absolute path for
-    this to work.)</para></listitem>
 
   </varlistentry>
 
@@ -1409,13 +1395,10 @@ in foo</programlisting>
   <varlistentry xml:id='builtin-toPath'>
     <term><function>builtins.toPath</function> <replaceable>s</replaceable></term>
 
-    <listitem><para>Convert the string value
+    <listitem><para> DEPRECATED. Use <literal>/. + "/path"</literal>
-    <replaceable>s</replaceable> into a path value.  The string
+    to convert a string into an absolute path. For relative paths,
-    <replaceable>s</replaceable> must represent an absolute path
+    use <literal>./. + "/path"</literal>.
-    (i.e., must start with <literal>/</literal>).  The path need not
+    </para></listitem>
-    exist.  The resulting path is canonicalised, e.g.,
-    <literal>builtins.toPath "//foo/xyzzy/../bar/"</literal> returns
-    <literal>/foo/bar</literal>.</para></listitem>
 
   </varlistentry>