From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.migadu.com ([2001:41d0:306:2d92::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms9.migadu.com with LMTPS id jYJlJ4ydB2XgAgAAauVa8A:P1 (envelope-from ) for ; Mon, 18 Sep 2023 02:45:00 +0200 Received: from aspmx1.migadu.com ([2001:41d0:306:2d92::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id jYJlJ4ydB2XgAgAAauVa8A (envelope-from ) for ; Mon, 18 Sep 2023 02:45:00 +0200 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 669EB30888 for ; Mon, 18 Sep 2023 02:45:00 +0200 (CEST) Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20230601 header.b=MXwB1Cyi; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org"; dmarc=fail reason="SPF not aligned (relaxed)" header.from=gmail.com (policy=none) ARC-Seal: i=1; s=key1; d=yhetil.org; t=1694997900; a=rsa-sha256; cv=none; b=R79Q649NG4ixnqlDlg1niiKDTnP49HER7J4LfvwUrNOQjgsjbKh0lOHmW8G5c2U7p6TjPI K58EiF7yfs+36kqz/0lpzYdAGTpfrCe9tdANetWXkwTMXIKuN+FCMXws5VTCH1HgoPl9Qs 4bcDotr/FT9hJci6C5ej1GUqg0icE5jmlfBMPBWWINIKn8+CmRj5Oqg6SfsKTwyp5VSgxq vb/1QuBCYQ1iiyEDeLCnOvLG/jyv1PPsj+SE3tntQaGVBl0CiQpPrBQNqaUh+d00AlsZAI bla8xQUl1RrkKAXMkuKJRaz/z6oATVk50ssda6+q2i6ovlBZX+wPHQJkjHGX3g== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1694997900; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding:resent-cc: resent-from:resent-sender:resent-message-id:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=CmoiUvwzRQcw75LFnEMihCQ967PVYN5TYCCEpNfllyQ=; b=tnuBWuHu1VFu9hT4lDAKFm9CtSXbD63vIaNd+sUkzs4E5SicvVTXPLvmYzHD+n0hjfverw qQobohlS98tgHFtIi8DPvl7mzL+MTw6nofN9oUKjsv8kwNiX+NrS5KkRKo4GTnzEfmwzOR cEE9XmpyVKAVw8xePLyILFNfF9q8BfMRv6N+eOceVZ5E+52J+pn5KuI1fJkeg7zy3Da2jo DgaL+GyiKM0Gz2PCBSofH9QmQPvYAQzsTqpyRKoe/evb8uj9VnAjKPVs3QnFPZB1yceVkh /82QX4zXlK2yLRIB8fUzHaZuuLMadKJduVNQODe8WptcYE2U2XfRNFHwMt5hsw== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20230601 header.b=MXwB1Cyi; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org"; dmarc=fail reason="SPF not aligned (relaxed)" header.from=gmail.com (policy=none) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qi2Nj-0003ym-Rg; Sun, 17 Sep 2023 20:44:55 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qi2Ni-0003yW-9N for guix-patches@gnu.org; Sun, 17 Sep 2023 20:44:54 -0400 Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qi2Ni-0001Gc-0r; Sun, 17 Sep 2023 20:44:54 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1qi2Np-0001rc-ST; Sun, 17 Sep 2023 20:45:01 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#65860] [PATCH v2 3/3] doc: Add new 'Circular Module Dependencies' section. Resent-From: Maxim Cournoyer Original-Sender: "Debbugs-submit" Resent-CC: maxim.cournoyer@gmail.com, ludo@gnu.org, guix-patches@gnu.org Resent-Date: Mon, 18 Sep 2023 00:45:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 65860 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 65860@debbugs.gnu.org Cc: Maxim Cournoyer , Maxim Cournoyer , Ludovic =?UTF-8?Q?Court=C3=A8s?= X-Debbugs-Original-Xcc: Maxim Cournoyer , Ludovic =?UTF-8?Q?Court=C3=A8s?= Received: via spool by 65860-submit@debbugs.gnu.org id=B65860.16949978457063 (code B ref 65860); Mon, 18 Sep 2023 00:45:01 +0000 Received: (at 65860) by debbugs.gnu.org; 18 Sep 2023 00:44:05 +0000 Received: from localhost ([127.0.0.1]:51678 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qi2Mu-0001pq-Tv for submit@debbugs.gnu.org; Sun, 17 Sep 2023 20:44:05 -0400 Received: from mail-qt1-x830.google.com ([2607:f8b0:4864:20::830]:52569) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qi2Mp-0001oS-2S for 65860@debbugs.gnu.org; Sun, 17 Sep 2023 20:43:59 -0400 Received: by mail-qt1-x830.google.com with SMTP id d75a77b69052e-414b3b65e85so26094361cf.1 for <65860@debbugs.gnu.org>; Sun, 17 Sep 2023 17:43:51 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1694997825; x=1695602625; darn=debbugs.gnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=CmoiUvwzRQcw75LFnEMihCQ967PVYN5TYCCEpNfllyQ=; b=MXwB1CyiNaRJS2I7jRbMRjubw5LtPECa4COl6CnMqRSKV/jWhkGjLoRnwI2AP8aP/2 yGDT5sMUjkWt+OowRx6hm2p/V3Whwd7Mr/0onn81mGJLBKx+h29LNcxxk0gujryPNrGO LGLcGtLzI95O3TKu0i3UJ3kJDrrEW8epaE2yzV6YqR7wX2Tn6TT6JQbjDnbN0oSnuzXJ jBgM6vPTZLHMF/9x2ItdhOi+yxPDTiClp+STq53z720Jg8GwtGNk/x44rQv7t4N7cmWv vAnS6Ft0QDHivDG2Jguh2S5vUTKf/L7JspjaWzq+wAN80xfUW5Gkc7Qjs12b4gPjaNrn YtXg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1694997825; x=1695602625; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=CmoiUvwzRQcw75LFnEMihCQ967PVYN5TYCCEpNfllyQ=; b=PMePR/nRBG8uH2pSK58mLh65/RXlO8P5djDvT2qbLGjpsViRosnnPU4bnKBAMjityp hVl1040V13HhgNc5u0LPpBWqmkKsIrWQHQgN5I3T2FlcE7CBFrMd5Z+GNGI+38qMUwRj 250ACC9PQehY1wV6NF/p0ouagS/KP5OT468tgZSbkbvVSQau16HQB30ag1zOJvIhd0l5 762ZJj6/dpH6996C/ejYGXP8TXmEzOYFCtA3tBNoOFs10ZL8LPwlzVd5EamYWRG9+mm1 L0ZsxMWiZyuu7VR0L3VgS8U2JMjs+57CWF6KZm9z1NPVzxOlgIjOIlLNvTWWSaW/ZKW3 aglA== X-Gm-Message-State: AOJu0YyxP+LARLi73QJyhVVwqvLkc2UyGxfeZ9hL9DsfP+h/0d5CH3fF w5aCLa3X52PbzbJMLfmn9gwJpjl2IrQ= X-Google-Smtp-Source: AGHT+IEdp9W6knVZwnemWm9ChAwDia54Q9PJAZaKJVB6Lnd51FF3y9x9FgrIoxmWjy7Gi+2kfHr3HA== X-Received: by 2002:a05:622a:50f:b0:411:5528:64f6 with SMTP id l15-20020a05622a050f00b00411552864f6mr9060870qtx.27.1694997825336; Sun, 17 Sep 2023 17:43:45 -0700 (PDT) Received: from localhost.localdomain (dsl-10-149-131.b2b2c.ca. [72.10.149.131]) by smtp.gmail.com with ESMTPSA id cr8-20020a05622a428800b00403f1a7be90sm2662547qtb.88.2023.09.17.17.43.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 17 Sep 2023 17:43:44 -0700 (PDT) From: Maxim Cournoyer Date: Sun, 17 Sep 2023 20:43:10 -0400 Message-ID: X-Mailer: git-send-email 2.41.0 In-Reply-To: References: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+larch=yhetil.org@gnu.org Sender: guix-patches-bounces+larch=yhetil.org@gnu.org X-Migadu-Flow: FLOW_IN X-Migadu-Country: US X-Migadu-Spam-Score: -3.10 X-Spam-Score: -3.10 X-Migadu-Queue-Id: 669EB30888 X-Migadu-Scanner: mx2.migadu.com X-TUID: VmNXVEgrGzXY * 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