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

* gnu/packages/base.scm (canonical-package, %final-inputs): Add comments.

Change-Id: I8b2f5802127dbde169850a7931a64fb5eb503b7c

1 files changed, 11 insertions, 1 deletions

diff --git a/gnu/packages/base.scm b/gnu/packages/base.scm
index 42d585de9b..0c4a9a08ed 100644
--- a/gnu/packages/base.scm
+++ b/gnu/packages/base.scm
@@ -84,6 +84,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:
@@ -1778,12 +1782,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'.