[bug#69587] [PATCH] doc: Add “Source Tree Structure” section.

["Ludovic Courtès" <ludo@gnu.org>]

[-- Attachment #1: Type: text/plain, Size: 2431 bytes --]

Hello!

"pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> skribis:

> Josselin’s 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’s talk.

Right.

> Ludovic Courtès <ludo@gnu.org> writes:
>> The order I chose is (roughly) from lower-level to higher-level:
>>
>> (guix store) -> (guix derivation) -> (guix packages) -> …
>> … -> (gnu packages) -> (gnu system) -> …
>>
>> Does that make sense?
>
> In your section the modules directly in (guix …) appeared unsorted 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 “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.

[...]

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

I was going to send a v2 but I’m not sure the changes I made fully
address your concerns:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Type: text/x-patch, Size: 1388 bytes --]

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

[-- Attachment #3: Type: text/plain, Size: 52 bytes --]


Let me know what you think!

Thanks,
Ludo’.