From: Maxim Cournoyer <maxim.cournoyer@gmail.com>
To: 65860@debbugs.gnu.org
Cc: "Maxim Cournoyer" <maxim.cournoyer@gmail.com>,
"Maxim Cournoyer" <maxim.cournoyer@gmail.com>,
"Ludovic Courtès" <ludo@gnu.org>
Subject: [bug#65860] [PATCH v2 3/3] doc: Add new 'Circular Module Dependencies' section.
Date: Sun, 17 Sep 2023 20:43:10 -0400 [thread overview]
Message-ID: <c2b54357d9f705ce0d561f660139b7e7570f195e.1694997755.git.maxim.cournoyer@gmail.com> (raw)
In-Reply-To: <cover.1694997755.git.maxim.cournoyer@gmail.com>
* doc/contributing.texi (Circular Module Dependencies): New subsection.
---
(no changes since v1)
doc/contributing.texi | 56 +++++++++++++++++++++++++++++++++++++++++++
1 file changed, 56 insertions(+)
diff --git a/doc/contributing.texi b/doc/contributing.texi
index 156a6cb19e1..d99751f42cb 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -513,6 +513,7 @@ Packaging Guidelines
* Version Numbers:: When the name is not enough.
* Synopses and Descriptions:: Helping users find the right package.
* Snippets versus Phases:: Whether to use a snippet, or a build phase.
+* Cyclic Module Dependencies:: Going full circle.
* Emacs Packages:: Your Elisp fix.
* Python Modules:: A touch of British comedy.
* Perl Modules:: Little pearls.
@@ -784,6 +785,61 @@ Snippets versus Phases
using build phases. Refer to the @code{origin} record documentation for
more information (@pxref{origin Reference}).
+@node Cyclic Module Dependencies
+@subsection Cyclic Module Dependencies
+
+While there cannot be circular dependencies between packages, Guile's
+lax module loading mechanism allows circular dependencies between Guile
+modules, which doesn't cause problems as long as the following
+conditions are followed for two modules part of a dependency cycle:
+
+@cindex rules to cope with circular module dependencies
+@enumerate
+@item
+Macros are not shared between the co-dependent modules
+@item
+Top-level variables are only referenced in delayed (@i{thunked}) package
+fields: @code{arguments}, @code{native-inputs}, @code{inputs},
+@code{propagated-inputs} or @code{replacement}
+@item
+Procedures referencing top-level variables from another module are not
+called at the top level of a module themselves.
+@end enumerate
+
+Straying away from the above rules may work while there are no
+dependency cycles between modules, but given such cycles are confusing
+and difficult to troubleshoot, it is best to follow the rules to avoid
+introducing problems down the line.
+
+@noindent
+Here is a common trap to avoid:
+
+@lisp
+(define-public avr-binutils
+ (package
+ (inherit (cross-binutils "avr"))
+ (name "avr-binutils")))
+@end lisp
+
+In the above example, the @code{avr-binutils} package was defined in the
+module @code{(gnu packages avr)}, and the @code{cross-binutils}
+procedure in @code{(gnu packages cross-base)}. Because the
+@code{inherit} field is not delayed (thunked), it is evaluated at the
+top level at load time, which is problematic in the presence of module
+dependency cycles. This could be resolved by turning the package into a
+procedure instead, like:
+
+@lisp
+(define (make-avr-binutils)
+ (package
+ (inherit (cross-binutils "avr"))
+ (name "avr-binutils")))
+@end lisp
+
+Care would need to be taken to ensure the above procedure is only ever
+used in a package delayed fields or within another procedure also not
+called at the top level.
+
@node Emacs Packages
@subsection Emacs Packages
--
2.41.0
prev parent reply other threads:[~2023-09-18 0:45 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-09-11 4:19 [bug#65860] [PATCH 0/4] Resolve a circular module dependencies in embedded modules Maxim Cournoyer
2023-09-18 0:43 ` [bug#65860] [PATCH v2 0/3] " Maxim Cournoyer
2023-09-18 0:43 ` [bug#65860] [PATCH v2 1/3] gnu: avr: Delay all cross compilation packages Maxim Cournoyer
2023-09-18 0:43 ` [bug#65860] [PATCH v2 2/3] gnu: embedded: Turn packages using top-level variables into procedures Maxim Cournoyer
2023-09-18 0:43 ` Maxim Cournoyer [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://guix.gnu.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=c2b54357d9f705ce0d561f660139b7e7570f195e.1694997755.git.maxim.cournoyer@gmail.com \
--to=maxim.cournoyer@gmail.com \
--cc=65860@debbugs.gnu.org \
--cc=ludo@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/guix.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).