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

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Ludovic Courtès <ludo <at> gnu.org>
Subject: bug#69587: closed (Re: [bug#69587] [PATCH v2] doc: Add
 “Source Tree Structure” section.)
Date: Thu, 21 Mar 2024 16:51:02 +0000

[Message part 1 (text/plain, inline)]

Your bug report

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

which was filed against the guix-patches package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to 69587 <at> debbugs.gnu.org.

-- 
69587: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=69587
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

From: Ludovic Courtès <ludo <at> gnu.org>
To: "pelzflorian (Florian Pelz)" <pelzflorian <at> pelzflorian.de>
Cc: 69587-done <at> debbugs.gnu.org
Subject: Re: [bug#69587] [PATCH v2] doc: Add “Source
 Tree Structure” section.
Date: Thu, 21 Mar 2024 17:49:00 +0100

Hi,

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

> Otherwise I’m 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’.

[Message part 3 (message/rfc822, inline)]

From: Ludovic Courtès <ludo <at> gnu.org>
To: guix-patches <at> gnu.org
Cc: Ludovic Courtès <ludo <at> gnu.org>
Subject: [PATCH] doc: Add “Source Tree Structure” section.
Date: Wed,  6 Mar 2024 17:37:47 +0100

* 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 <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.