| Message ID | 87le6oog1j.fsf@gnu.org |
|---|---|
| State | New |
| Headers | show |
| Series | [bug#69587] doc: Add “Source Tree Structure” section. | expand |
Hi Ludo. Ludovic Courtès <ludo@gnu.org> 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 “Contributing” chapter, so we’re 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. 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 “core”. Do you >>> think some other adjective or a longer description would help? >>> >>>> Perhaps (guix …) should be listed after (gnu …) and defined as the >>>> Guix mechanisms that do not belong in gnu? Not quite sure either. >> >> Josselin called the distinction between (guix …) and (gnu …) murky, >> explaining that most of (guix …) must not import (gnu …) except by >> module-ref, while (guix scripts …) and such can just use-modules (gnu >> …). To me, gnu/packages.scm looks like core as well, but it rightfully >> is in gnu. > > I think “murky” is a strong word, or at least it shouldn’t be > interpreted as meaning that the guix/gnu distinction is arbitrary. I’ll > try to clarify that as well. Hmm what is the difference between, let’s say, (gnu packages) and (guix package)? > @@ -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.}. I think the (guix build-system @dots{}) never use (gnu …)? scripts and importers do. Regards, Florian
Hello Ludo' thank you for this patch, I find it super useful I don't have specific comments, just general ones. Ludovic Courtès <ludo@gnu.org> writes: > "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> 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’s >> talk. > > Right. I appreciate Josselin’s talk very much, but in general I prefer studying 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 “Contributing” chapter, so we’re talking 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 …) and (gnu …) murky, >> explaining that most of (guix …) must not import (gnu …) except by >> module-ref, while (guix scripts …) and such can just use-modules (gnu >> …). To me, gnu/packages.scm looks like core as well, but it rightfully >> is in gnu. > > I think “murky” is a strong word, or at least it shouldn’t be > interpreted as meaning that the guix/gnu distinction is arbitrary. I’ll > 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 :-)
Thank you Giovanni for voicing support; I’m afraid I sounded more opposed than I am. Giovanni Biscuolo <g@xelera.eu> 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? ‘gnu/system’ These are core Guix System modules, such as: ‘(gnu system)’ Defines ‘operating-system’ (*note operating-system Reference::). ‘(gnu system file-systems)’ Defines ‘file-system’ (*note File Systems::). ‘(gnu system mapped-devices)’ Defines ‘mapped-device’ (*note Mapped Devices::). ‘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. ‘(gnu build accounts)’ Creating ‘/etc/passwd’, ‘/etc/shadow’, etc. (*note User Accounts::). ‘(gnu build activation)’ Activating an operating system at boot time or reconfiguration time. ‘(gnu build file-systems)’ Searching, checking, and mounting file systems. ‘(gnu build linux-boot)’ ‘(gnu build hurd-boot)’ Booting GNU/Linux and GNU/Hurd operating systems. ‘(gnu build linux-initrd)’ Creating a Linux initial RAM disk (*note Initial RAM Disk::). […] ‘gnu/installer’ This contains the text-mode graphical system installer (*note Guided Graphical Installation::). ‘gnu/machine’ These are the “machine abstractions” used by ‘guix deploy’ (*note Invoking guix deploy::). […] ‘po’ 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
Hello, "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> skribis: > Ludovic Courtès <ludo@gnu.org> 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 “Contributing” chapter, so we’re 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’s the crux of our difference of interpretation?). I wouldn’t 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’t 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 “murky” is a strong word, or at least it shouldn’t be >> interpreted as meaning that the guix/gnu distinction is arbitrary. I’ll >> try to clarify that as well. > > Hmm what is the difference between, let’s say, (gnu packages) and (guix > package)? (guix packages) defines a <package> type and associated mechanisms (the “package Reference” section). (gnu packages) lets you browse packages defined in (gnu packages …), 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 …)? They do, as in the ‘cmake’ example above. > scripts and importers do. Oh right, that’s true. So there’s more than one notable exception. :-) Ludo’.
Hello, thank you for moving this to a resolution. Ludovic Courtès <ludo@gnu.org> writes: > "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> skribis: >> Ludovic Courtès <ludo@gnu.org> 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 “Contributing” chapter, so we’re 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’s the 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’t 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. > ‘po’ > 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 “murky” is a strong word, or at least it shouldn’t be >>> interpreted as meaning that the guix/gnu distinction is arbitrary. I’ll >>> try to clarify that as well. >> >> Hmm what is the difference between, let’s say, (gnu packages) and (guix >> package)? > > (guix packages) defines a <package> type and associated mechanisms (the > “package Reference” section). > > (gnu packages) lets you browse packages defined in (gnu packages …), > 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 …)? > > They do, as in the ‘cmake’ example above. Only by module-ref. > >> scripts and importers do. > > Oh right, that’s true. So there’s more than one notable exception. :-) > > Ludo’. Regards, Florian
Hello! "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> skribis: > Ludovic Courtès <ludo@gnu.org> 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’s the 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’ll do that. >> If the section is deemed too long, it probably makes sense to trim it a >> bit, but I don’t 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’ll add it (did my subconscious want me to forget the project’s roots?). >> ‘po’ >> 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’s say, (gnu packages) and (guix >>> package)? >> >> (guix packages) defines a <package> type and associated mechanisms (the >> “package Reference” section). >> >> (gnu packages) lets you browse packages defined in (gnu packages …), >> 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’ll work on a new version. Thanks for your patience, Ludo’.
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