06/06: packages: Recommend against the use of 'package-file'.

[guix-commits]

civodul pushed a commit to branch master
in repository guix.

commit c8d8f6160e7b4d3df7b006b35ba0f4e74b9b90fb
Author: Ludovic Courtès <address@hidden>
AuthorDate: Mon Apr 20 23:37:05 2020 +0200

    packages: Recommend against the use of 'package-file'.
    
    * guix/packages.scm (package-file): Recommend against its use in the
    docstring.
    * doc/guix.texi (The Store Monad): Likewise.
---
 doc/guix.texi     | 4 ++++
 guix/packages.scm | 6 +++++-
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index d2cd115..a79bbfc 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -7483,6 +7483,10 @@ value in the absolute file name of @var{file} within the 
@var{output}
 directory of @var{package}.  When @var{file} is omitted, return the name
 of the @var{output} directory of @var{package}.  When @var{target} is
 true, use it as a cross-compilation target triplet.
+
+Note that this procedure does @emph{not} build @var{package}.  Thus, the
+result might or might not designate an existing file.  We recommend not
+using this procedure unless you know what you are doing.
 @end deffn
 
 @deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
diff --git a/guix/packages.scm b/guix/packages.scm
index 6c6a06e..2fa4fd0 100644
--- a/guix/packages.scm
+++ b/guix/packages.scm
@@ -1340,7 +1340,11 @@ code of derivations to GUILE, a package object."
   "Return as a monadic value the absolute file name of FILE within the
 OUTPUT directory of PACKAGE.  When FILE is omitted, return the name of the
 OUTPUT directory of PACKAGE.  When TARGET is true, use it as a
-cross-compilation target triplet."
+cross-compilation target triplet.
+
+Note that this procedure does _not_ build PACKAGE.  Thus, the result might or
+might not designate an existing file.  We recommend not using this procedure
+unless you know what you are doing."
   (lambda (store)
     (define compute-derivation
       (if target