From unknown Mon Aug 18 08:27:48 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#69587 <69587@debbugs.gnu.org> To: bug#69587 <69587@debbugs.gnu.org> Subject: Status: [PATCH] doc: Add =?UTF-8?Q?=E2=80=9CSource?= Tree =?UTF-8?Q?Structure=E2=80=9D?= section. Reply-To: bug#69587 <69587@debbugs.gnu.org> Date: Mon, 18 Aug 2025 15:27:48 +0000 retitle 69587 [PATCH] doc: Add =E2=80=9CSource Tree Structure=E2=80=9D sect= ion. reassign 69587 guix-patches submitter 69587 Ludovic Court=C3=A8s severity 69587 normal tag 69587 patch thanks From debbugs-submit-bounces@debbugs.gnu.org Wed Mar 06 11:38:39 2024 Received: (at submit) by debbugs.gnu.org; 6 Mar 2024 16:38:39 +0000 Received: from localhost ([127.0.0.1]:51296 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rhuHs-0003DX-H8 for submit@debbugs.gnu.org; Wed, 06 Mar 2024 11:38:39 -0500 Received: from lists.gnu.org ([209.51.188.17]:45338) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rhuHo-0003DK-7R for submit@debbugs.gnu.org; Wed, 06 Mar 2024 11:38:35 -0500 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 1rhuHI-0001cz-Lk for guix-patches@gnu.org; Wed, 06 Mar 2024 11:38:00 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rhuHG-00014F-KB; Wed, 06 Mar 2024 11:37:58 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:Subject:To:From:in-reply-to: references; bh=MRlivkXSHLGcv1R/ZMqxmB7AGPEO1DxleYzBxawjSLg=; b=DWL6SBtM7cQE6n 6LkXR9rdpJpOx4lQhcXUUaeJTA7p/sCm4AItP9C2Q3ijSnVEV5QvyHD8lKGoa7itFWw4aKxkaGp6C bCl11NDgtDtrkaKCQTw/GxFuB/VXrSsMwm/fheiWvy/ae3cajdWIzKqYUfLSrJPehY2FzA3W1aTqB d+ITAZgLovqcoBCeo5C64L0NlEFHCHf3vYWh23MbCgMwrimvbiPUrqd+t9pOzexsmkoH6Foe2kHBT mVmGok7LCa3w6zfsd1XWCAnvDiHkf5IekpeL+ypewAnquCvqncb2U0LWgc5fXd6MrnBBtMki1JQZo uabO2fMwHvHfFVfSDfvw==; From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= To: guix-patches@gnu.org Subject: [PATCH] =?UTF-8?q?doc:=20Add=20=E2=80=9CSource=20Tree=20Structure?= =?UTF-8?q?=E2=80=9D=20section.?= Date: Wed, 6 Mar 2024 17:37:47 +0100 Message-ID: X-Mailer: git-send-email 2.41.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: submit Cc: =?UTF-8?q?Ludovic=20Court=C3=A8s?= X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) * doc/contributing.texi (Source Tree Structure): New node. * doc/guix.texi (Programming Interface): Add cross-reference. Change-Id: I141a1f4d806ae5f72c7a246e18c14dc63056a607 --- doc/contributing.texi | 235 +++++++++++++++++++++++++++++++++++++++++- doc/guix.texi | 3 +- 2 files changed, 236 insertions(+), 2 deletions(-) Hello there! This is a long overdue section for contributors, very much inspired by Josselin's talk last year: https://10years.guix.gnu.org/video/guixy-guile-the-derivation-factory-a-tour-of-the-guix-source-tree/ Thoughts? Ludo'. diff --git a/doc/contributing.texi b/doc/contributing.texi index a7d91724fb..ff7065ad2a 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -23,7 +23,8 @@ Contributing * Building from Git:: The latest and greatest. * Running Guix Before It Is Installed:: Hacker tricks. * The Perfect Setup:: The right tools. -* Alternative Setups:: Other posible tools that do the job. +* Alternative Setups:: Other possible tools that do the job. +* Source Tree Structure:: Source code guided tour. * Packaging Guidelines:: Growing the distribution. * Coding Style:: Hygiene of the contributor. * Submitting Patches:: Share your work. @@ -546,6 +547,238 @@ Vim and NeoVim process and inject your code there live (sadly it's not packaged in Guix yet). +@node Source Tree Structure +@section Source Tree Structure + +@cindex structure, of the source tree +Now that we're all set, let's look at the source tree. Overall, the +Guix source tree contains almost exclusively Guile @dfn{modules}, each +of which can be seen as an independent library (@pxref{Modules,,, guile, +GNU Guile Reference Manual}). + +The following table gives an overview of the main directories and what +they contain. Remember that in Guile, each module name is derived from +its file name---e.g., the module in file@file{guix/packages.scm} is +called @code{(guix packages)}. + +@table @file +@item guix +This is the location of core Guix mechanisms. A few examples: + +@table @code +@item (guix store) +Connecting to and interacting with the build daemon (@pxref{The Store}). +@item (guix derivations) +Creating derivations (@pxref{Derivations}). +@item (guix gexps) +Writing G-expressions (@pxref{G-Expressions}). +@item (guix packages) +Defining packages and origins (@pxref{package Reference}). +@item (guix download) +@itemx (guix git-download) +The @code{url-fetch} and @code{git-fetch} origin download methods +(@pxref{origin Reference}). +@item (guix swh) +Fetching source code from the +@uref{https://archive.softwareheritage.org,Software Heritage archive}. +@item (guix search-paths) +Implementing search paths (@pxref{Search Paths}). +@item (guix build-system) +The build system interface (@pxref{Build Systems}). +@item (guix profiles) +Implementing profiles. +@end table + +@cindex build system, directory structure +@item guix/build-system +This directory contains specific build system implementations +(@pxref{Build Systems}), such as: + +@table @code +@item (guix build-system gnu) +the GNU build system; +@item (guix build-system cmake) +the CMake build system; +@item (guix build-system pyproject) +The Python ``pyproject'' build system. +@end table + +@item guix/build +This contains code generally used on the ``build side'' +(@pxref{G-Expressions, strata of code}). This includes code used to +build packages or other operating system components, as well as +utilities: + +@table @code +@item (guix build utils) +Utilities for package definitions and more (@pxref{Build Utilities}). +@item (guix build gnu-build-system) +@itemx (guix build cmake-build-system) +@itemx (guix build pyproject-build-system) +Implementation of build systems, and in particular definition of their +build phases (@pxref{Build Phases}). +@item (guix build syscalls) +Interface to the C library and to Linux system calls. +@end table + +@cindex command-line tools, as Guile modules +@cindex command modules +@item guix/scripts +This contains modules corresponding to @command{guix} sub-commands. For +example, the @code{(guix scripts shell)} module exports the +@code{guix-shell} procedure, which directly corresponds to the +@command{guix shell} command (@pxref{Invoking guix shell}). + +@cindex importer modules +@item guix/import +This contains supporting code for the importers and updaters +(@pxref{Invoking guix import}, and @pxref{Invoking guix refresh}). For +example, @code{(guix import pypi)} defines the interface to PyPI, which +is used by the @code{guix import pypi} command. +@end table + +The directories we have seen so far all live under @file{guix/}. The +other important place is the @code{gnu/} directory, which contains +primarily package definitions as well as libraries and tools for Guix +System (@pxref{System Configuration}) and Guix Home (@pxref{Home +Configuration}). + +@table @file +@cindex package modules +@item gnu/packages +This is by far the most crowded directory of the source tree: it +contains @dfn{package modules} that export package definitions +(@pxref{Package Modules}). A few examples: + +@table @code +@item (gnu packages base) +Module providing ``base'' packages: @code{glibc}, @code{coreutils}, +@code{grep}, etc. +@item (gnu packages guile) +Guile and core Guile packages. +@item (gnu packages linux) +The Linux-libre kernel and related packages. +@item (gnu packages python) +Python and core Python packages. +@item (gnu packages python-xyz) +Miscellaneous Python packages (we were not very creative). +@end table + +In any case, you can jump to a package definition using @command{guix +edit} (@pxref{Invoking guix edit}) and view its location with +@command{guix show} (@pxref{Invoking guix package}). + +@findex search-patches +@item gnu/packages/patches +This directory contains patches applied against packages and obtained +using the @code{search-patches} procedure. + +@item gnu/services +This contains service definitions, primarily for Guix System +(@pxref{Services}) but some of them are adapted and reused for Guix Home +as we will see below. Examples: + +@table @code +@item (gnu services) +The service framework itself, which defines the service and service type +data types (@pxref{Service Composition}). +@item (gnu services base) +``Base'' services (@pxref{Base Services}). +@item (gnu services desktop) +``Desktop'' services (@pxref{Desktop Services}). +@item (gnu services shepherd) +Support for Shepherd services (@pxref{Shepherd Services}). +@end table + +You can jump to a service definition using @command{guix system edit} +and view its location with @command{guix system search} (@pxref{Invoking +guix system}). + +@item gnu/system +These are core Guix System modules, such as: + +@table @code +@item (gnu system) +Defines @code{operating-system} (@pxref{operating-system Reference}). +@item (gnu system file-systems) +Defines @code{file-system} (@pxref{File Systems}). +@item (gnu system mapped-devices) +Defines @code{mapped-device} (@pxref{Mapped Devices}). +@end table + +@item gnu/build +These are modules that are either used on the ``build side'' when +building operating systems or packages, or at run time by operating +systems. + +@table @code +@item (gnu build accounts) +Creating @file{/etc/passwd}, @file{/etc/shadow}, etc. (@pxref{User +Accounts}). +@item (gnu build activation) +Activating an operating system at boot time or reconfiguration time. +@item (gnu build file-systems) +Searching, checking, and mounting file systems. +@item (gnu build linux-boot) +@itemx (gnu build hurd-boot) +Booting GNU/Linux and GNU/Hurd operating systems. +@item (gnu build linux-initrd) +Creating a Linux initial RAM disk (@pxref{Initial RAM Disk}). +@end table + +@item gnu/home +This contains all things Guix Home (@pxref{Home Configuration}); +examples: + +@table @code +@item (gnu home services) +Core services such as @code{home-files-service-type}. +@item (gnu home services ssh) +SSH-related services (@pxref{Secure Shell}). +@end table + +@item gnu/installer +This contains the text-mode graphical system installer (@pxref{Guided +Graphical Installation}). + +@item gnu/machine +These are the @dfn{machine abstractions} used by @command{guix deploy} +(@pxref{Invoking guix deploy}). + +@item gnu/tests +This contains system tests---tests that spawn virtual machines to check +that system services work as expected (@pxref{Running the Test Suite}). +@end table + +Last, there's also a few directories that contain files that are +@emph{not} Guile modules: + +@table @file +@item tests +These are unit tests, each file corresponding more or less to one +module, in particular @code{(guix @dots{})} modules (@pxref{Running the +Test Suite}). + +@item doc +This is the documentation in the form of Texinfo files: this manual and +the Cookbook. + +@item po +This is the location of translations of Guix itself, of package synopses +and descriptions, of the manual, and of the cookbook (@pxref{Translating +Guix}). + +@item etc +Miscellaneous files: shell completions, support for systemd and other +init systems, Git hooks, etc. +@end table + +With all this, a fair chunk of your operating system is at your +fingertips! Beyond @command{grep} and @command{git grep}, @pxref{The +Perfect Setup} on how to navigate code from your editor, and +@pxref{Using Guix Interactively} for information on how to use +interactively use Scheme modules. Enjoy! + @node Packaging Guidelines @section Packaging Guidelines diff --git a/doc/guix.texi b/doc/guix.texi index 87fe9f803c..fa26d78187 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -7677,7 +7677,8 @@ Programming Interface that build results @emph{derive} from them. This chapter describes all these APIs in turn, starting from high-level -package definitions. +package definitions. @xref{Source Tree Structure}, for a more general +overview of the source code. @menu * Package Modules:: Packages from the programmer's viewpoint. base-commit: 9d9bb8955a939b89b5b28f1071b70ed9f9a54f8c -- 2.41.0 From debbugs-submit-bounces@debbugs.gnu.org Fri Mar 08 13:02:19 2024 Received: (at 69587) by debbugs.gnu.org; 8 Mar 2024 18:02:19 +0000 Received: from localhost ([127.0.0.1]:59517 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rieXz-0007UV-3M for submit@debbugs.gnu.org; Fri, 08 Mar 2024 13:02:19 -0500 Received: from relay.yourmailgateway.de ([188.68.63.162]:46399) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rieXu-0007UK-Sc for 69587@debbugs.gnu.org; Fri, 08 Mar 2024 13:02:17 -0500 Received: from mors-relay-8201.netcup.net (localhost [127.0.0.1]) by mors-relay-8201.netcup.net (Postfix) with ESMTPS id 4TrvBD6vDLz3vXv; Fri, 8 Mar 2024 19:01:40 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=pelzflorian.de; s=key2; t=1709920901; bh=t774KE+s3TFt/LGKluauo/yPFYuLIfY+gQmDOg+DjRY=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=Sehr93SV0fys6WkJ7CGnWBa3S00KwkGAWRP7gmNG5Uiwyx0AbKUvBTtM21EEn4WGn mfBHG3NGWZInr0IcpZYKo89OZZpMpmywxYTBxbkG9eAjfP4/3SbGVZICmoNo1T9+bh 9Lj3MlZlllKaa1oDl38EmbN7t4ZQIBP874x7nBfDRVjLxV7TYBORhPboHplPt0zL9K 4gm7BYRDjopJ8lOiTfS/4H19GEK9yNjM7xMNducuronEIfs68kLTM7jVP2E6LRt0og MSY1rZvo1rnq0WA+B6pHREfDT8lBWeDwlCwLnXNQzFJL1ln3lfvmYD9m7Ac6Eu4lzb GfaklUj4URryA== Received: from policy02-mors.netcup.net (unknown [46.38.225.35]) by mors-relay-8201.netcup.net (Postfix) with ESMTPS id 4TrvBD67yMz3vXD; Fri, 8 Mar 2024 19:01:40 +0100 (CET) Received: from mxe217.netcup.net (unknown [10.243.12.53]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by policy02-mors.netcup.net (Postfix) with ESMTPS id 4TrvBD4RtWz8sb8; Fri, 8 Mar 2024 19:01:40 +0100 (CET) Received: from florianrock64 (ip92344de0.dynamic.kabel-deutschland.de [146.52.77.224]) by mxe217.netcup.net (Postfix) with ESMTPSA id F419B82F77; Fri, 8 Mar 2024 19:01:34 +0100 (CET) From: "pelzflorian (Florian Pelz)" To: Ludovic =?utf-8?Q?Court=C3=A8s?= Subject: Re: [bug#69587] [PATCH] doc: Add =?utf-8?Q?=E2=80=9CSource?= Tree =?utf-8?Q?Structure=E2=80=9D?= section. In-Reply-To: ("Ludovic =?utf-8?Q?Court=C3=A8s=22's?= message of "Wed, 6 Mar 2024 17:37:47 +0100") References: Date: Fri, 08 Mar 2024 19:01:34 +0100 Message-ID: <878r2sa9hd.fsf@pelzflorian.de> User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Rspamd-Queue-Id: F419B82F77 X-Rspamd-Server: rspamd-worker-8404 X-NC-CID: rG5UIwSqaXYUbpvEkrNm7Bp5hK4xgfaHPCEQFo8qKpq4Ji5ZKs95u+jZ X-Spam-Score: -0.0 (/) X-Debbugs-Envelope-To: 69587 Cc: 69587@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Hi Ludo. Good that I now have finally watched Josselin=E2=80=99s talk. This section seems to be a good idea in general, but the examples are an opinionated selection. I believe the list should be small. Listing individual modules directly in ~/src/guix/guix directory is not useful to newcomers or often self-explanatory. gnu/installer, gnu/system, gnu/build, gnu/machine is not useful to know. po is better not talked about, otherwise people edit translations directly in po, when they should use Weblate. Ludovic Court=C3=A8s writes: > +The following table gives an overview of the main directories and what > +they contain. Remember that in Guile, each module name is derived from > +its file name---e.g., the module in file@file{guix/packages.scm} is file@file should be @file > +called @code{(guix packages)}. > + > +@table @file > +@item guix > +This is the location of core Guix mechanisms. A few examples: What does core mean? Perhaps (guix =E2=80=A6) should be listed after (gnu = =E2=80=A6) and defined as the Guix mechanisms that do not belong in gnu? Not quite sure either. > [=E2=80=A6] > +With all this, a fair chunk of your operating system is at your > +fingertips! Beyond @command{grep} and @command{git grep}, @pxref{The > +Perfect Setup} on how to navigate code from your editor, and > +@pxref{Using Guix Interactively} for information on how to use > +interactively use Scheme modules. Enjoy! Remove duplicate =E2=80=9Cuse=E2=80=9D. Regards, Florian From debbugs-submit-bounces@debbugs.gnu.org Fri Mar 08 17:07:41 2024 Received: (at 69587) by debbugs.gnu.org; 8 Mar 2024 22:07:41 +0000 Received: from localhost ([127.0.0.1]:59851 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1riiNQ-0003HE-RY for submit@debbugs.gnu.org; Fri, 08 Mar 2024 17:07:41 -0500 Received: from eggs.gnu.org ([209.51.188.92]:41696) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1riiNO-0003Gy-VK for 69587@debbugs.gnu.org; Fri, 08 Mar 2024 17:07:39 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1riiMm-0003pM-Iy; Fri, 08 Mar 2024 17:07:00 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:References:In-Reply-To:Subject:To: From; bh=7aNn0a3rVkrGSc/ntWXm/faqPYf4npUjVuvDnkdkHmY=; b=VUB2qXrAungDMPF29TzR q4JImQe4p8qb1r0IrRzvPlxJcWll7TQmEvA0dHuSlZJtHnURFMvPHV3U0JUNP4p0hp7iwplghs4LK 947KGvtyFsOgaY+eqZIGsyNsRQnrIGFUnG9lFLm67ju/7xsKpzQCOLech2iK46r3aCVIlcLJMxiFG fggnNBJQ2kQ+EVQFs935JdoIxERIUj8N3Vk9NAsNAZDRBz2FJht05FRfptOX7FMflz62d4DQ9WnJ9 zUX8Z5H72KYoz+Sae0X6k/mrmxCn1PG87FDxhMk4hAXgORl9ci49vPvrOH+yrr0B91SkzroJD1FVQ mMfk6molWCUF4A==; From: =?utf-8?Q?Ludovic_Court=C3=A8s?= To: "pelzflorian (Florian Pelz)" Subject: Re: [bug#69587] [PATCH] doc: Add =?utf-8?Q?=E2=80=9CSource?= Tree =?utf-8?Q?Structure=E2=80=9D?= section. In-Reply-To: <878r2sa9hd.fsf@pelzflorian.de> (pelzflorian@pelzflorian.de's message of "Fri, 08 Mar 2024 19:01:34 +0100") References: <878r2sa9hd.fsf@pelzflorian.de> X-URL: http://www.fdn.fr/~lcourtes/ X-Revolutionary-Date: Nonidi 19 =?utf-8?Q?Vent=C3=B4se?= an 232 de la =?utf-8?Q?R=C3=A9volution=2C?= jour du Cerfeuil X-PGP-Key-ID: 0x090B11993D9AEBB5 X-PGP-Key: http://www.fdn.fr/~lcourtes/ludovic.asc X-PGP-Fingerprint: 3CE4 6455 8A84 FDC6 9DB4 0CFB 090B 1199 3D9A EBB5 X-OS: x86_64-pc-linux-gnu Date: Fri, 08 Mar 2024 23:06:57 +0100 Message-ID: <877cic2xa6.fsf@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 69587 Cc: 69587@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Hello! "pelzflorian (Florian Pelz)" skribis: > This section seems to be a good idea in general, but the examples are an > opinionated selection. I believe the list should be small. Listing > individual modules directly in ~/src/guix/guix directory is not useful > to newcomers or often self-explanatory. gnu/installer, gnu/system, > gnu/build, gnu/machine is not useful to know. Are you suggesting to remove the examples? If that=E2=80=99s the case, we might as well not add the section or it would become a bullet list with three items (guix/, gnu/, and tests/), no? The selection is opinionated, indeed. My thought was that it was a way to connect the dots among things presented in the manual and to provide a =E2=80=9Cguided tour=E2=80=9D pretty much like Josselin=E2=80=99s talk. > po is better not talked about, otherwise people edit translations > directly in po, when they should use Weblate. Not sure; there=E2=80=99s a link to =E2=80=9CTranslating Guix=E2=80=9D that= explains what to do. >> +@table @file >> +@item guix >> +This is the location of core Guix mechanisms. A few examples: > > What does core mean? The examples were meant to illustrate what is meant by =E2=80=9Ccore=E2=80= =9D. Do you think some other adjective or a longer description would help? > Perhaps (guix =E2=80=A6) should be listed after (gnu =E2=80=A6) and defi= ned as the > Guix mechanisms that do not belong in gnu? Not quite sure either. The order I chose is (roughly) from lower-level to higher-level: (guix store) -> (guix derivation) -> (guix packages) -> =E2=80=A6 =E2=80=A6 -> (gnu packages) -> (gnu system) -> =E2=80=A6 Does that make sense? Thanks for your feedback! Ludo=E2=80=99. From debbugs-submit-bounces@debbugs.gnu.org Sat Mar 09 09:39:31 2024 Received: (at 69587) by debbugs.gnu.org; 9 Mar 2024 14:39:31 +0000 Received: from localhost ([127.0.0.1]:60999 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rixrH-00088d-1D for submit@debbugs.gnu.org; Sat, 09 Mar 2024 09:39:31 -0500 Received: from relay.yourmailgateway.de ([46.38.247.119]:55979) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rixrE-00088T-8m for 69587@debbugs.gnu.org; Sat, 09 Mar 2024 09:39:29 -0500 Received: from mors-relay-8404.netcup.net (localhost [127.0.0.1]) by mors-relay-8404.netcup.net (Postfix) with ESMTPS id 4TsQdp1W3Vz80xR; Sat, 9 Mar 2024 15:38:54 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=pelzflorian.de; s=key2; t=1709995134; bh=kUSiU9ACBfmA6ajy5nyfcNx1pR4A+tvItVlnxl+VKdw=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=YZm418U3fuaQLU22rJhZd7jXWIx6upYzugFMUMbT3XK4F8QCarHuhEGqnl8nYihfG H9HCMzAT8hnIEze+1SUc+pnQ/DpUSKq6A1FBBjO2oJ18zldAaNUdRdiLlUS3SiUUGI UNZ9YOezENIo6dA5OrNWQmo1G0i05AUaOVozCTFPC1MLleVI7txxmVvjF4UU5NT/1f BkoS/YC/RgUKW0SJL7qxP5SZ9Nfty9945fXG82kYt2qUFIzDsVgBGRXYd6uiSHnRfs rB8M1cRdMjG9a6V6JBGlK+nx4jCoteqDOu7oZq0W7EBtTI0yKp6ErMD8yyJyISmZnf iOCP4Pxgq2aMw== Received: from policy02-mors.netcup.net (unknown [46.38.225.35]) by mors-relay-8404.netcup.net (Postfix) with ESMTPS id 4TsQdp16rlz4yDg; Sat, 9 Mar 2024 15:38:54 +0100 (CET) Received: from mxe217.netcup.net (unknown [10.243.12.53]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by policy02-mors.netcup.net (Postfix) with ESMTPS id 4TsQdn5wkZz8svW; Sat, 9 Mar 2024 15:38:53 +0100 (CET) Received: from florianrock64 (ip92344de0.dynamic.kabel-deutschland.de [146.52.77.224]) by mxe217.netcup.net (Postfix) with ESMTPSA id 4513E82EAA; Sat, 9 Mar 2024 15:38:46 +0100 (CET) From: "pelzflorian (Florian Pelz)" To: Ludovic =?utf-8?Q?Court=C3=A8s?= Subject: Re: [bug#69587] [PATCH] doc: Add =?utf-8?Q?=E2=80=9CSource?= Tree =?utf-8?Q?Structure=E2=80=9D?= section. In-Reply-To: <877cic2xa6.fsf@gnu.org> ("Ludovic =?utf-8?Q?Court=C3=A8s=22'?= =?utf-8?Q?s?= message of "Fri, 08 Mar 2024 23:06:57 +0100") References: <878r2sa9hd.fsf@pelzflorian.de> <877cic2xa6.fsf@gnu.org> Date: Sat, 09 Mar 2024 15:38:44 +0100 Message-ID: <878r2r8o7f.fsf@pelzflorian.de> User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Rspamd-Queue-Id: 4513E82EAA X-Rspamd-Server: rspamd-worker-8404 X-NC-CID: fGlopATOmv4cjmsEH+NdOCun6iKV1wDsVRv97F1HgY9cQq+c+PtS1Y8i X-Spam-Score: -0.0 (/) X-Debbugs-Envelope-To: 69587 Cc: 69587@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Hi Ludo. Josselin=E2=80=99s talk is different in that it is a talk of more than 30 minutes. In so much time, it can give more detailed guidance to almost the whole guix source tree, even including build-aux and nix. Josselin also gives hints to use git grep (like you) but also to read the commentary at the top of the file. This may be a helpful hint to someone starting out, but someone starting out maybe does not want to read as much as a complete talk. If they wanted it all, then better link to Josselin=E2=80=99s talk. Ludovic Court=C3=A8s writes: > The order I chose is (roughly) from lower-level to higher-level: > > (guix store) -> (guix derivation) -> (guix packages) -> =E2=80=A6 > =E2=80=A6 -> (gnu packages) -> (gnu system) -> =E2=80=A6 > > Does that make sense? In your section the modules directly in (guix =E2=80=A6) appeared unsorted = to me. Could you explicitly state this order in the manual section? Nice things like (guix swh) or (gnu system), (gnu build), (gnu installer), (gnu machine), or po, still seem not useful for the general populace to me. > Are you suggesting to remove the examples? I like tests and gnu/tests. Also that your section lists (guix build-system =E2=80=A6) and the occasional duality with (guix build =E2=80=A6-build-system), Rightfully you also list non-dual utilities like (= guix build syscalls) to make clear not all in (guix build) is about build systems. The explanation about guix/scripts containing the entry points is useful. >> What does core mean? > > The examples were meant to illustrate what is meant by =E2=80=9Ccore=E2= =80=9D. Do you > think some other adjective or a longer description would help? > >> Perhaps (guix =E2=80=A6) should be listed after (gnu =E2=80=A6) and def= ined as the >> Guix mechanisms that do not belong in gnu? Not quite sure either. Josselin called the distinction between (guix =E2=80=A6) and (gnu =E2=80=A6= ) murky, explaining that most of (guix =E2=80=A6) must not import (gnu =E2=80=A6) ex= cept by module-ref, while (guix scripts =E2=80=A6) and such can just use-modules (g= nu =E2=80=A6). To me, gnu/packages.scm looks like core as well, but it rightf= ully is in gnu. Regards, Florian From debbugs-submit-bounces@debbugs.gnu.org Mon Mar 11 13:06:18 2024 Received: (at 69587) by debbugs.gnu.org; 11 Mar 2024 17:06:18 +0000 Received: from localhost ([127.0.0.1]:41164 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rjj6Q-0007OE-8c for submit@debbugs.gnu.org; Mon, 11 Mar 2024 13:06:18 -0400 Received: from eggs.gnu.org ([209.51.188.92]:41758) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rjj6N-0007Nk-B4 for 69587@debbugs.gnu.org; Mon, 11 Mar 2024 13:06:17 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rjj5h-0007rJ-Op; Mon, 11 Mar 2024 13:05:35 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:References:In-Reply-To:Subject:To: From; bh=gtk2KRS5zYyZiu5N2QWK7JIc+eztXHbFKx40OaRr+Ck=; b=Ojkd5485LtmW+Hbkg0OM AMCLWEEihmw8EUrAko/y1/QSo3EaSbOSOwoNHS+3o9Qm0e7XD0wCyaIhqMFWeRNJhKcFFoUs3+pij uryKQ08lmZFasNo808u8GHCYZQjxzu+vaJfhOd+pnr4cowfKJNjjmC9AX+iUyYgbJE1fr+tRawcaN EablnXgVoNxOUGSR51wp5vS//oY6BZgZiRPM5eXTG604aB94pybEyloXXqGwDls4Q8IQF5S6dV098 e5Gvz1yf9WL6RuKbFkS/w5rAmaXQVhprdQ0hSOSg/Ykx8+wBYnp5UEwMfnWu1RH44weS41bzsZEvx ZEQIr9ojiLMDig==; From: =?utf-8?Q?Ludovic_Court=C3=A8s?= To: "pelzflorian (Florian Pelz)" Subject: Re: [bug#69587] [PATCH] doc: Add =?utf-8?Q?=E2=80=9CSource?= Tree =?utf-8?Q?Structure=E2=80=9D?= section. In-Reply-To: <878r2r8o7f.fsf@pelzflorian.de> (pelzflorian@pelzflorian.de's message of "Sat, 09 Mar 2024 15:38:44 +0100") References: <878r2sa9hd.fsf@pelzflorian.de> <877cic2xa6.fsf@gnu.org> <878r2r8o7f.fsf@pelzflorian.de> Date: Mon, 11 Mar 2024 18:05:12 +0100 Message-ID: <87le6oog1j.fsf@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 69587 Cc: 69587@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Hello! "pelzflorian (Florian Pelz)" skribis: > Josselin=E2=80=99s talk is different in that it is a talk of more than 30 > minutes. In so much time, it can give more detailed guidance to almost > the whole guix source tree, even including build-aux and nix. Josselin > also gives hints to use git grep (like you) but also to read the > commentary at the top of the file. This may be a helpful hint to > someone starting out, but someone starting out maybe does not want to > read as much as a complete talk. If they wanted it all, then better > link to Josselin=E2=80=99s talk. Right. > Ludovic Court=C3=A8s writes: >> The order I chose is (roughly) from lower-level to higher-level: >> >> (guix store) -> (guix derivation) -> (guix packages) -> =E2=80=A6 >> =E2=80=A6 -> (gnu packages) -> (gnu system) -> =E2=80=A6 >> >> Does that make sense? > > In your section the modules directly in (guix =E2=80=A6) appeared unsorte= d to > me. Could you explicitly state this order in the manual section? Good idea, will do. > Nice things like (guix swh) or (gnu system), (gnu build), (gnu > installer), (gnu machine), or po, still seem not useful for the general > populace to me. This is in the =E2=80=9CContributing=E2=80=9D chapter, so we=E2=80=99re tal= king about a subset of the general populace. :-) You might argue that few current contributors care about the modules you mention, but by exposing the structure of the code, my hope is that more people would dare take a look and fiddle with it. [...] >> The examples were meant to illustrate what is meant by =E2=80=9Ccore=E2= =80=9D. Do you >> think some other adjective or a longer description would help? >> >>> Perhaps (guix =E2=80=A6) should be listed after (gnu =E2=80=A6) and de= fined as the >>> Guix mechanisms that do not belong in gnu? Not quite sure either. > > Josselin called the distinction between (guix =E2=80=A6) and (gnu =E2=80= =A6) murky, > explaining that most of (guix =E2=80=A6) must not import (gnu =E2=80=A6) = except by > module-ref, while (guix scripts =E2=80=A6) and such can just use-modules = (gnu > =E2=80=A6). To me, gnu/packages.scm looks like core as well, but it righ= tfully > is in gnu. I think =E2=80=9Cmurky=E2=80=9D is a strong word, or at least it shouldn=E2= =80=99t be interpreted as meaning that the guix/gnu distinction is arbitrary. I=E2=80= =99ll try to clarify that as well. I was going to send a v2 but I=E2=80=99m not sure the changes I made fully address your concerns: --=-=-= Content-Type: text/x-patch Content-Disposition: inline diff --git a/doc/contributing.texi b/doc/contributing.texi index ff7065ad2a..18f3705a43 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -563,7 +563,9 @@ Source Tree Structure @table @file @item guix -This is the location of core Guix mechanisms. A few examples: +This is the location of core Guix mechanisms. To illustrate what is +meant by ``core'', here are a few examples, starting from low-level +tools and going towards higher-level tools: @table @code @item (guix store) @@ -638,10 +640,16 @@ Source Tree Structure @end table The directories we have seen so far all live under @file{guix/}. The -other important place is the @code{gnu/} directory, which contains +other important place is the @file{gnu/} directory, which contains primarily package definitions as well as libraries and tools for Guix System (@pxref{System Configuration}) and Guix Home (@pxref{Home -Configuration}). +Configuration}), all of which build upon functionality provided by +@code{(guix @dots{})} modules@footnote{For this reason, @code{(guix +@dots{})} modules must generally not depend on @code{(gnu @dots{})} +modules, with one notable exception: @code{(guix build-system @dots{})} +modules may look up packages at run time---e.g., @code{(guix +build-system cmake)} needs to access the @code{cmake} variable at run +time.}. @table @file @cindex package modules --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Let me know what you think! Thanks, Ludo=E2=80=99. --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Mon Mar 11 14:10:38 2024 Received: (at 69587) by debbugs.gnu.org; 11 Mar 2024 18:10:38 +0000 Received: from localhost ([127.0.0.1]:41233 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rjk6f-0000sO-Rg for submit@debbugs.gnu.org; Mon, 11 Mar 2024 14:10:38 -0400 Received: from relay.yourmailgateway.de ([46.38.247.119]:47773) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rjk6b-0000s9-B8 for 69587@debbugs.gnu.org; Mon, 11 Mar 2024 14:10:37 -0400 Received: from mors-relay-8404.netcup.net (localhost [127.0.0.1]) by mors-relay-8404.netcup.net (Postfix) with ESMTPS id 4TtlDP6tgxz82G5; Mon, 11 Mar 2024 19:09:57 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=pelzflorian.de; s=key2; t=1710180598; bh=J93z4D18upN98vnp7B92CKZ9nyFle1W0KrXZaEsRWlY=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=JkUNg7rSwWWzPUu2cYcGKxIQ35X6H5fZBtT6EuA8TI8W8r24WCg7e4HccaFdJVBAB d3z7glB55zTSC7ZjRxYuhruIn+GE9nh8neLRr2K5hox7NGX7B4bwbHi36Wy7PctZte 04esZBC+1eochzteDzWzPYWblbhvMddgi3CBU2QpFM+eyPwXA0Wd6/yH1g3uz/B/Rd RBlfdBtLClXtZAwYy0G8OObdD7Ja/eSQtd9fegG/hMpyMVTv+WvL/o35CkD+Lt6FRM pRrw8VDmj+Dmjlx7S6QF1lh5IPu6EMfy10VQQNN2nIrNlABWsqahAzaU+7M3A3Z2ER H2bpucRKOCITw== Received: from policy01-mors.netcup.net (unknown [46.38.225.35]) by mors-relay-8404.netcup.net (Postfix) with ESMTPS id 4TtlDP6VpHz4yT0; Mon, 11 Mar 2024 19:09:57 +0100 (CET) X-Virus-Scanned: Debian amavisd-new at policy01-mors.netcup.net X-Spam-Flag: NO X-Spam-Score: -2.9 X-Spam-Level: X-Spam-Status: No, score=-2.9 required=6.31 tests=[ALL_TRUSTED=-1, BAYES_00=-1.9] autolearn=ham autolearn_force=no Received: from mxe217.netcup.net (unknown [10.243.12.53]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by policy01-mors.netcup.net (Postfix) with ESMTPS id 4TtlDG0LgQz8sZl; Mon, 11 Mar 2024 19:09:49 +0100 (CET) Received: from florianrock64 (ip92344de0.dynamic.kabel-deutschland.de [146.52.77.224]) by mxe217.netcup.net (Postfix) with ESMTPSA id AF8EA832BD; Mon, 11 Mar 2024 19:09:44 +0100 (CET) From: "pelzflorian (Florian Pelz)" To: Ludovic =?utf-8?Q?Court=C3=A8s?= Subject: Re: [bug#69587] [PATCH] doc: Add =?utf-8?Q?=E2=80=9CSource?= Tree =?utf-8?Q?Structure=E2=80=9D?= section. In-Reply-To: <87le6oog1j.fsf@gnu.org> ("Ludovic =?utf-8?Q?Court=C3=A8s=22'?= =?utf-8?Q?s?= message of "Mon, 11 Mar 2024 18:05:12 +0100") References: <878r2sa9hd.fsf@pelzflorian.de> <877cic2xa6.fsf@gnu.org> <878r2r8o7f.fsf@pelzflorian.de> <87le6oog1j.fsf@gnu.org> Date: Mon, 11 Mar 2024 19:09:43 +0100 Message-ID: <87jzm8prmg.fsf@pelzflorian.de> User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Rspamd-Queue-Id: AF8EA832BD X-Rspamd-Server: rspamd-worker-8404 X-NC-CID: Y0kXCLQHYVZvweKfc0h64Pfocqs2RUdyD4spLHn/6aA6k0HiuAw7IjRx X-Spam-Score: -0.0 (/) X-Debbugs-Envelope-To: 69587 Cc: 69587@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Hi Ludo. Ludovic Court=C3=A8s writes: >> Nice things like (guix swh) or (gnu system), (gnu build), (gnu >> installer), (gnu machine), or po, still seem not useful for the general >> populace to me. > > This is in the =E2=80=9CContributing=E2=80=9D chapter, so we=E2=80=99re t= alking about a subset > of the general populace. :-) > > You might argue that few current contributors care about the modules you > mention, but by exposing the structure of the code, my hope is that more > people would dare take a look and fiddle with it. Your reply makes clear that emphasis on (guix swh) was intentional. If SWH is central to Guix, then you are right mentioning it. I had not recognized and only considered it a nice, well-integrated bonus. Still I would prefer if (gnu system), (gnu build), (gnu installer), (gnu machine), and especially po, were not part of the list. I expect that most contributors want to provide a package or (home) service with docs and tests. They will not customize the operating-system record type. > [...] > >>> The examples were meant to illustrate what is meant by =E2=80=9Ccore=E2= =80=9D. Do you >>> think some other adjective or a longer description would help? >>> >>>> Perhaps (guix =E2=80=A6) should be listed after (gnu =E2=80=A6) and d= efined as the >>>> Guix mechanisms that do not belong in gnu? Not quite sure either. >> >> Josselin called the distinction between (guix =E2=80=A6) and (gnu =E2=80= =A6) murky, >> explaining that most of (guix =E2=80=A6) must not import (gnu =E2=80=A6)= except by >> module-ref, while (guix scripts =E2=80=A6) and such can just use-modules= (gnu >> =E2=80=A6). To me, gnu/packages.scm looks like core as well, but it rig= htfully >> is in gnu. > > I think =E2=80=9Cmurky=E2=80=9D is a strong word, or at least it shouldn= =E2=80=99t be > interpreted as meaning that the guix/gnu distinction is arbitrary. I=E2= =80=99ll > try to clarify that as well. Hmm what is the difference between, let=E2=80=99s say, (gnu packages) and (= guix package)? > @@ -638,10 +640,16 @@ Source Tree Structure > @end table >=20=20 > The directories we have seen so far all live under @file{guix/}. The > -other important place is the @code{gnu/} directory, which contains > +other important place is the @file{gnu/} directory, which contains > primarily package definitions as well as libraries and tools for Guix > System (@pxref{System Configuration}) and Guix Home (@pxref{Home > -Configuration}). > +Configuration}), all of which build upon functionality provided by > +@code{(guix @dots{})} modules@footnote{For this reason, @code{(guix > +@dots{})} modules must generally not depend on @code{(gnu @dots{})} > +modules, with one notable exception: @code{(guix build-system @dots{})} > +modules may look up packages at run time---e.g., @code{(guix > +build-system cmake)} needs to access the @code{cmake} variable at run > +time.}. I think the (guix build-system @dots{}) never use (gnu =E2=80=A6)? scripts= and importers do. Regards, Florian From debbugs-submit-bounces@debbugs.gnu.org Tue Mar 12 12:36:51 2024 Received: (at 69587) by debbugs.gnu.org; 12 Mar 2024 16:36:51 +0000 Received: from localhost ([127.0.0.1]:43518 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rk57S-0000K4-NM for submit@debbugs.gnu.org; Tue, 12 Mar 2024 12:36:51 -0400 Received: from ns13.heimat.it ([46.4.214.66]:54732) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rk57Q-0000Jp-4p for 69587@debbugs.gnu.org; Tue, 12 Mar 2024 12:36:50 -0400 Received: from localhost (ip6-localhost [127.0.0.1]) by ns13.heimat.it (Postfix) with ESMTP id 0DE6630022C; Tue, 12 Mar 2024 16:36:08 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at ns13.heimat.it Received: from ns13.heimat.it ([127.0.0.1]) by localhost (ns13.heimat.it [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id PI1tH45RZqFe; Tue, 12 Mar 2024 16:36:05 +0000 (UTC) Received: from bourrache.mug.xelera.it (unknown [93.56.171.217]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by ns13.heimat.it (Postfix) with ESMTPSA id B9A83300104; Tue, 12 Mar 2024 16:36:05 +0000 (UTC) Received: from roquette.mug.biscuolo.net (roquette [10.38.2.14]) by bourrache.mug.xelera.it (Postfix) with SMTP id 595882F9D7A9; Tue, 12 Mar 2024 17:36:05 +0100 (CET) Received: (nullmailer pid 16802 invoked by uid 1000); Tue, 12 Mar 2024 16:36:05 -0000 From: Giovanni Biscuolo To: Ludovic =?utf-8?Q?Court=C3=A8s?= Subject: Re: [bug#69587] [PATCH] doc: Add =?utf-8?Q?=E2=80=9CSource?= Tree =?utf-8?Q?Structure=E2=80=9D?= section. In-Reply-To: <87le6oog1j.fsf@gnu.org> Organization: Xelera.eu References: <878r2sa9hd.fsf@pelzflorian.de> <877cic2xa6.fsf@gnu.org> <878r2r8o7f.fsf@pelzflorian.de> <87le6oog1j.fsf@gnu.org> Date: Tue, 12 Mar 2024 17:35:57 +0100 Message-ID: <877ci7tnki.fsf@xelera.eu> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha512; protocol="application/pgp-signature" X-Spam-Score: -0.0 (/) X-Debbugs-Envelope-To: 69587 Cc: 69587@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Hello Ludo' thank you for this patch, I find it super useful I don't have specific comments, just general ones. Ludovic Court=C3=A8s writes: > "pelzflorian (Florian Pelz)" skribis: [...] >> but someone starting out maybe does not want to read as much as a >> complete talk. If they wanted it all, then better link to Josselin=E2= =80=99s >> talk. > > Right. I appreciate Josselin=E2=80=99s talk very much, but in general I prefer stu= dying written information instead of "attenting to" a talk; I guess I'm not the only one :-) [...] >> Nice things like (guix swh) or (gnu system), (gnu build), (gnu >> installer), (gnu machine), or po, still seem not useful for the general >> populace to me. > > This is in the =E2=80=9CContributing=E2=80=9D chapter, so we=E2=80=99re t= alking about a subset > of the general populace. :-) I don't know what general populance is :-) but I agree with you that explaining the structure of the code is interesting for /some/ people, like me for example. Also, please don't (dis)miss the usefulness of such documentation as a sort of meta-literate programming, probably also useful for expert Guix programmers too, IMHO > You might argue that few current contributors care about the modules you > mention, but by exposing the structure of the code, my hope is that more > people would dare take a look and fiddle with it. Also, we should not assume what are the insterests of most contributors or in general of readers, since everyone have it's own interests and goals in studying Guix. A section like this one does not have to be "perfect" at first "shot", it can be improved by expert Guix persons when they feel "inspired"; I already find the patches you sent useful. It's true that (Guile) programmers could study the source code to understand how it works but knowing the general _architecture is very helpful. Last but not least, I have a feeling it's time to split the Guix manual in two: one for users, like "GNU Guix User Manual" and one for programmers [1], like "GNU Guix Programmer Manual", with chapters like "Programming Interface", "Platforms", "Bootstrapping", "Porting", "Contributing"... but that's another story, OT here. [...] >> Josselin called the distinction between (guix =E2=80=A6) and (gnu =E2=80= =A6) murky, >> explaining that most of (guix =E2=80=A6) must not import (gnu =E2=80=A6)= except by >> module-ref, while (guix scripts =E2=80=A6) and such can just use-modules= (gnu >> =E2=80=A6). To me, gnu/packages.scm looks like core as well, but it rig= htfully >> is in gnu. > > I think =E2=80=9Cmurky=E2=80=9D is a strong word, or at least it shouldn= =E2=80=99t be > interpreted as meaning that the guix/gnu distinction is arbitrary. I=E2= =80=99ll > try to clarify that as well. IMHO the very fact that Josselin find that distinction "murky" (arbitrary? not well defined? not much clear?) is an indication that we need a section like the one you are proposing :-D [...] Thank you for your work! Gio' [1] ehrm... using Guix _is_ programming but well, I hope you got the idea :-) =2D-=20 Giovanni Biscuolo Xelera IT Infrastructures --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQJABAEBCgAqFiEERcxjuFJYydVfNLI5030Op87MORIFAmXwhG0MHGdAeGVsZXJh LmV1AAoJENN9DqfOzDkSluIP/i+EgT44QlMV0ZRHOpz/qCAOUp8DQSL5IaRBUAtw 55mZUQn/DMJef+bfJTTwj7g45MpA1BoSn7Zp1C1WOXM4xJvkh08A7AjOTMrFcf/P tmTSyxasnUWUn75SS2Lm4bWh6GG/XMN7gLPbV9x1O9thxXTV10ZBpK4r7G7lsEdc Bb9+U01+XuhHizNtRCuhfeWxXdzzizjZ78/F14+2MUadRjZ7OkEl9MWFLcbeqenG BaUiTMu9Z+wqm0IdNMQbOpMiKR3qz0DA/8Tpqxqek07oADEg7BkDYBQ2D3Zaos43 pzFLl1hd8cILLYdHoASN28vOEq6+69hdWunGXpmLGZKjRT+3giUH/Ye1afIj8Qzc nvbFABlfBgWqoNcQvW/EsohHqTeDW+YUpXXm79EdmeU+brUZz/QfXi9rNTpoUHES rfZx35FNM491ltdn63i5HG7c3dMxSkOG1wAPTFq+rOfK9KdzxveDCo6xhMaa52Dc qnt9beZuwmaTSG4Ez3RJ42QcSWiozSfMkTF/yKbNsdF9kEmKydvgiVXvISFNdlsr ELq3hgDudRsZ+tInsBP44v37Jfnx79BVldrENeeHp5KPDwcy1xetDQCeHiYEtZ83 5bPXYo2trUPTU99Q33xM4VZhguHpgcN3sDCY+wF4+XR5kWxdTxI3V3qtwKnhFFUA QP4E =iGa3 -----END PGP SIGNATURE----- --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Tue Mar 12 14:41:55 2024 Received: (at 69587) by debbugs.gnu.org; 12 Mar 2024 18:41:55 +0000 Received: from localhost ([127.0.0.1]:43808 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rk74V-0006PR-0h for submit@debbugs.gnu.org; Tue, 12 Mar 2024 14:41:55 -0400 Received: from relay.yourmailgateway.de ([194.59.206.189]:40077) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rk74R-0006PH-Kz for 69587@debbugs.gnu.org; Tue, 12 Mar 2024 14:41:53 -0400 Received: from relay02-mors.netcup.net (localhost [127.0.0.1]) by relay02-mors.netcup.net (Postfix) with ESMTPS id 4TvMt338XXz45QY; Tue, 12 Mar 2024 19:41:15 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=pelzflorian.de; s=key2; t=1710268875; bh=xNljVR9lr9ZXNa9NLkTHdS7ydVKXERUwF3EM8d0swuY=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=CbxkWFJQ36FJogpZKyc/YqxeLq6iutEH6LoZLJNGbX9V0wTD4etYs32DmjfaQI/ps jqmgzIAEz8fO6/VJ9ghbsZItcVx4lVRTC1OmfpPtUzrTp0NqVHpbBx+/Tb0ePnJmZk 2ExVCJLhhBYDKOmTT2MAcYG8PBZKZEjERt0mqksd1V+oSMwBwCc1bT4ZTnmevtcqiZ dD9ITdVylqoBHNUBSbUitmZ/kqUkrTyOg2WvWi6EtjQCALmuRsDedN6VSvHG0s/E/9 B3Za7TukzgnEs2gXINYHTTYCsIW5BMTDWd3t0mZKM8m6HsOTcYwJWQMQoyVJ0t55YR 85RveHQOpR5qw== Received: from policy02-mors.netcup.net (unknown [46.38.225.35]) by relay02-mors.netcup.net (Postfix) with ESMTPS id 4TvMt32lfGz7wvF; Tue, 12 Mar 2024 19:41:15 +0100 (CET) Received: from mxe217.netcup.net (unknown [10.243.12.53]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by policy02-mors.netcup.net (Postfix) with ESMTPS id 4TvMt14fbZz8sZf; Tue, 12 Mar 2024 19:41:13 +0100 (CET) Received: from florianrock64 (ip92344de0.dynamic.kabel-deutschland.de [146.52.77.224]) by mxe217.netcup.net (Postfix) with ESMTPSA id 3D1F382F14; Tue, 12 Mar 2024 19:41:07 +0100 (CET) From: "pelzflorian (Florian Pelz)" To: Giovanni Biscuolo Subject: Re: [bug#69587] [PATCH] doc: Add =?utf-8?Q?=E2=80=9CSource?= Tree =?utf-8?Q?Structure=E2=80=9D?= section. In-Reply-To: <877ci7tnki.fsf@xelera.eu> (Giovanni Biscuolo's message of "Tue, 12 Mar 2024 17:35:57 +0100") References: <878r2sa9hd.fsf@pelzflorian.de> <877cic2xa6.fsf@gnu.org> <878r2r8o7f.fsf@pelzflorian.de> <87le6oog1j.fsf@gnu.org> <877ci7tnki.fsf@xelera.eu> Date: Tue, 12 Mar 2024 19:41:06 +0100 Message-ID: <87edcfthrx.fsf@pelzflorian.de> User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Rspamd-Queue-Id: 3D1F382F14 X-Rspamd-Server: rspamd-worker-8404 X-NC-CID: tjDLQ/aw+Ck6u43rBfekfHslUj7lWHDgVVlrD8URdBrltvRR9D6aQiqq X-Spam-Score: -0.0 (/) X-Debbugs-Envelope-To: 69587 Cc: Ludovic =?utf-8?Q?Court=C3=A8s?= , 69587@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Thank you Giovanni for voicing support; I=E2=80=99m afraid I sounded more opposed than I am. Giovanni Biscuolo writes: > Also, please don't (dis)miss the usefulness of such documentation as a > sort of meta-literate programming, probably also useful for expert Guix > programmers too, IMHO Do you think the following controversial parts should stay? But what is their audience, and why explain them but not the directories build-aux and nix and some other not so important files in guix? =E2=80=98gnu/system=E2=80=99 These are core Guix System modules, such as: =E2=80=98(gnu system)=E2=80=99 Defines =E2=80=98operating-system=E2=80=99 (*note operating-system Reference::). =E2=80=98(gnu system file-systems)=E2=80=99 Defines =E2=80=98file-system=E2=80=99 (*note File Systems::). =E2=80=98(gnu system mapped-devices)=E2=80=99 Defines =E2=80=98mapped-device=E2=80=99 (*note Mapped Devices::). =E2=80=98gnu/build=E2=80=99 These are modules that are either used on the =E2=80=9Cbuild side=E2= =80=9D when building operating systems or packages, or at run time by operating systems. =E2=80=98(gnu build accounts)=E2=80=99 Creating =E2=80=98/etc/passwd=E2=80=99, =E2=80=98/etc/shadow=E2= =80=99, etc. (*note User Accounts::). =E2=80=98(gnu build activation)=E2=80=99 Activating an operating system at boot time or reconfiguration time. =E2=80=98(gnu build file-systems)=E2=80=99 Searching, checking, and mounting file systems. =E2=80=98(gnu build linux-boot)=E2=80=99 =E2=80=98(gnu build hurd-boot)=E2=80=99 Booting GNU/Linux and GNU/Hurd operating systems. =E2=80=98(gnu build linux-initrd)=E2=80=99 Creating a Linux initial RAM disk (*note Initial RAM Disk::). [=E2=80=A6] =E2=80=98gnu/installer=E2=80=99 This contains the text-mode graphical system installer (*note Guided Graphical Installation::). =E2=80=98gnu/machine=E2=80=99 These are the =E2=80=9Cmachine abstractions=E2=80=9D used by =E2=80=98= guix deploy=E2=80=99 (*note Invoking guix deploy::). [=E2=80=A6] =E2=80=98po=E2=80=99 This is the location of translations of Guix itself, of package synopses and descriptions, of the manual, and of the cookbook (*note Translating Guix::). > Last but not least, I have a feeling it's time to split the Guix manual > in two: one for users, like "GNU Guix User Manual" and one for > programmers [1], like "GNU Guix Programmer Manual", with chapters like > "Programming Interface", "Platforms", "Bootstrapping", "Porting", > "Contributing"... but that's another story, OT here. Hmm why? But yes, another story. Regards, Florian From debbugs-submit-bounces@debbugs.gnu.org Wed Mar 13 17:46:26 2024 Received: (at 69587) by debbugs.gnu.org; 13 Mar 2024 21:46:26 +0000 Received: from localhost ([127.0.0.1]:47543 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rkWQc-0000qN-4F for submit@debbugs.gnu.org; Wed, 13 Mar 2024 17:46:26 -0400 Received: from eggs.gnu.org ([209.51.188.92]:40640) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rkWQZ-0000q6-Dn for 69587@debbugs.gnu.org; Wed, 13 Mar 2024 17:46:24 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rkWPu-0001w5-2g; Wed, 13 Mar 2024 17:45:42 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:References:In-Reply-To:Subject:To: From; bh=/KhTJXtm53C5hK+SN1EEltcM1GIPD2Eb4NyI/T+Vtrg=; b=nrT0KkyN3jhcpElnMre4 +Z43yXRIHM9+3SZv+5W7nrPMXQwlQ4jWrfV75A+bQX9Cv0VWM49ME0QtboLKGfTWWTsOmFNyDoBGe Y8R8jSwGLixFnIH1/+qCPZvKthnyxcBPxJ3+6jQhJ8JHXBY5ldWYWp3b8c+mefbdT8m6hQWEnXICo ghrzH9OK/CMDehCmBr3o84qO8AJeLsVuDfYEcm403qUo64LJpO0xK+qesiP49Nm8TMHTIioiFj8iE wnXsFXeun4LRV+Egr7KF4V9errsR8u1D+bZgRuhap1Wh+mjg8aDOOYvVfWRhZ5PVTDoxsbcQYhsAJ CZfsgsa9vFzVPQ==; From: =?utf-8?Q?Ludovic_Court=C3=A8s?= To: "pelzflorian (Florian Pelz)" Subject: Re: [bug#69587] [PATCH] doc: Add =?utf-8?Q?=E2=80=9CSource?= Tree =?utf-8?Q?Structure=E2=80=9D?= section. In-Reply-To: <87jzm8prmg.fsf@pelzflorian.de> (pelzflorian@pelzflorian.de's message of "Mon, 11 Mar 2024 19:09:43 +0100") References: <878r2sa9hd.fsf@pelzflorian.de> <877cic2xa6.fsf@gnu.org> <878r2r8o7f.fsf@pelzflorian.de> <87le6oog1j.fsf@gnu.org> <87jzm8prmg.fsf@pelzflorian.de> Date: Wed, 13 Mar 2024 22:45:01 +0100 Message-ID: <877ci5iz6q.fsf@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 69587 Cc: 69587@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Hello, "pelzflorian (Florian Pelz)" skribis: > Ludovic Court=C3=A8s writes: >>> Nice things like (guix swh) or (gnu system), (gnu build), (gnu >>> installer), (gnu machine), or po, still seem not useful for the general >>> populace to me. >> >> This is in the =E2=80=9CContributing=E2=80=9D chapter, so we=E2=80=99re = talking about a subset >> of the general populace. :-) >> >> You might argue that few current contributors care about the modules you >> mention, but by exposing the structure of the code, my hope is that more >> people would dare take a look and fiddle with it. [...] > Still I would prefer if (gnu system), (gnu build), (gnu installer), (gnu > machine), and especially po, were not part of the list. I expect that > most contributors want to provide a package or (home) service with docs > and tests. They will not customize the operating-system record type. I disagree here. This section is intended for people willing to contribute to Guix or to learn about it beyond packages (perhaps that intention should be more clearly stated though; perhaps that=E2=80=99s the = crux of our difference of interpretation?). I wouldn=E2=80=99t assume that this= or that part is not worthy. If the section is deemed too long, it probably makes sense to trim it a bit, but I don=E2=80=99t find it this long. Or we can use different examples, though I would keep those that are already documented elsewhere in the manual (like (gnu system)). WDYT? >> I think =E2=80=9Cmurky=E2=80=9D is a strong word, or at least it shouldn= =E2=80=99t be >> interpreted as meaning that the guix/gnu distinction is arbitrary. I=E2= =80=99ll >> try to clarify that as well. > > Hmm what is the difference between, let=E2=80=99s say, (gnu packages) and= (guix > package)? (guix packages) defines a type and associated mechanisms (the =E2=80=9Cpackage Reference=E2=80=9D section). (gnu packages) lets you browse packages defined in (gnu packages =E2=80=A6), etc. The former is abstract; the latter is about concrete package definitions. >> +@code{(guix @dots{})} modules@footnote{For this reason, @code{(guix >> +@dots{})} modules must generally not depend on @code{(gnu @dots{})} >> +modules, with one notable exception: @code{(guix build-system @dots{})} >> +modules may look up packages at run time---e.g., @code{(guix >> +build-system cmake)} needs to access the @code{cmake} variable at run >> +time.}. > > I think the (guix build-system @dots{}) never use (gnu =E2=80=A6)? They do, as in the =E2=80=98cmake=E2=80=99 example above. > scripts and importers do. Oh right, that=E2=80=99s true. So there=E2=80=99s more than one notable ex= ception. :-) Ludo=E2=80=99. From debbugs-submit-bounces@debbugs.gnu.org Thu Mar 14 07:31:21 2024 Received: (at 69587) by debbugs.gnu.org; 14 Mar 2024 11:31:21 +0000 Received: from localhost ([127.0.0.1]:48511 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rkjIu-000861-LE for submit@debbugs.gnu.org; Thu, 14 Mar 2024 07:31:21 -0400 Received: from relay.yourmailgateway.de ([194.59.206.189]:60903) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rkjIr-00085q-6X for 69587@debbugs.gnu.org; Thu, 14 Mar 2024 07:31:19 -0400 Received: from relay02-mors.netcup.net (localhost [127.0.0.1]) by relay02-mors.netcup.net (Postfix) with ESMTPS id 4TwQDJ0rYrz44DS; Thu, 14 Mar 2024 12:30:40 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=pelzflorian.de; s=key2; t=1710415840; bh=6vYXkROirX+fVPY/Cz44SJCBO6d5kmpRM5F9opN5Qqg=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=lY/kXQ1jhZn2msPZFW+q0+zDfBPsYGxCdFpSgzjk/pQv6vmYfXdMFgwN9nGZ33QUc FQpAq8or8AKaB4HjBvcXrpnkondMHSBu3CiF47vVz3MEypitEcYS/pe8igRmcVRTKZ DSIKjwTbp/DpsZ9VBzMXki6ghUqVUX2UnfzqXy4US8lyD3wGx16Rkd36aw3YiLJFc4 n2FdWy+mY7oGIFofqi6nQLyNLI8cfMu4VUJRHgrXCE/UUPs7k2Ve/Pvne0NNaaFxdG qnwuMqvVcgEyA1KlbJnurcgMiCFX4jHJpRLAbI1imVcgCg9u7TiOaNCNKBKfwcf1RS HO+LLpkjVZgng== Received: from policy02-mors.netcup.net (unknown [46.38.225.35]) by relay02-mors.netcup.net (Postfix) with ESMTPS id 4TwQDJ0T9bz7x3k; Thu, 14 Mar 2024 12:30:40 +0100 (CET) Received: from mxe217.netcup.net (unknown [10.243.12.53]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by policy02-mors.netcup.net (Postfix) with ESMTPS id 4TwQDH65Tbz8svT; Thu, 14 Mar 2024 12:30:39 +0100 (CET) Received: from florianrock64 (ip92344de0.dynamic.kabel-deutschland.de [146.52.77.224]) by mxe217.netcup.net (Postfix) with ESMTPSA id 42F1882DB8; Thu, 14 Mar 2024 12:30:34 +0100 (CET) From: "pelzflorian (Florian Pelz)" To: Ludovic =?utf-8?Q?Court=C3=A8s?= Subject: Re: [bug#69587] [PATCH] doc: Add =?utf-8?Q?=E2=80=9CSource?= Tree =?utf-8?Q?Structure=E2=80=9D?= section. In-Reply-To: <877ci5iz6q.fsf@gnu.org> ("Ludovic =?utf-8?Q?Court=C3=A8s=22'?= =?utf-8?Q?s?= message of "Wed, 13 Mar 2024 22:45:01 +0100") References: <878r2sa9hd.fsf@pelzflorian.de> <877cic2xa6.fsf@gnu.org> <878r2r8o7f.fsf@pelzflorian.de> <87le6oog1j.fsf@gnu.org> <87jzm8prmg.fsf@pelzflorian.de> <877ci5iz6q.fsf@gnu.org> Date: Thu, 14 Mar 2024 12:30:33 +0100 Message-ID: <87a5n1f3ty.fsf@pelzflorian.de> User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Rspamd-Queue-Id: 42F1882DB8 X-Rspamd-Server: rspamd-worker-8404 X-NC-CID: 2uY9dwCM5j1J/mYi0yyQsGgpXvAxO43Ykm0Ty/tOf/yavuJhLTTfN8VD X-Spam-Score: -0.0 (/) X-Debbugs-Envelope-To: 69587 Cc: 69587@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Hello, thank you for moving this to a resolution. Ludovic Court=C3=A8s writes: > "pelzflorian (Florian Pelz)" skribis: >> Ludovic Court=C3=A8s writes: >>>> Nice things like (guix swh) or (gnu system), (gnu build), (gnu >>>> installer), (gnu machine), or po, still seem not useful for the general >>>> populace to me. >>> >>> This is in the =E2=80=9CContributing=E2=80=9D chapter, so we=E2=80=99re= talking about a subset >>> of the general populace. :-) >>> >>> You might argue that few current contributors care about the modules you >>> mention, but by exposing the structure of the code, my hope is that more >>> people would dare take a look and fiddle with it. > > [...] > >> Still I would prefer if (gnu system), (gnu build), (gnu installer), (gnu >> machine), and especially po, were not part of the list. I expect that >> most contributors want to provide a package or (home) service with docs >> and tests. They will not customize the operating-system record type. > > This section is intended for people willing to > contribute to Guix or to learn about it beyond packages (perhaps that > intention should be more clearly stated though; perhaps that=E2=80=99s th= e crux > of our difference of interpretation?). This is the misunderstanding. It would help if the audience is clear, so other readers can skip the section. > If the section is deemed too long, it probably makes sense to trim it a > bit, but I don=E2=80=99t find it this long. > > Or we can use different examples, though I would keep those that are > already documented elsewhere in the manual (like (gnu system)). > > WDYT? Okay, people might be curious about directories and therefore look at these not immediately important directories. Then the reason the directory nix is not talked about is that we seek to get rid of nix? That there are other sections is not a good reason, however. But it also does not seem like it was your criterion of inclusion. > =E2=80=98po=E2=80=99 > This is the location of translations of Guix itself, of package > synopses and descriptions, of the manual, and of the cookbook > (*note Translating Guix::). Could you mention directly that translations are pulled from Weblate? >>> I think =E2=80=9Cmurky=E2=80=9D is a strong word, or at least it should= n=E2=80=99t be >>> interpreted as meaning that the guix/gnu distinction is arbitrary. I= =E2=80=99ll >>> try to clarify that as well. >> >> Hmm what is the difference between, let=E2=80=99s say, (gnu packages) an= d (guix >> package)? > > (guix packages) defines a type and associated mechanisms (the > =E2=80=9Cpackage Reference=E2=80=9D section). > > (gnu packages) lets you browse packages defined in (gnu packages =E2=80= =A6), > etc. > > The former is abstract; the latter is about concrete package > definitions. I see, but this is unlike (gnu system), which is equally abstract. There is a tendency, but case-by-case it seems murky. >>> +@code{(guix @dots{})} modules@footnote{For this reason, @code{(guix >>> +@dots{})} modules must generally not depend on @code{(gnu @dots{})} >>> +modules, with one notable exception: @code{(guix build-system @dots{})} >>> +modules may look up packages at run time---e.g., @code{(guix >>> +build-system cmake)} needs to access the @code{cmake} variable at run >>> +time.}. >> >> I think the (guix build-system @dots{}) never use (gnu =E2=80=A6)? > > They do, as in the =E2=80=98cmake=E2=80=99 example above. Only by module-ref. > >> scripts and importers do. > > Oh right, that=E2=80=99s true. So there=E2=80=99s more than one notable = exception. :-) > > Ludo=E2=80=99. Regards, Florian From debbugs-submit-bounces@debbugs.gnu.org Tue Mar 19 10:17:30 2024 Received: (at 69587) by debbugs.gnu.org; 19 Mar 2024 14:17:30 +0000 Received: from localhost ([127.0.0.1]:51016 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rmaHR-0004Iq-HB for submit@debbugs.gnu.org; Tue, 19 Mar 2024 10:17:30 -0400 Received: from eggs.gnu.org ([209.51.188.92]:34394) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rmaHO-0004IN-N9 for 69587@debbugs.gnu.org; Tue, 19 Mar 2024 10:17:27 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rmaGg-0003bq-Bc; Tue, 19 Mar 2024 10:16:42 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:References:In-Reply-To:Subject:To: From; bh=aCtJBPnkybdD9LHJXn6WCwKwkwMZx8arnaapIeBXwQg=; b=SqIwwGodKTnsXpLyLpEe RXuVVfOV4Z9TXAV9tdhDmUpp7+PzI1RQDUT1i+6mwB0+fQ3GEbF06wzZpF9gcVxuWN8DXjYrdINhe aqReXnfygZ/J0D7R4//mQ9NBkS8+BXpawWmt28in4jrDxwBJk7uFemNeoLB1qBTGfDA9rP3ScpVEE l/XDzADXdozh/Q4atCEVSWndWI7EKX0BgZ/1esiLZFAHKPIiZDazG6Zbm3jW+D4IdmVHfeYkkRjfD mj/xmk1rW4CYjeHu0TB9EFkjOj9D4vyjZhnpYymDBOgc17qXHox7kmmWjNrnzsKWwCd16Ka8ERaGp X0YPZZqvpyjUJg==; From: =?utf-8?Q?Ludovic_Court=C3=A8s?= To: "pelzflorian (Florian Pelz)" Subject: Re: [bug#69587] [PATCH] doc: Add =?utf-8?Q?=E2=80=9CSource?= Tree =?utf-8?Q?Structure=E2=80=9D?= section. In-Reply-To: <87a5n1f3ty.fsf@pelzflorian.de> (pelzflorian@pelzflorian.de's message of "Thu, 14 Mar 2024 12:30:33 +0100") References: <878r2sa9hd.fsf@pelzflorian.de> <877cic2xa6.fsf@gnu.org> <878r2r8o7f.fsf@pelzflorian.de> <87le6oog1j.fsf@gnu.org> <87jzm8prmg.fsf@pelzflorian.de> <877ci5iz6q.fsf@gnu.org> <87a5n1f3ty.fsf@pelzflorian.de> Date: Tue, 19 Mar 2024 15:16:15 +0100 Message-ID: <87wmpy2tow.fsf@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 69587 Cc: 69587@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Hello! "pelzflorian (Florian Pelz)" skribis: > Ludovic Court=C3=A8s writes: [...] >> This section is intended for people willing to >> contribute to Guix or to learn about it beyond packages (perhaps that >> intention should be more clearly stated though; perhaps that=E2=80=99s t= he crux >> of our difference of interpretation?). > > This is the misunderstanding. It would help if the audience is clear, > so other readers can skip the section. Great, I=E2=80=99ll do that. >> If the section is deemed too long, it probably makes sense to trim it a >> bit, but I don=E2=80=99t find it this long. >> >> Or we can use different examples, though I would keep those that are >> already documented elsewhere in the manual (like (gnu system)). >> >> WDYT? > > Okay, people might be curious about directories and therefore look at > these not immediately important directories. Then the reason the > directory nix is not talked about is that we seek to get rid of nix? Very good point, I=E2=80=99ll add it (did my subconscious want me to forget= the project=E2=80=99s roots?). >> =E2=80=98po=E2=80=99 >> This is the location of translations of Guix itself, of package >> synopses and descriptions, of the manual, and of the cookbook >> (*note Translating Guix::). > > Could you mention directly that translations are pulled from Weblate? Sure. >>> Hmm what is the difference between, let=E2=80=99s say, (gnu packages) a= nd (guix >>> package)? >> >> (guix packages) defines a type and associated mechanisms (the >> =E2=80=9Cpackage Reference=E2=80=9D section). >> >> (gnu packages) lets you browse packages defined in (gnu packages =E2=80= =A6), >> etc. >> >> The former is abstract; the latter is about concrete package >> definitions. > > I see, but this is unlike (gnu system), which is equally abstract. > There is a tendency, but case-by-case it seems murky. Yeah okay, maybe. :-) I=E2=80=99ll work on a new version. Thanks for your patience, Ludo=E2=80=99. From debbugs-submit-bounces@debbugs.gnu.org Wed Mar 20 07:08:44 2024 Received: (at 69587) by debbugs.gnu.org; 20 Mar 2024 11:08:44 +0000 Received: from localhost ([127.0.0.1]:38871 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rmtoJ-0008SA-T5 for submit@debbugs.gnu.org; Wed, 20 Mar 2024 07:08:44 -0400 Received: from eggs.gnu.org ([209.51.188.92]:54064) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rmtoH-0008Rn-MH for 69587@debbugs.gnu.org; Wed, 20 Mar 2024 07:08:42 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rmtVg-0000Ze-Db; Wed, 20 Mar 2024 06:49:28 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:References:In-Reply-To:Date:Subject:To: From; bh=i39i4C2lURkJTEJR/wcm6nHckK94Ri4SCOBMHwEQpbM=; b=fbR+uNTM4vfGoAOvZCsd JirsHJ1excHOfYD44+uJ1grGZj+uD6gemB/FPy6PX0NPfnOO8Zpb4B2hM4L67IQb8NipwUWlSHKo0 mPyZRfYZEeLl7yzb9yDqf3+VZ0LK1LaHauHBje273HzrjaHfwE4ReiS+T0o128OvCJj0garNqcby1 2ybPQqEoyldLiPRa8BSr7i+ZJmZDbdcr+nqfkfFeOK+vADOnfbll6hgYNVS9m+LKOiTvIN71mV/W8 0Z1dkMEyqlKttsfec3NgYv4eX+O3Ma6SIsKurCzLQ0lnklXKvHJVDsTw30cIFtUuZijZzTvPjVHy5 3rijpYso1AlidA==; From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= To: 69587@debbugs.gnu.org Subject: [PATCH v2] =?UTF-8?q?doc:=20Add=20=E2=80=9CSource=20Tree=20Struct?= =?UTF-8?q?ure=E2=80=9D=20section.?= Date: Wed, 20 Mar 2024 11:49:13 +0100 Message-ID: <4b50aca680226c4eeba9b83f1d82d935aaae382d.1710931512.git.ludo@gnu.org> X-Mailer: git-send-email 2.41.0 In-Reply-To: <87wmpy2tow.fsf@gnu.org> References: <87wmpy2tow.fsf@gnu.org> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 69587 Cc: =?UTF-8?q?Ludovic=20Court=C3=A8s?= , pelzflorian@pelzflorian.de X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) * doc/contributing.texi (Source Tree Structure): New node. * doc/guix.texi (Programming Interface): Add cross-reference. Change-Id: I141a1f4d806ae5f72c7a246e18c14dc63056a607 --- doc/contributing.texi | 252 +++++++++++++++++++++++++++++++++++++++++- doc/guix.texi | 3 +- 2 files changed, 253 insertions(+), 2 deletions(-) Hi! Changes since v1: • Clarify the intended audience upfront. • Mention the nix/ directory. • Explain that .po files are taken from Weblate. • Explain what “core mechanisms” means. • Clarify guix/gnu module name space distinction. Ludo’. diff --git a/doc/contributing.texi b/doc/contributing.texi index a7d91724fb..17ecf4a04c 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -23,7 +23,8 @@ Contributing * Building from Git:: The latest and greatest. * Running Guix Before It Is Installed:: Hacker tricks. * The Perfect Setup:: The right tools. -* Alternative Setups:: Other posible tools that do the job. +* Alternative Setups:: Other possible tools that do the job. +* Source Tree Structure:: Source code guided tour. * Packaging Guidelines:: Growing the distribution. * Coding Style:: Hygiene of the contributor. * Submitting Patches:: Share your work. @@ -546,6 +547,255 @@ Vim and NeoVim process and inject your code there live (sadly it's not packaged in Guix yet). +@node Source Tree Structure +@section Source Tree Structure + +@cindex structure, of the source tree +If you're willing to contribute to Guix beyond packages, or if you'd +like to learn how it all fits together, this section provides a guided +tour in the code base that you may find useful. + +Overall, the Guix source tree contains almost exclusively Guile +@dfn{modules}, each of which can be seen as an independent library +(@pxref{Modules,,, guile, GNU Guile Reference Manual}). + +The following table gives an overview of the main directories and what +they contain. Remember that in Guile, each module name is derived from +its file name---e.g., the module in file@file{guix/packages.scm} is +called @code{(guix packages)}. + +@table @file +@item guix +This is the location of core Guix mechanisms. To illustrate what is +meant by ``core'', here are a few examples, starting from low-level +tools and going towards higher-level tools: + +@table @code +@item (guix store) +Connecting to and interacting with the build daemon (@pxref{The Store}). +@item (guix derivations) +Creating derivations (@pxref{Derivations}). +@item (guix gexps) +Writing G-expressions (@pxref{G-Expressions}). +@item (guix packages) +Defining packages and origins (@pxref{package Reference}). +@item (guix download) +@itemx (guix git-download) +The @code{url-fetch} and @code{git-fetch} origin download methods +(@pxref{origin Reference}). +@item (guix swh) +Fetching source code from the +@uref{https://archive.softwareheritage.org,Software Heritage archive}. +@item (guix search-paths) +Implementing search paths (@pxref{Search Paths}). +@item (guix build-system) +The build system interface (@pxref{Build Systems}). +@item (guix profiles) +Implementing profiles. +@end table + +@cindex build system, directory structure +@item guix/build-system +This directory contains specific build system implementations +(@pxref{Build Systems}), such as: + +@table @code +@item (guix build-system gnu) +the GNU build system; +@item (guix build-system cmake) +the CMake build system; +@item (guix build-system pyproject) +The Python ``pyproject'' build system. +@end table + +@item guix/build +This contains code generally used on the ``build side'' +(@pxref{G-Expressions, strata of code}). This includes code used to +build packages or other operating system components, as well as +utilities: + +@table @code +@item (guix build utils) +Utilities for package definitions and more (@pxref{Build Utilities}). +@item (guix build gnu-build-system) +@itemx (guix build cmake-build-system) +@itemx (guix build pyproject-build-system) +Implementation of build systems, and in particular definition of their +build phases (@pxref{Build Phases}). +@item (guix build syscalls) +Interface to the C library and to Linux system calls. +@end table + +@cindex command-line tools, as Guile modules +@cindex command modules +@item guix/scripts +This contains modules corresponding to @command{guix} sub-commands. For +example, the @code{(guix scripts shell)} module exports the +@code{guix-shell} procedure, which directly corresponds to the +@command{guix shell} command (@pxref{Invoking guix shell}). + +@cindex importer modules +@item guix/import +This contains supporting code for the importers and updaters +(@pxref{Invoking guix import}, and @pxref{Invoking guix refresh}). For +example, @code{(guix import pypi)} defines the interface to PyPI, which +is used by the @code{guix import pypi} command. +@end table + +The directories we have seen so far all live under @file{guix/}. The +other important place is the @file{gnu/} directory, which contains +primarily package definitions as well as libraries and tools for Guix +System (@pxref{System Configuration}) and Guix Home (@pxref{Home +Configuration}), all of which build upon functionality provided by +@code{(guix @dots{})} modules@footnote{For this reason, @code{(guix +@dots{})} modules must generally not depend on @code{(gnu @dots{})} +modules, with one notable exception: @code{(guix build-system @dots{})} +modules may look up packages at run time---e.g., @code{(guix +build-system cmake)} needs to access the @code{cmake} variable at run +time.}. + +@table @file +@cindex package modules +@item gnu/packages +This is by far the most crowded directory of the source tree: it +contains @dfn{package modules} that export package definitions +(@pxref{Package Modules}). A few examples: + +@table @code +@item (gnu packages base) +Module providing ``base'' packages: @code{glibc}, @code{coreutils}, +@code{grep}, etc. +@item (gnu packages guile) +Guile and core Guile packages. +@item (gnu packages linux) +The Linux-libre kernel and related packages. +@item (gnu packages python) +Python and core Python packages. +@item (gnu packages python-xyz) +Miscellaneous Python packages (we were not very creative). +@end table + +In any case, you can jump to a package definition using @command{guix +edit} (@pxref{Invoking guix edit}) and view its location with +@command{guix show} (@pxref{Invoking guix package}). + +@findex search-patches +@item gnu/packages/patches +This directory contains patches applied against packages and obtained +using the @code{search-patches} procedure. + +@item gnu/services +This contains service definitions, primarily for Guix System +(@pxref{Services}) but some of them are adapted and reused for Guix Home +as we will see below. Examples: + +@table @code +@item (gnu services) +The service framework itself, which defines the service and service type +data types (@pxref{Service Composition}). +@item (gnu services base) +``Base'' services (@pxref{Base Services}). +@item (gnu services desktop) +``Desktop'' services (@pxref{Desktop Services}). +@item (gnu services shepherd) +Support for Shepherd services (@pxref{Shepherd Services}). +@end table + +You can jump to a service definition using @command{guix system edit} +and view its location with @command{guix system search} (@pxref{Invoking +guix system}). + +@item gnu/system +These are core Guix System modules, such as: + +@table @code +@item (gnu system) +Defines @code{operating-system} (@pxref{operating-system Reference}). +@item (gnu system file-systems) +Defines @code{file-system} (@pxref{File Systems}). +@item (gnu system mapped-devices) +Defines @code{mapped-device} (@pxref{Mapped Devices}). +@end table + +@item gnu/build +These are modules that are either used on the ``build side'' when +building operating systems or packages, or at run time by operating +systems. + +@table @code +@item (gnu build accounts) +Creating @file{/etc/passwd}, @file{/etc/shadow}, etc. (@pxref{User +Accounts}). +@item (gnu build activation) +Activating an operating system at boot time or reconfiguration time. +@item (gnu build file-systems) +Searching, checking, and mounting file systems. +@item (gnu build linux-boot) +@itemx (gnu build hurd-boot) +Booting GNU/Linux and GNU/Hurd operating systems. +@item (gnu build linux-initrd) +Creating a Linux initial RAM disk (@pxref{Initial RAM Disk}). +@end table + +@item gnu/home +This contains all things Guix Home (@pxref{Home Configuration}); +examples: + +@table @code +@item (gnu home services) +Core services such as @code{home-files-service-type}. +@item (gnu home services ssh) +SSH-related services (@pxref{Secure Shell}). +@end table + +@item gnu/installer +This contains the text-mode graphical system installer (@pxref{Guided +Graphical Installation}). + +@item gnu/machine +These are the @dfn{machine abstractions} used by @command{guix deploy} +(@pxref{Invoking guix deploy}). + +@item gnu/tests +This contains system tests---tests that spawn virtual machines to check +that system services work as expected (@pxref{Running the Test Suite}). +@end table + +Last, there's also a few directories that contain files that are +@emph{not} Guile modules: + +@table @file +@item nix +This is the C++ implementation of @command{guix-daemon}, inherited from +Nix (@pxref{Invoking guix-daemon}). + +@item tests +These are unit tests, each file corresponding more or less to one +module, in particular @code{(guix @dots{})} modules (@pxref{Running the +Test Suite}). + +@item doc +This is the documentation in the form of Texinfo files: this manual and +the Cookbook. @xref{Writing a Texinfo File,,, texinfo, GNU Texinfo}, +for information on Texinfo markup language. + +@item po +This is the location of translations of Guix itself, of package synopses +and descriptions, of the manual, and of the cookbook. Note that +@file{.po} files that live here are pulled directly from Weblate +(@pxref{Translating Guix}).` + +@item etc +Miscellaneous files: shell completions, support for systemd and other +init systems, Git hooks, etc. +@end table + +With all this, a fair chunk of your operating system is at your +fingertips! Beyond @command{grep} and @command{git grep}, @pxref{The +Perfect Setup} on how to navigate code from your editor, and +@pxref{Using Guix Interactively} for information on how to use +interactively use Scheme modules. Enjoy! + @node Packaging Guidelines @section Packaging Guidelines diff --git a/doc/guix.texi b/doc/guix.texi index 20f007b1c0..138d53602f 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -7680,7 +7680,8 @@ Programming Interface that build results @emph{derive} from them. This chapter describes all these APIs in turn, starting from high-level -package definitions. +package definitions. @xref{Source Tree Structure}, for a more general +overview of the source code. @menu * Package Modules:: Packages from the programmer's viewpoint. base-commit: b7eb1a8116b2caee7acf26fb963ae998fbdb4253 -- 2.41.0 From debbugs-submit-bounces@debbugs.gnu.org Wed Mar 20 14:21:59 2024 Received: (at 69587) by debbugs.gnu.org; 20 Mar 2024 18:22:00 +0000 Received: from localhost ([127.0.0.1]:54550 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rn0Zb-0000jg-Ek for submit@debbugs.gnu.org; Wed, 20 Mar 2024 14:21:59 -0400 Received: from relay.yourmailgateway.de ([188.68.63.98]:59693) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rn0ZY-0000jU-Uy for 69587@debbugs.gnu.org; Wed, 20 Mar 2024 14:21:58 -0400 Received: from mors-relay-2501.netcup.net (localhost [127.0.0.1]) by mors-relay-2501.netcup.net (Postfix) with ESMTPS id 4V0FMW6GMqz62jm; Wed, 20 Mar 2024 18:05:11 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=pelzflorian.de; s=key2; t=1710954311; bh=SjXQFEH21SpycDqVmnrI2Pwr+jxjzYe1ZTNtws1PmzI=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=FGH1q8OtHdOx5TMvhbIv39eloBSc8VR0XbL/c49FCO8iK2Pk1Aug2Fsg3DiR04bnA k3QUdkJlkeQtNC7Z/Xt4IbPQqAGUtLxlMaXpVKTduTDv9sK55qXuHMu/k7RN+CfE0k qF+TY48g3mtBME6ZrOGdQ6NNb9a6m+WbPWgNrdEO+unEdDfO88v0PKR/6/DdVBB8O5 dP4mySAkeYr5gFyt3P61lpOHq7RhAFspXpZ0YXg0i5/mPyWHUrf+6K+qJpKLS6N//W 09K4JsvitbUmneAGtHh1kbCBpbBJPBMmcPsHp0AVrsEQi5KL5OY53sRtIHe0kt6Gbn O+XK6ZxHkzp+A== Received: from policy02-mors.netcup.net (unknown [46.38.225.35]) by mors-relay-2501.netcup.net (Postfix) with ESMTPS id 4V0FMW5ZJRz4xwc; Wed, 20 Mar 2024 18:05:11 +0100 (CET) Received: from mxe217.netcup.net (unknown [10.243.12.53]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by policy02-mors.netcup.net (Postfix) with ESMTPS id 4V0FMW39Myz8sb8; Wed, 20 Mar 2024 18:05:11 +0100 (CET) Received: from florianrock64 (ip92344de0.dynamic.kabel-deutschland.de [146.52.77.224]) by mxe217.netcup.net (Postfix) with ESMTPSA id C799B833F2; Wed, 20 Mar 2024 18:05:05 +0100 (CET) From: "pelzflorian (Florian Pelz)" To: Ludovic =?utf-8?Q?Court=C3=A8s?= Subject: Re: [PATCH v2] doc: Add =?utf-8?Q?=E2=80=9CSource?= Tree =?utf-8?Q?Structure=E2=80=9D?= section. In-Reply-To: <4b50aca680226c4eeba9b83f1d82d935aaae382d.1710931512.git.ludo@gnu.org> ("Ludovic =?utf-8?Q?Court=C3=A8s=22's?= message of "Wed, 20 Mar 2024 11:49:13 +0100") References: <87wmpy2tow.fsf@gnu.org> <4b50aca680226c4eeba9b83f1d82d935aaae382d.1710931512.git.ludo@gnu.org> Date: Wed, 20 Mar 2024 18:05:04 +0100 Message-ID: <87bk78u94v.fsf@pelzflorian.de> User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Rspamd-Queue-Id: C799B833F2 X-Rspamd-Server: rspamd-worker-8404 X-NC-CID: Hwf/NRScGShhs/oLnCKM2rE4va7vNnpio4kYThtXFfs8o6Niq2KszTSC X-Spam-Score: -0.0 (/) X-Debbugs-Envelope-To: 69587 Cc: 69587@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Hello, some small things to fix: Ludovic Court=C3=A8s writes: > +The following table gives an overview of the main directories and what > +they contain. Remember that in Guile, each module name is derived from > +its file name---e.g., the module in file@file{guix/packages.scm} The file@file should be @file, I presume. > [=E2=80=A6] > +The directories we have seen so far all live under @file{guix/}. The > +other important place is the @file{gnu/} directory, which contains > +primarily package definitions as well as libraries and tools for Guix > +System (@pxref{System Configuration}) and Guix Home (@pxref{Home > +Configuration}), all of which build upon functionality provided by > +@code{(guix @dots{})} modules@footnote{For this reason, @code{(guix > +@dots{})} modules The double space is inappropriate. > must generally not depend on @code{(gnu @dots{})} > +modules, with one notable exception: Perhaps better mention all three exceptions, not only build-system but also direct #:use-module in scripts like pack and to a lesser degree import. > +@item po > +This is the location of translations of Guix itself, of package synopses > +and descriptions, of the manual, and of the cookbook. Note that > +@file{.po} files that live here are pulled directly from Weblate > +(@pxref{Translating Guix}).` At the end is a stray `. > +With all this, a fair chunk of your operating system is at your > +fingertips! Beyond @command{grep} and @command{git grep}, @pxref{The > +Perfect Setup} on how to navigate code from your editor, and > +@pxref{Using Guix Interactively} for information on how to use > +interactively use Scheme modules. Enjoy! The word =E2=80=9Cuse=E2=80=9D is duplicated. Otherwise I=E2=80=99m happy and it LGTM. Thank you! Regards, Florian From debbugs-submit-bounces@debbugs.gnu.org Thu Mar 21 12:50:13 2024 Received: (at 69587-done) by debbugs.gnu.org; 21 Mar 2024 16:50:13 +0000 Received: from localhost ([127.0.0.1]:43671 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rnLcK-000105-1G for submit@debbugs.gnu.org; Thu, 21 Mar 2024 12:50:12 -0400 Received: from eggs.gnu.org ([209.51.188.92]:56928) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rnLcH-0000zf-HN for 69587-done@debbugs.gnu.org; Thu, 21 Mar 2024 12:50:10 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rnLbX-0000I6-Gq; Thu, 21 Mar 2024 12:49:23 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:References:In-Reply-To:Subject:To: From; bh=mw4Wh/YsiuYeZNtEszFQY/1ScUD0X6hc7UvFn5xqXUQ=; b=O06DUAcJzhuFDfCqoGX6 uy4xJJOZPPiz51rFD/wzWuB9MvT18EoLqYdyEKBZXAKC2ibjFYZ70lXkmdl6tesRDAAnpO51D+ysi 901SspgI/E28c/ah8rupmSElRte1Rt2lZJlG1L9qvA9OGnJTFTZtBE8XJDtpBLlW2h1rmJuKutgfX n5p4FcljYGQzuEC0sj+m1CRxypAmGKui4tbXCkuhYZ47dTTEPqI1IH7P+WoK//kA/PZCcFTulH+Ex jp0cXeM4QQJbdSXsO9wYAnc/L5jRVPQosxa3sI311BgX5SdFeUY+WpcMpZsqQ3foyAnQ+uJ1OHiya TM45wAPyr1xdXw==; From: =?utf-8?Q?Ludovic_Court=C3=A8s?= To: "pelzflorian (Florian Pelz)" Subject: Re: [bug#69587] [PATCH v2] doc: Add =?utf-8?Q?=E2=80=9CSource?= Tree =?utf-8?Q?Structure=E2=80=9D?= section. In-Reply-To: <87bk78u94v.fsf@pelzflorian.de> (pelzflorian@pelzflorian.de's message of "Wed, 20 Mar 2024 18:05:04 +0100") References: <87wmpy2tow.fsf@gnu.org> <4b50aca680226c4eeba9b83f1d82d935aaae382d.1710931512.git.ludo@gnu.org> <87bk78u94v.fsf@pelzflorian.de> Date: Thu, 21 Mar 2024 17:49:00 +0100 Message-ID: <87wmpvtts3.fsf@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 69587-done Cc: 69587-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Hi, "pelzflorian (Florian Pelz)" skribis: > Otherwise I=E2=80=99m happy and it LGTM. Thank you! Fixed all the typos (oops!), added more exceptions in the guix/gnu footnote, and pushed as d67e4f0f9b10c7ddac8fb0ca68cbf1d6ad0a6e5d. Thanks again for your patience! Ludo=E2=80=99. From unknown Mon Aug 18 08:27:48 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Fri, 19 Apr 2024 11:24:24 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator