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 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'.