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

[pelzflorian (Florian Pelz)]

Hi Ludo.

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.

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?

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 …) and the occasional duality with (guix build
…-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 “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.

Regards,
Florian