Re: [PATCH] doc: "Introduction" revise and add figure.

[Ludovic Courtès]

Hi!

After much hesitation and questions, I ended up pushing something
similar in spirit to what you suggest, but with my own words (commit
6f773606812075ee5c6747c3b7f95285254e48f2).

The suggestion you made of describing features “top-down” made a lot of
sense to me, esp. compared to the previous one which insisted on the
“functional paradigm”, which is not really the first thing newcomers are
interested in.  However, I felt a few things needed a different
explanation.

Also, while I agree that illustrations would be helpful, I’m not
satisfied with the diagram you proposed.  I think the meaning of arrows
is unclear, and it also puts too much emphasis on Hydra, “system
profiles”, and “system services.”

Anyway, below is the intro as it currently appears in ‘master’.

Thank you!

Ludo’.


GNU Guix(1) is a package management tool for the GNU system.  Guix makes
it easy for unprivileged users to install, upgrade, or remove packages,
to roll back to a previous package set, to build packages from source,
and generally assists with the creation and maintenance of software
environments.

   Guix provides a command-line package management interface (*note
Invoking guix package::), a set of command-line utilities (*note
Utilities::), a visual user interface in Emacs (*note Emacs
Interface::), as well as Scheme programming interfaces (*note
Programming Interface::).  Its “build daemon” is responsible for
building packages on behalf of users (*note Setting Up the Daemon::) and
for downloading pre-built binaries from authorized sources (*note
Substitutes::).

   Guix includes package definitions for many GNU and non-GNU packages,
all of which respect the user’s computing freedom
(https://www.gnu.org/philosophy/free-sw.html).  It is _extensible_:
users can write their own package definitions (*note Defining
Packages::) and make them available as independent package modules
(*note Package Modules::).  It is also _customizable_: users can
_derive_ specialized package definitions from existing ones, including
from the command line (*note Package Transformation Options::).

   You can install GNU Guix on top of an existing GNU/Linux system where
it complements the available tools without interference (*note
Installation::), or you can use it as part of the standalone “Guix
System Distribution” or GuixSD (*note GNU Distribution::).  With
GNU GuixSD, you _declare_ all aspects of the operating system
configuration and Guix takes care of instantiating the configuration in
a transactional, reproducible, and stateless fashion (*note System
Configuration::).

   Under the hood, Guix implements the “functional package management”
discipline pioneered by Nix (*note Acknowledgments::).  In Guix, the
package build and installation process is seen as a _function_, in the
mathematical sense.  That function takes inputs, such as build scripts,
a compiler, and libraries, and returns an installed package.  As a pure
function, its result depends solely on its inputs—for instance, it
cannot refer to software or scripts that were not explicitly passed as
inputs.  A build function always produces the same result when passed a
given set of inputs.  It cannot alter the environment of the running
system in any way; for instance, it cannot create, modify, or delete
files outside of its build and installation directories.  This is
achieved by running build processes in isolated environments (or
“containers”), where only their explicit inputs are visible.

   The result of package build functions is “cached” in the file system,
in a special directory called “the store” (*note The Store::).  Each
package is installed in a directory of its own in the store—by default
under ‘/gnu/store’.  The directory name contains a hash of all the
inputs used to build that package; thus, changing an input yields a
different directory name.

   This approach is the foundation for the salient features of Guix:
support for transactional package upgrade and rollback, per-user
installation, and garbage collection of packages (*note Features::).

   ---------- Footnotes ----------

   (1) “Guix” is pronounced like “geeks”, or “ɡiːks” using the
international phonetic alphabet (IPA).