08/11: gnu: base: Add cautionary comments for canonical-package, %final-inputs usage.

[guix-commits]

apteryx pushed a commit to branch wip-cu-switch-to-pkgconf
in repository guix.

commit 70ba80160d870df196c087ec0224c8e07ebd52c5
Author: Maxim Cournoyer <maxim.cournoyer@gmail.com>
AuthorDate: Thu Feb 1 12:51:07 2024 -0500

    gnu: base: Add cautionary comments for canonical-package, %final-inputs 
usage.
    
    * gnu/packages/base.scm (canonical-package, %final-inputs): Add comments.
    
    Change-Id: I8b2f5802127dbde169850a7931a64fb5eb503b7c
---
 gnu/packages/base.scm | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/gnu/packages/base.scm b/gnu/packages/base.scm
index deda116964..cffc99d4cc 100644
--- a/gnu/packages/base.scm
+++ b/gnu/packages/base.scm
@@ -82,6 +82,10 @@
             libc-utf8-locales-for-target
             make-ld-wrapper
             libiconv-if-needed
+
+            ;; Beware: the following should not be used the top level to avoid
+            ;; introducing circular module dependencies.
+            canonical-package
             %final-inputs))
 
 ;;; Commentary:
@@ -1720,12 +1724,18 @@ package needs iconv ,@(libiconv-if-needed) should be 
added."
       (list libiconv)
       '()))
 
-(define-public (canonical-package package)
+;;; Beware: canonical-package should not be used at the top level, to avoid
+;;; eagerly resolving (gnu packages commencement), which would introduce
+;;; circular module dependencies.
+(define (canonical-package package)
   ;; Avoid circular dependency by lazily resolving 'commencement'.
   (let* ((iface (resolve-interface '(gnu packages commencement)))
          (proc  (module-ref iface 'canonical-package)))
     (proc package)))
 
+;;; Beware: %final-inputs should not be used at the top level, to avoid
+;;; eagerly resolving (gnu packages commencement), which would introduce
+;;; circular module dependencies.
 (define* (%final-inputs #:optional (system (%current-system)))
   "Return the list of \"final inputs\"."
   ;; Avoid circular dependency by lazily resolving 'commencement'.