[PATCH 0/4] Re-organize the manual

  • Done
  • quality assurance status badge
Details
2 participants
  • Ludovic Courtès
  • Ricardo Wurmus
Owner
unassigned
Submitted by
Ludovic Courtès
Severity
normal
L
L
Ludovic Courtès wrote on 21 Jan 2019 11:47
(address . guix-patches@gnu.org)(name . Ludovic Courtès)(address . ludo@gnu.org)
20190121104741.14511-1-ludo@gnu.org
Hello Guix!

This is the great season cleanup of the manual. I think it provides
a clearer view of what’s available. Until now, the top-level chapters
were:

Toggle snippet (9 lines)
* Introduction:: What is Guix about?
* Installation:: Installing Guix.
* Package Management:: Package installation, upgrade, etc.
* Programming Interface:: Using Guix in Scheme.
* Utilities:: Package management commands.
* GNU Distribution:: Software for your friendly GNU system.
* Contributing:: Your help needed!

With these changes, that becomes:

Toggle snippet (15 lines)
* Introduction:: What is Guix about?
* Installation:: Installing Guix.
* System Installation:: Installing the whole operating system.
* Package Management:: Package installation, upgrade, etc.
* Programming Interface:: Using Guix in Scheme.
* Utilities:: Package management commands.
* System Configuration:: Configuring the operating system.
* Documentation:: Browsing software user manuals.
* Installing Debugging Files:: Feeding the debugger.
* Security Updates:: Deploying security fixes quickly.
* Bootstrapping:: GNU/Linux built from scratch.
* Porting:: Targeting another platform or kernel.
* Contributing:: Your help needed!

Things about “the distro” in a broad sense are no longer hidden
under “GNU Distribution” and the introduction no longer ignores
Guix System.

Next up I’d like us to get rid of these catch-all “Utilities”
section and instead organize things by activities, such as
“Development”, “Distributing Substitutes”, and “Managing Storage
Space”.

Later I’d like to move each chapter to its own .texi file, which
will be nicer and will help Emacs build menus (currently it’s
confused because only one chapter leaves in a separate file.)

Thoughts?

Ludo’.

Ludovic Courtès (4):
doc: Move sections under "GNU Distribution" one level higher.
doc: Move "System Installation" right after "Installation".
doc: Move "Packaging Guidelines" under "Contributing".
doc: Move "Package Modules" under "Programming Interface".

doc/contributing.texi | 450 ++++++++
doc/guix.texi | 2254 ++++++++++++++++-------------------------
2 files changed, 1336 insertions(+), 1368 deletions(-)

--
2.20.1
L
L
Ludovic Courtès wrote on 21 Jan 2019 12:02
[PATCH 1/4] doc: Move sections under "GNU Distribution" one level higher.
(address . 34156@debbugs.gnu.org)(name . Ludovic Courtès)(address . ludo@gnu.org)
20190121110238.15225-1-ludo@gnu.org
* doc/guix.texi (Introduction): Add note about Guix System.
[Managing Software the Guix Way]: New section heading.
[GNU Distribution]: New subsection of "Introduction". Mention "Guix
System" rather than "GuixSD" and update the list of supported systems.
(GNU Distribution): Remove as a chapter.
(System Installation, System Configuration, Documentation)
(Installing Debugging Files, Security Updates, Package Modules)
(Packaging Guidelines, Bootstrapping, Porting): Turn these sections
into chapters.
---
doc/guix.texi | 395 ++++++++++++++++++++++++--------------------------
1 file changed, 187 insertions(+), 208 deletions(-)

Toggle diff (509 lines)
diff --git a/doc/guix.texi b/doc/guix.texi
index 245a18bc70..0fa4ec27a6 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -120,7 +120,15 @@ Project}.
* Package Management:: Package installation, upgrade, etc.
* Programming Interface:: Using Guix in Scheme.
* Utilities:: Package management commands.
-* GNU Distribution:: Software for your friendly GNU system.
+* System Installation:: Installing the whole operating system.
+* System Configuration:: Configuring the operating system.
+* Documentation:: Browsing software user manuals.
+* Installing Debugging Files:: Feeding the debugger.
+* Security Updates:: Deploying security fixes quickly.
+* Package Modules:: Packages from the programmer's viewpoint.
+* Packaging Guidelines:: Growing the distribution.
+* Bootstrapping:: GNU/Linux built from scratch.
+* Porting:: Targeting another platform or kernel.
* Contributing:: Your help needed!
* Acknowledgments:: Thanks!
@@ -210,18 +218,6 @@ Invoking @command{guix build}
* Additional Build Options:: Options specific to 'guix build'.
* Debugging Build Failures:: Real life packaging experience.
-GNU Distribution
-
-* System Installation:: Installing the whole operating system.
-* System Configuration:: Configuring the operating system.
-* Documentation:: Browsing software user manuals.
-* Installing Debugging Files:: Feeding the debugger.
-* Security Updates:: Deploying security fixes quickly.
-* Package Modules:: Packages from the programmer's viewpoint.
-* Packaging Guidelines:: Growing the distribution.
-* Bootstrapping:: GNU/Linux built from scratch.
-* Porting:: Targeting another platform or kernel.
-
System Installation
* Limitations:: What you can expect.
@@ -297,21 +293,6 @@ Packaging Guidelines
* Java Packages:: Coffee break.
* Fonts:: Fond of fonts.
-Contributing
-
-* Building from Git:: The latest and greatest.
-* Running Guix Before It Is Installed:: Hacker tricks.
-* The Perfect Setup:: The right tools.
-* Coding Style:: Hygiene of the contributor.
-* Submitting Patches:: Share your work.
-
-Coding Style
-
-* Programming Paradigm:: How to compose your elements.
-* Modules:: Where to store your code?
-* Data Types and Pattern Matching:: Implementing data structures.
-* Formatting Code:: Writing conventions.
-
@end detailmenu
@end menu
@@ -322,11 +303,22 @@ Coding Style
@cindex purpose
GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``?i?ks''
using the international phonetic alphabet (IPA).} 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
+management tool for and distribution of the GNU system.
+Guix makes it easy for unprivileged
+users to install, upgrade, or remove software 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.
+@cindex Guix System
+@cindex GuixSD
+You can install GNU@tie{}Guix on top of an existing GNU/Linux system where it
+complements the available tools without interference (@pxref{Installation}),
+or you can use it as a standalone operating system distribution,
+@dfn{Guix@tie{}System} (@pxref{GNU Distribution}).
+
+@node Managing Software the Guix Way
+@section Managing Software the Guix Way
+
@cindex user interfaces
Guix provides a command-line package management interface
(@pxref{Invoking guix package}), a set of command-line utilities
@@ -348,17 +340,6 @@ is also @emph{customizable}: users can @emph{derive} specialized package
definitions from existing ones, including from the command line
(@pxref{Package Transformation Options}).
-@cindex Guix System Distribution
-@cindex GuixSD
-You can install GNU@tie{}Guix on top of an existing GNU/Linux system
-where it complements the available tools without interference
-(@pxref{Installation}), or you can use it as part of the standalone
-@dfn{Guix System Distribution} or GuixSD (@pxref{GNU Distribution}).
-With GNU@tie{}GuixSD, you @emph{declare} all aspects of the operating
-system configuration and Guix takes care of instantiating the
-configuration in a transactional, reproducible, and stateless fashion
-(@pxref{System Configuration}).
-
@cindex functional package management
@cindex isolation
Under the hood, Guix implements the @dfn{functional package management}
@@ -389,6 +370,81 @@ for transactional package upgrade and rollback, per-user installation, and
garbage collection of packages (@pxref{Features}).
+@node GNU Distribution
+@section GNU Distribution
+
+@cindex Guix System
+@cindex GuixSD
+Guix comes with a distribution of the GNU system consisting entirely of
+free software@footnote{The term ``free'' here refers to the
+@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
+users of that software}.}. The
+distribution can be installed on its own (@pxref{System Installation}),
+but it is also possible to install Guix as a package manager on top of
+an installed GNU/Linux system (@pxref{Installation}). When we need to
+distinguish between the two, we refer to the standalone distribution as
+Guix@tie{}System.
+
+The distribution provides core GNU packages such as GNU libc, GCC, and
+Binutils, as well as many GNU and non-GNU applications. The complete
+list of available packages can be browsed
+@url{http://www.gnu.org/software/guix/packages,on-line} or by
+running @command{guix package} (@pxref{Invoking guix package}):
+
+@example
+guix package --list-available
+@end example
+
+Our goal is to provide a practical 100% free software distribution of
+Linux-based and other variants of GNU, with a focus on the promotion and
+tight integration of GNU components, and an emphasis on programs and
+tools that help users exert that freedom.
+
+Packages are currently available on the following platforms:
+
+@table @code
+
+@item x86_64-linux
+Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;
+
+@item i686-linux
+Intel 32-bit architecture (IA32), Linux-Libre kernel;
+
+@item armhf-linux
+ARMv7-A architecture with hard float, Thumb-2 and NEON,
+using the EABI hard-float application binary interface (ABI),
+and Linux-Libre kernel.
+
+@item aarch64-linux
+little-endian 64-bit ARMv8-A processors, Linux-Libre kernel. This is
+currently in an experimental stage, with limited support.
+@xref{Contributing}, for how to help!
+
+@item mips64el-linux
+little-endian 64-bit MIPS processors, specifically the Loongson series,
+n32 ABI, and Linux-Libre kernel.
+
+@end table
+
+With Guix@tie{}System, you @emph{declare} all aspects of the operating system
+configuration and Guix takes care of instantiating the configuration in a
+transactional, reproducible, and stateless fashion (@pxref{System
+Configuration}). Guix System uses the Linux-libre kernel, the Shepherd
+initialization system (@pxref{Introduction,,, shepherd, The GNU Shepherd
+Manual}), the well-known GNU utilities and tool chain, as well as the
+graphical environment or system services of your choice.
+
+Guix System is available on all the above platforms except
+@code{mips64el-linux}.
+
+@noindent
+For information on porting to other architectures or kernels,
+@pxref{Porting}.
+
+Building this distribution is a cooperative effort, and you are invited
+to join! @xref{Contributing}, for information about how you can help.
+
+
@c *********************************************************************
@node Installation
@chapter Installation
@@ -9034,86 +9090,9 @@ ClientPID: 19419
ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
@end example
-@c *********************************************************************
-@node GNU Distribution
-@chapter GNU Distribution
-
-@cindex Guix System Distribution
-@cindex GuixSD
-Guix comes with a distribution of the GNU system consisting entirely of
-free software@footnote{The term ``free'' here refers to the
-@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
-users of that software}.}. The
-distribution can be installed on its own (@pxref{System Installation}),
-but it is also possible to install Guix as a package manager on top of
-an installed GNU/Linux system (@pxref{Installation}). To distinguish
-between the two, we refer to the standalone distribution as the Guix
-System Distribution, or GuixSD.
-
-The distribution provides core GNU packages such as GNU libc, GCC, and
-Binutils, as well as many GNU and non-GNU applications. The complete
-list of available packages can be browsed
-@url{http://www.gnu.org/software/guix/packages,on-line} or by
-running @command{guix package} (@pxref{Invoking guix package}):
-
-@example
-guix package --list-available
-@end example
-
-Our goal is to provide a practical 100% free software distribution of
-Linux-based and other variants of GNU, with a focus on the promotion and
-tight integration of GNU components, and an emphasis on programs and
-tools that help users exert that freedom.
-
-Packages are currently available on the following platforms:
-
-@table @code
-
-@item x86_64-linux
-Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;
-
-@item i686-linux
-Intel 32-bit architecture (IA32), Linux-Libre kernel;
-
-@item armhf-linux
-ARMv7-A architecture with hard float, Thumb-2 and NEON,
-using the EABI hard-float application binary interface (ABI),
-and Linux-Libre kernel.
-
-@item aarch64-linux
-little-endian 64-bit ARMv8-A processors, Linux-Libre kernel. This is
-currently in an experimental stage, with limited support.
-@xref{Contributing}, for how to help!
-
-@item mips64el-linux
-little-endian 64-bit MIPS processors, specifically the Loongson series,
-n32 ABI, and Linux-Libre kernel.
-
-@end table
-
-GuixSD itself is currently only available on @code{i686} and @code{x86_64}.
-
-@noindent
-For information on porting to other architectures or kernels,
-@pxref{Porting}.
-
-@menu
-* System Installation:: Installing the whole operating system.
-* System Configuration:: Configuring the operating system.
-* Documentation:: Browsing software user manuals.
-* Installing Debugging Files:: Feeding the debugger.
-* Security Updates:: Deploying security fixes quickly.
-* Package Modules:: Packages from the programmer's viewpoint.
-* Packaging Guidelines:: Growing the distribution.
-* Bootstrapping:: GNU/Linux built from scratch.
-* Porting:: Targeting another platform or kernel.
-@end menu
-
-Building this distribution is a cooperative effort, and you are invited
-to join! @xref{Contributing}, for information about how you can help.
@node System Installation
-@section System Installation
+@chapter System Installation
@cindex installing GuixSD
@cindex Guix System Distribution
@@ -9147,7 +9126,7 @@ available.
@end menu
@node Limitations
-@subsection Limitations
+@section Limitations
As of version @value{VERSION}, the Guix System Distribution (GuixSD) is
not production-ready. It may contain bugs and lack important
@@ -9191,7 +9170,7 @@ to report issues (and success stories!), and to join us in improving it.
@node Hardware Considerations
-@subsection Hardware Considerations
+@section Hardware Considerations
@cindex hardware support on GuixSD
GNU@tie{}GuixSD focuses on respecting the user's computing freedom. It
@@ -9226,7 +9205,7 @@ about their support in GNU/Linux.
@node USB Stick and DVD Installation
-@subsection USB Stick and DVD Installation
+@section USB Stick and DVD Installation
An ISO-9660 installation image that can be written to a USB stick or
burnt to a DVD can be downloaded from
@@ -9265,7 +9244,7 @@ and rerun the @code{gpg --verify} command.
This image contains the tools necessary for an installation.
It is meant to be copied @emph{as is} to a large-enough USB stick or DVD.
-@unnumberedsubsubsec Copying to a USB Stick
+@unnumberedsubsec Copying to a USB Stick
To copy the image to a USB stick, follow these steps:
@@ -9290,7 +9269,7 @@ sync
Access to @file{/dev/sdX} usually requires root privileges.
@end enumerate
-@unnumberedsubsubsec Burning on a DVD
+@unnumberedsubsec Burning on a DVD
To copy the image to a DVD, follow these steps:
@@ -9314,7 +9293,7 @@ growisofs -dvd-compat -Z /dev/srX=guixsd-install-@value{VERSION}.@var{system}.is
Access to @file{/dev/srX} usually requires root privileges.
@end enumerate
-@unnumberedsubsubsec Booting
+@unnumberedsubsec Booting
Once this is done, you should be able to reboot the system and boot from
the USB stick or DVD. The latter usually requires you to get in the
@@ -9325,7 +9304,7 @@ GuixSD in a virtual machine (VM).
@node Preparing for Installation
-@subsection Preparing for Installation
+@section Preparing for Installation
Once you have successfully booted your computer using the installation medium,
you should end up with the welcome page of the graphical installer. The
@@ -9354,7 +9333,7 @@ But it is also a full-blown GuixSD system, which means that you can
install additional packages, should you need it, using @command{guix
package} (@pxref{Invoking guix package}).
-@subsubsection Keyboard Layout
+@subsection Keyboard Layout
@cindex keyboard layout
The installation image uses the US qwerty keyboard layout. If you want
@@ -9369,7 +9348,7 @@ See the files under @file{/run/current-system/profile/share/keymaps} for
a list of available keyboard layouts. Run @command{man loadkeys} for
more information.
-@subsubsection Networking
+@subsection Networking
Run the following command to see what your network interfaces are called:
@@ -9462,7 +9441,7 @@ herd start ssh-daemon
Make sure to either set a password with @command{passwd}, or configure
OpenSSH public key authentication before logging in.
-@subsubsection Disk Partitioning
+@subsection Disk Partitioning
Unless this has already been done, the next step is to partition, and
then format the target partition(s).
@@ -9583,7 +9562,7 @@ file in its file system as described above, then the encryption also
protects the swap file, just like any other file in that file system.
@node Proceeding with the Installation
-@subsection Proceeding with the Installation
+@section Proceeding with the Installation
With the target partitions ready and the target root mounted on
@file{/mnt}, we're ready to go. First, run:
@@ -9680,7 +9659,7 @@ Join us on @code{#guix} on the Freenode IRC network or on
good.
@node Installing GuixSD in a VM
-@subsection Installing GuixSD in a Virtual Machine
+@section Installing GuixSD in a Virtual Machine
@cindex virtual machine, GuixSD installation
@cindex virtual private server (VPS)
@@ -9734,7 +9713,7 @@ Once installation is complete, you can boot the system that's on your
that.
@node Building the Installation Image
-@subsection Building the Installation Image
+@section Building the Installation Image
@cindex installation image
The installation image described above was built using the @command{guix
@@ -9748,7 +9727,7 @@ Have a look at @file{gnu/system/install.scm} in the source tree,
and see also @ref{Invoking guix system} for more information
about the installation image.
-@subsection Building the Installation Image for ARM Boards
+@section Building the Installation Image for ARM Boards
Many ARM boards require a specific variant of the
@uref{http://www.denx.de/wiki/U-Boot/, U-Boot} bootloader.
@@ -9765,7 +9744,7 @@ guix system disk-image --system=armhf-linux -e '((@@ (gnu system install) os-wit
board, a list of possible boards will be printed.
@node System Configuration
-@section System Configuration
+@chapter System Configuration
@cindex system configuration
The Guix System Distribution supports a consistent whole-system configuration
@@ -9808,7 +9787,7 @@ instance to support new system services.
@end menu
@node Using the Configuration System
-@subsection Using the Configuration System
+@section Using the Configuration System
The operating system is configured by providing an
@code{operating-system} declaration in a file that can then be passed to
@@ -9831,7 +9810,7 @@ Below we discuss the effect of some of the most important fields
fields), and how to @dfn{instantiate} the operating system using
@command{guix system}.
-@unnumberedsubsubsec Bootloader
+@unnumberedsubsec Bootloader
@cindex legacy boot, on Intel machines
@cindex BIOS boot, on Intel machines
@@ -9852,7 +9831,7 @@ the @code{bootloader} field should contain something along these lines:
@xref{Bootloader Configuration}, for more information on the available
configuration options.
-@unnumberedsubsubsec Globally-Visible Packages
+@unnumberedsubsec Globally-Visible Packages
@vindex %base-packages
The @code{packages} field lists packages that will be globally visible
@@ -9898,7 +9877,7 @@ version:
%base-packages)))
@end lisp
-@unnumberedsubsubsec System Services
+@unnumberedsubsec System Services
@cindex services
@vindex %base-services
@@ -9990,7 +9969,7 @@ following expression returns a list that contains all the services in
%desktop-services)
@end example
-@unnumberedsubsubsec Instantiating the System
+@unnumberedsubsec Instantiating the System
Assuming the @code{operating-system} declaration
is stored in the @file{my-system-config.scm}
@@ -10023,7 +10002,7 @@ the latest (e.g., after invoking @command{guix system roll-back}), since
the operation might overwrite a later generation (@pxref{Invoking guix
system}).
-@unnumberedsubsubsec The Programming Interface
+@unnumberedsubsec The Programming Interface
At the Scheme level, the bulk of an @code{operating-system} declaration
is instantiated with the following monadic procedure (@pxref{The Store
@@ -10044,7 +10023,7 @@ guts of GuixSD. Make sure to visit it!
@node operating-system Reference
-@subsection @code{operating-system} Reference
+@section @code{operating-system} Reference
This section summarizes all the options available in
@code{operating-system} declarations (@pxref{Using the Configuration
@@ -10198,7 +10177,7 @@ is that only @code{root} and members of the @code{wheel} group may use
@end deftp
@node File Systems
-@subsection File Systems
+@section File Systems
The list of file systems to be mounted is specified in the
@code{file-systems} field of the operating system declaration
@@ -10363,7 +10342,7 @@ and unmount user-space FUSE file systems. This requires the
@end defvr
@node Mapped Devices
-@subsection Mapped Devices
+@section Mapped Devices
@cindex device mapping
@cindex mapped devices
@@ -10484,7 +10463,7 @@ automatically later.
@node User Accounts
-@subsection User Accounts
+@section User Accounts
@cindex users
@cindex accounts
@@ -10619,7 +10598,7 @@ special-case and is automatically added whether or not it is specified.
@end defvr
@node Locales
-@subsection Locales
+@section Locales
@cindex locale
A @dfn{lo
This message was truncated. Download the full message here.
L
L
Ludovic Courtès wrote on 21 Jan 2019 12:02
[PATCH 2/4] doc: Move "System Installation" right after "Installation".
(address . 34156@debbugs.gnu.org)(name . Ludovic Courtès)(address . ludo@gnu.org)
20190121110238.15225-2-ludo@gnu.org
* doc/guix.texi (System Installation): Move right after "Installation".
---
doc/guix.texi | 1327 +++++++++++++++++++++++++------------------------
1 file changed, 664 insertions(+), 663 deletions(-)

Toggle diff (543 lines)
diff --git a/doc/guix.texi b/doc/guix.texi
index 0fa4ec27a6..42c7f4eeb1 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -117,10 +117,10 @@ Project}.
@menu
* Introduction:: What is Guix about?
* Installation:: Installing Guix.
+* System Installation:: Installing the whole operating system.
* Package Management:: Package installation, upgrade, etc.
* Programming Interface:: Using Guix in Scheme.
* Utilities:: Package management commands.
-* System Installation:: Installing the whole operating system.
* System Configuration:: Configuring the operating system.
* Documentation:: Browsing software user manuals.
* Installing Debugging Files:: Feeding the debugger.
@@ -154,6 +154,16 @@ Setting Up the Daemon
* Daemon Offload Setup:: Offloading builds to remote machines.
* SELinux Support:: Using an SELinux policy for the daemon.
+System Installation
+
+* Limitations:: What you can expect.
+* Hardware Considerations:: Supported hardware.
+* USB Stick and DVD Installation:: Preparing the installation medium.
+* Preparing for Installation:: Networking, partitioning, etc.
+* Proceeding with the Installation:: The real thing.
+* Installing GuixSD in a VM:: GuixSD playground.
+* Building the Installation Image:: How this comes to be.
+
Package Management
* Features:: How Guix will make your life brighter.
@@ -218,16 +228,6 @@ Invoking @command{guix build}
* Additional Build Options:: Options specific to 'guix build'.
* Debugging Build Failures:: Real life packaging experience.
-System Installation
-
-* Limitations:: What you can expect.
-* Hardware Considerations:: Supported hardware.
-* USB Stick and DVD Installation:: Preparing the installation medium.
-* Preparing for Installation:: Networking, partitioning, etc.
-* Proceeding with the Installation:: The real thing.
-* Installing GuixSD in a VM:: GuixSD playground.
-* Building the Installation Image:: How this comes to be.
-
System Configuration
* Using the Configuration System:: Customizing your GNU system.
@@ -1744,6 +1744,659 @@ store you need to define the environment variable
@c TODO What else?
+@c *********************************************************************
+@node System Installation
+@chapter System Installation
+
+@cindex installing GuixSD
+@cindex Guix System Distribution
+This section explains how to install the Guix System Distribution (GuixSD)
+on a machine. The Guix package manager can
+also be installed on top of a running GNU/Linux system,
+@pxref{Installation}.
+
+@ifinfo
+@quotation Note
+@c This paragraph is for people reading this from tty2 of the
+@c installation image.
+You are reading this documentation with an Info reader. For details on
+how to use it, hit the @key{RET} key (``return'' or ``enter'') on the
+link that follows: @pxref{Top, Info reader,, info-stnd, Stand-alone GNU
+Info}. Hit @kbd{l} afterwards to come back here.
+
+Alternately, run @command{info info} in another tty to keep the manual
+available.
+@end quotation
+@end ifinfo
+
+@menu
+* Limitations:: What you can expect.
+* Hardware Considerations:: Supported hardware.
+* USB Stick and DVD Installation:: Preparing the installation medium.
+* Preparing for Installation:: Networking, partitioning, etc.
+* Proceeding with the Installation:: The real thing.
+* Installing GuixSD in a VM:: GuixSD playground.
+* Building the Installation Image:: How this comes to be.
+@end menu
+
+@node Limitations
+@section Limitations
+
+As of version @value{VERSION}, the Guix System Distribution (GuixSD) is
+not production-ready. It may contain bugs and lack important
+features. Thus, if you are looking for a stable production system that
+respects your freedom as a computer user, a good solution at this point
+is to consider @url{http://www.gnu.org/distros/free-distros.html, one of
+the more established GNU/Linux distributions}. We hope you can soon switch
+to the GuixSD without fear, of course. In the meantime, you can
+also keep using your distribution and try out the package manager on top
+of it (@pxref{Installation}).
+
+Before you proceed with the installation, be aware of the following
+noteworthy limitations applicable to version @value{VERSION}:
+
+@itemize
+@item
+The installation process does not include a graphical user interface and
+requires familiarity with GNU/Linux (see the following subsections to
+get a feel of what that means.)
+
+@item
+Support for the Logical Volume Manager (LVM) is missing.
+
+@item
+More and more system services are provided (@pxref{Services}), but some
+may be missing.
+
+@item
+More than 8,500 packages are available, but you might
+occasionally find that a useful package is missing.
+
+@item
+GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}),
+as well as a number of X11 window managers. However, some graphical
+applications may be missing, as well as KDE.
+@end itemize
+
+You have been warned! But more than a disclaimer, this is an invitation
+to report issues (and success stories!), and to join us in improving it.
+@xref{Contributing}, for more info.
+
+
+@node Hardware Considerations
+@section Hardware Considerations
+
+@cindex hardware support on GuixSD
+GNU@tie{}GuixSD focuses on respecting the user's computing freedom. It
+builds around the kernel Linux-libre, which means that only hardware for
+which free software drivers and firmware exist is supported. Nowadays,
+a wide range of off-the-shelf hardware is supported on
+GNU/Linux-libre---from keyboards to graphics cards to scanners and
+Ethernet controllers. Unfortunately, there are still areas where
+hardware vendors deny users control over their own computing, and such
+hardware is not supported on GuixSD.
+
+@cindex WiFi, hardware support
+One of the main areas where free drivers or firmware are lacking is WiFi
+devices. WiFi devices known to work include those using Atheros chips
+(AR9271 and AR7010), which corresponds to the @code{ath9k} Linux-libre
+driver, and those using Broadcom/AirForce chips (BCM43xx with
+Wireless-Core Revision 5), which corresponds to the @code{b43-open}
+Linux-libre driver. Free firmware exists for both and is available
+out-of-the-box on GuixSD, as part of @var{%base-firmware}
+(@pxref{operating-system Reference, @code{firmware}}).
+
+@cindex RYF, Respects Your Freedom
+The @uref{https://www.fsf.org/, Free Software Foundation} runs
+@uref{https://www.fsf.org/ryf, @dfn{Respects Your Freedom}} (RYF), a
+certification program for hardware products that respect your freedom
+and your privacy and ensure that you have control over your device. We
+encourage you to check the list of RYF-certified devices.
+
+Another useful resource is the @uref{https://www.h-node.org/, H-Node}
+web site. It contains a catalog of hardware devices with information
+about their support in GNU/Linux.
+
+
+@node USB Stick and DVD Installation
+@section USB Stick and DVD Installation
+
+An ISO-9660 installation image that can be written to a USB stick or
+burnt to a DVD can be downloaded from
+@indicateurl{https://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.iso.xz},
+where @var{system} is one of:
+
+@table @code
+@item x86_64-linux
+for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;
+
+@item i686-linux
+for a 32-bit GNU/Linux system on Intel-compatible CPUs.
+@end table
+
+@c start duplication of authentication part from ``Binary Installation''
+Make sure to download the associated @file{.sig} file and to verify the
+authenticity of the image against it, along these lines:
+
+@example
+$ wget https://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.iso.xz.sig
+$ gpg --verify guixsd-install-@value{VERSION}.@var{system}.iso.xz.sig
+@end example
+
+If that command fails because you do not have the required public key,
+then run this command to import it:
+
+@example
+$ gpg --keyserver @value{KEY-SERVER} \
+ --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
+@end example
+
+@noindent
+and rerun the @code{gpg --verify} command.
+@c end duplication
+
+This image contains the tools necessary for an installation.
+It is meant to be copied @emph{as is} to a large-enough USB stick or DVD.
+
+@unnumberedsubsec Copying to a USB Stick
+
+To copy the image to a USB stick, follow these steps:
+
+@enumerate
+@item
+Decompress the image using the @command{xz} command:
+
+@example
+xz -d guixsd-install-@value{VERSION}.@var{system}.iso.xz
+@end example
+
+@item
+Insert a USB stick of 1@tie{}GiB or more into your machine, and determine
+its device name. Assuming that the USB stick is known as @file{/dev/sdX},
+copy the image with:
+
+@example
+dd if=guixsd-install-@value{VERSION}.@var{system}.iso of=/dev/sdX
+sync
+@end example
+
+Access to @file{/dev/sdX} usually requires root privileges.
+@end enumerate
+
+@unnumberedsubsec Burning on a DVD
+
+To copy the image to a DVD, follow these steps:
+
+@enumerate
+@item
+Decompress the image using the @command{xz} command:
+
+@example
+xz -d guixsd-install-@value{VERSION}.@var{system}.iso.xz
+@end example
+
+@item
+Insert a blank DVD into your machine, and determine
+its device name. Assuming that the DVD drive is known as @file{/dev/srX},
+copy the image with:
+
+@example
+growisofs -dvd-compat -Z /dev/srX=guixsd-install-@value{VERSION}.@var{system}.iso
+@end example
+
+Access to @file{/dev/srX} usually requires root privileges.
+@end enumerate
+
+@unnumberedsubsec Booting
+
+Once this is done, you should be able to reboot the system and boot from
+the USB stick or DVD. The latter usually requires you to get in the
+BIOS or UEFI boot menu, where you can choose to boot from the USB stick.
+
+@xref{Installing GuixSD in a VM}, if, instead, you would like to install
+GuixSD in a virtual machine (VM).
+
+
+@node Preparing for Installation
+@section Preparing for Installation
+
+Once you have successfully booted your computer using the installation medium,
+you should end up with the welcome page of the graphical installer. The
+graphical installer is a text-based user interface built upon the newt
+library. It shall guide you through all the different steps needed to install
+GNU GuixSD. However, as the graphical installer is still under heavy
+development, you might want to fallback to the original, shell based install
+process, by switching to TTYs 3 to 6 with the shortcuts CTRL-ALT-F[3-6]. The
+following sections describe the installation procedure assuming you're using
+one of those TTYs. They are configured and can be used to run commands as
+root.
+
+TTY2 shows this documentation, browsable using the Info reader commands
+(@pxref{Top,,, info-stnd, Stand-alone GNU Info}). The installation system
+runs the GPM mouse daemon, which allows you to select text with the left mouse
+button and to paste it with the middle button.
+
+@quotation Note
+Installation requires access to the Internet so that any missing
+dependencies of your system configuration can be downloaded. See the
+``Networking'' section below.
+@end quotation
+
+The installation system includes many common tools needed for this task.
+But it is also a full-blown GuixSD system, which means that you can
+install additional packages, should you need it, using @command{guix
+package} (@pxref{Invoking guix package}).
+
+@subsection Keyboard Layout
+
+@cindex keyboard layout
+The installation image uses the US qwerty keyboard layout. If you want
+to change it, you can use the @command{loadkeys} command. For example,
+the following command selects the Dvorak keyboard layout:
+
+@example
+loadkeys dvorak
+@end example
+
+See the files under @file{/run/current-system/profile/share/keymaps} for
+a list of available keyboard layouts. Run @command{man loadkeys} for
+more information.
+
+@subsection Networking
+
+Run the following command to see what your network interfaces are called:
+
+@example
+ifconfig -a
+@end example
+
+@noindent
+@dots{} or, using the GNU/Linux-specific @command{ip} command:
+
+@example
+ip a
+@end example
+
+@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
+Wired interfaces have a name starting with @samp{e}; for example, the
+interface corresponding to the first on-board Ethernet controller is
+called @samp{eno1}. Wireless interfaces have a name starting with
+@samp{w}, like @samp{w1p2s0}.
+
+@table @asis
+@item Wired connection
+To configure a wired network run the following command, substituting
+@var{interface} with the name of the wired interface you want to use.
+
+@example
+ifconfig @var{interface} up
+@end example
+
+@item Wireless connection
+@cindex wireless
+@cindex WiFi
+To configure wireless networking, you can create a configuration file
+for the @command{wpa_supplicant} configuration tool (its location is not
+important) using one of the available text editors such as
+@command{nano}:
+
+@example
+nano wpa_supplicant.conf
+@end example
+
+As an example, the following stanza can go to this file and will work
+for many wireless networks, provided you give the actual SSID and
+passphrase for the network you are connecting to:
+
+@example
+network=@{
+ ssid="@var{my-ssid}"
+ key_mgmt=WPA-PSK
+ psk="the network's secret passphrase"
+@}
+@end example
+
+Start the wireless service and run it in the background with the
+following command (substitute @var{interface} with the name of the
+network interface you want to use):
+
+@example
+wpa_supplicant -c wpa_supplicant.conf -i @var{interface} -B
+@end example
+
+Run @command{man wpa_supplicant} for more information.
+@end table
+
+@cindex DHCP
+At this point, you need to acquire an IP address. On a network where IP
+addresses are automatically assigned @i{via} DHCP, you can run:
+
+@example
+dhclient -v @var{interface}
+@end example
+
+Try to ping a server to see if networking is up and running:
+
+@example
+ping -c 3 gnu.org
+@end example
+
+Setting up network access is almost always a requirement because the
+image does not contain all the software and tools that may be needed.
+
+@cindex installing over SSH
+If you want to, you can continue the installation remotely by starting
+an SSH server:
+
+@example
+herd start ssh-daemon
+@end example
+
+Make sure to either set a password with @command{passwd}, or configure
+OpenSSH public key authentication before logging in.
+
+@subsection Disk Partitioning
+
+Unless this has already been done, the next step is to partition, and
+then format the target partition(s).
+
+The installation image includes several partitioning tools, including
+Parted (@pxref{Overview,,, parted, GNU Parted User Manual}),
+@command{fdisk}, and @command{cfdisk}. Run it and set up your disk with
+the partition layout you want:
+
+@example
+cfdisk
+@end example
+
+If your disk uses the GUID Partition Table (GPT) format and you plan to
+install BIOS-based GRUB (which is the default), make sure a BIOS Boot
+Partition is available (@pxref{BIOS installation,,, grub, GNU GRUB
+manual}).
+
+@cindex EFI, installation
+@cindex UEFI, installation
+@cindex ESP, EFI system partition
+If you instead wish to use EFI-based GRUB, a FAT32 @dfn{EFI System Partition}
+(ESP) is required. This partition should be mounted at @file{/boot/efi} and
+must have the @code{esp} flag set. E.g., for @command{parted}:
+
+@example
+parted /dev/sda set 1 esp on
+@end example
+
+@quotation Note
+@vindex grub-bootloader
+@vindex grub-efi-bootloader
+Unsure whether to use EFI- or BIOS-based GRUB? If the directory
+@file{/sys/firmware/efi} exists in the installation image, then you should
+probably perform an EFI installation, using @code{grub-efi-bootloader}.
+Otherwise you should use the BIOS-based GRUB, known as
+@code{grub-bootloader}. @xref{Bootloader Configuration}, for more info on
+bootloaders.
+@end quotation
+
+Once you are done partitioning the target hard disk drive, you have to
+create a file system on the relevant partition(s)@footnote{Currently
+GuixSD only supports ext4 and btrfs file systems. In particular, code
+that reads file system UUIDs and labels only works for these file system
+types.}. For the ESP, if you have one and assuming it is
+@file{/dev/sda1}, run:
+
+@example
+mkfs.fat -F32 /dev/sda1
+@end example
+
+Preferably, assign file systems a label so that you can easily and
+reliably refer to them in @code{file-system} declarations (@pxref{File
+Systems}). This is typically done using the @code{-L} option of
+@command{mkfs.ext4} and related commands. So, assuming the target root
+partition lives at @file{/dev/sda2}, a file system with the label
+@code{my-root} can be created with:
+
+@example
+mkfs.ext4 -L my-root /dev/sda2
+@end example
+
+@cindex encrypted disk
+If you are instead planning to encrypt the root partition, you can use
+the Cryptsetup/LUKS utilities to do that (see @inlinefmtifelse{html,
+@uref{https://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}},
+@code{man cryptsetup}} for more information.) Assuming you want to
+store the root partition on @file{/dev/sda2}, the command sequence would
+be along these lines:
+
+@example
+cryptsetup luksFormat /dev/sda2
+cryptsetup open --type luks /dev/sda2 my-partition
+mkfs.ext4 -L my-root /dev/mapper/my-partition
+@end example
+
+Once that is done, mount the target file system under @file{/mnt}
+with a command like (again, assuming @code{my-root} is the label of the
+root file system):
+
+@example
+mount LABEL=my-root /mnt
+@end example
+
+Also mount any other file systems you would like to use on the target
+system relative to this path. If you have @file{/boot} on a separate
+partition for example, mount it at @file{/mnt/boot} now so it is found
+by @code{guix system init} afterwards.
+
+Finally, if you plan to use one or more swap partitions (@pxref{Memory
+Concepts, swap space,, libc, The GNU C Library Reference Manual}), make
+sure to initialize them with @command{mkswap}. Assuming you have one
+swap partition on @file{/dev/sda3}, you would run:
+
+@example
+mkswap /dev/sda3
+swapon /dev/sda3
+@end example
+
+Alternatively, you may use a swap file. For example, assuming that in
+the new system you want to use the file @file{/swapfile} as a swap file,
+you would run@footnote{This example will work for many types of file
+systems (e.g., ext4). However, for copy-on-write file systems (e.g.,
+btrfs), the required steps may be different. For details, see the
+manual pages for @command{mkswap} and @command{swapon}.}:
+
+@example
+# This is 10 GiB of swap space. Adjust "count" to change the size.
+dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240
+# For security, make the file readable and writable only by root.
+chmod 600 /mnt/swapfile
+mkswap /mnt/swapfile
+swapon /mnt/swapfile
+@end example
+
+Note that if you have encrypted the root partition and created a swap
+file in its file system as described above, then the encryption also
+protects the swap file, just like any other file in that file system.
+
+@node Proceeding with the Installation
+@section Proceeding with the Installation
+
+With the target partitions ready and the target root mounted on
+@file{/mnt}, we're ready to go. First, run:
+
+@example
+herd start cow-store /mnt
+@end example
+
+This makes @file{/gnu/store} copy-on-write, such that packages added to it
+during the installation phase are written to the target disk on @file{/mnt}
+rather than kept in memory. This is necessary because the first phase of
+the @command{guix system init} command (see below) entails downloads or
+builds to @file{/gnu/store} which, initially, is an in-memory file system.
+
+Next, you have to edit a file and
+provide
This message was truncated. Download the full message here.
L
L
Ludovic Courtès wrote on 21 Jan 2019 12:02
[PATCH 4/4] doc: Move "Package Modules" under "Programming Interface".
(address . 34156@debbugs.gnu.org)(name . Ludovic Courtès)(address . ludo@gnu.org)
20190121110238.15225-4-ludo@gnu.org
* doc/guix.texi (Package Modules): Move to...
(Programming Interface): ... here. Turn into a section.
---
doc/guix.texi | 128 +++++++++++++++++++++++++-------------------------
1 file changed, 64 insertions(+), 64 deletions(-)

Toggle diff (169 lines)
diff --git a/doc/guix.texi b/doc/guix.texi
index add06ec8af..251fd9b8ec 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -125,7 +125,6 @@ Project}.
* Documentation:: Browsing software user manuals.
* Installing Debugging Files:: Feeding the debugger.
* Security Updates:: Deploying security fixes quickly.
-* Package Modules:: Packages from the programmer's viewpoint.
* Bootstrapping:: GNU/Linux built from scratch.
* Porting:: Targeting another platform or kernel.
* Contributing:: Your help needed!
@@ -188,6 +187,7 @@ Substitutes
Programming Interface
+* Package Modules:: Packages from the programmer's viewpoint.
* Defining Packages:: Defining new packages.
* Build Systems:: Specifying how packages are built.
* The Store:: Manipulating the package store.
@@ -4437,6 +4437,7 @@ This chapter describes all these APIs in turn, starting from high-level
package definitions.
@menu
+* Package Modules:: Packages from the programmer's viewpoint.
* Defining Packages:: Defining new packages.
* Build Systems:: Specifying how packages are built.
* The Store:: Manipulating the package store.
@@ -4446,6 +4447,68 @@ package definitions.
* Invoking guix repl:: Fiddling with Guix interactively.
@end menu
+@node Package Modules
+@section Package Modules
+
+From a programming viewpoint, the package definitions of the
+GNU distribution are provided by Guile modules in the @code{(gnu packages
+@dots{})} name space@footnote{Note that packages under the @code{(gnu
+packages @dots{})} module name space are not necessarily ``GNU
+packages''. This module naming scheme follows the usual Guile module
+naming convention: @code{gnu} means that these modules are distributed
+as part of the GNU system, and @code{packages} identifies modules that
+define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile
+Reference Manual}). For instance, the @code{(gnu packages emacs)}
+module exports a variable named @code{emacs}, which is bound to a
+@code{<package>} object (@pxref{Defining Packages}).
+
+The @code{(gnu packages @dots{})} module name space is
+automatically scanned for packages by the command-line tools. For
+instance, when running @code{guix package -i emacs}, all the @code{(gnu
+packages @dots{})} modules are scanned until one that exports a package
+object whose name is @code{emacs} is found. This package search
+facility is implemented in the @code{(gnu packages)} module.
+
+@cindex customization, of packages
+@cindex package module search path
+Users can store package definitions in modules with different
+names---e.g., @code{(my-packages emacs)}@footnote{Note that the file
+name and module name must match. For instance, the @code{(my-packages
+emacs)} module must be stored in a @file{my-packages/emacs.scm} file
+relative to the load path specified with @option{--load-path} or
+@code{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,,
+guile, GNU Guile Reference Manual}, for details.}. There are two ways to make
+these package definitions visible to the user interfaces:
+
+@enumerate
+@item
+By adding the directory containing your package modules to the search path
+with the @code{-L} flag of @command{guix package} and other commands
+(@pxref{Common Build Options}), or by setting the @code{GUIX_PACKAGE_PATH}
+environment variable described below.
+
+@item
+By defining a @dfn{channel} and configuring @command{guix pull} so that it
+pulls from it. A channel is essentially a Git repository containing package
+modules. @xref{Channels}, for more information on how to define and use
+channels.
+@end enumerate
+
+@code{GUIX_PACKAGE_PATH} works similarly to other search path variables:
+
+@defvr {Environment Variable} GUIX_PACKAGE_PATH
+This is a colon-separated list of directories to search for additional
+package modules. Directories listed in this variable take precedence
+over the own modules of the distribution.
+@end defvr
+
+The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
+each package is built based solely on other packages in the
+distribution. The root of this dependency graph is a small set of
+@dfn{bootstrap binaries}, provided by the @code{(gnu packages
+bootstrap)} module. For more information on bootstrapping,
+@pxref{Bootstrapping}.
+
@node Defining Packages
@section Defining Packages
@@ -24106,69 +24169,6 @@ lsof | grep /gnu/store/.*bash
@end example
-@node Package Modules
-@chapter Package Modules
-
-From a programming viewpoint, the package definitions of the
-GNU distribution are provided by Guile modules in the @code{(gnu packages
-@dots{})} name space@footnote{Note that packages under the @code{(gnu
-packages @dots{})} module name space are not necessarily ``GNU
-packages''. This module naming scheme follows the usual Guile module
-naming convention: @code{gnu} means that these modules are distributed
-as part of the GNU system, and @code{packages} identifies modules that
-define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile
-Reference Manual}). For instance, the @code{(gnu packages emacs)}
-module exports a variable named @code{emacs}, which is bound to a
-@code{<package>} object (@pxref{Defining Packages}).
-
-The @code{(gnu packages @dots{})} module name space is
-automatically scanned for packages by the command-line tools. For
-instance, when running @code{guix package -i emacs}, all the @code{(gnu
-packages @dots{})} modules are scanned until one that exports a package
-object whose name is @code{emacs} is found. This package search
-facility is implemented in the @code{(gnu packages)} module.
-
-@cindex customization, of packages
-@cindex package module search path
-Users can store package definitions in modules with different
-names---e.g., @code{(my-packages emacs)}@footnote{Note that the file
-name and module name must match. For instance, the @code{(my-packages
-emacs)} module must be stored in a @file{my-packages/emacs.scm} file
-relative to the load path specified with @option{--load-path} or
-@code{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,,
-guile, GNU Guile Reference Manual}, for details.}. There are two ways to make
-these package definitions visible to the user interfaces:
-
-@enumerate
-@item
-By adding the directory containing your package modules to the search path
-with the @code{-L} flag of @command{guix package} and other commands
-(@pxref{Common Build Options}), or by setting the @code{GUIX_PACKAGE_PATH}
-environment variable described below.
-
-@item
-By defining a @dfn{channel} and configuring @command{guix pull} so that it
-pulls from it. A channel is essentially a Git repository containing package
-modules. @xref{Channels}, for more information on how to define and use
-channels.
-@end enumerate
-
-@code{GUIX_PACKAGE_PATH} works similarly to other search path variables:
-
-@defvr {Environment Variable} GUIX_PACKAGE_PATH
-This is a colon-separated list of directories to search for additional
-package modules. Directories listed in this variable take precedence
-over the own modules of the distribution.
-@end defvr
-
-The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
-each package is built based solely on other packages in the
-distribution. The root of this dependency graph is a small set of
-@dfn{bootstrap binaries}, provided by the @code{(gnu packages
-bootstrap)} module. For more information on bootstrapping,
-@pxref{Bootstrapping}.
-
-
@node Bootstrapping
@chapter Bootstrapping
--
2.20.1
L
L
Ludovic Courtès wrote on 21 Jan 2019 12:02
[PATCH 3/4] doc: Move "Packaging Guidelines" under "Contributing".
(address . 34156@debbugs.gnu.org)(name . Ludovic Courtès)(address . ludo@gnu.org)
20190121110238.15225-3-ludo@gnu.org
* doc/guix.texi (Packaging Guidelines): Move to...
* doc/contributing.texi (Packaging Guidelines): ... here. Turn into a
section. Adjust references to "Contributing".
---
doc/contributing.texi | 450 ++++++++++++++++++++++++++++++++++++++++
doc/guix.texi | 462 ------------------------------------------
2 files changed, 450 insertions(+), 462 deletions(-)

Toggle diff (455 lines)
diff --git a/doc/contributing.texi b/doc/contributing.texi
index f24886233d..ecc20dabc5 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -23,6 +23,7 @@ choice.
* Building from Git:: The latest and greatest.
* Running Guix Before It Is Installed:: Hacker tricks.
* The Perfect Setup:: The right tools.
+* Packaging Guidelines:: Growing the distribution.
* Coding Style:: Hygiene of the contributor.
* Submitting Patches:: Share your work.
@end menu
@@ -223,6 +224,455 @@ trigger string @code{origin...}, which can be expanded further. The
@code{...}, which also can be expanded further.
+@node Packaging Guidelines
+@section Packaging Guidelines
+
+@cindex packages, creating
+The GNU distribution is nascent and may well lack some of your favorite
+packages. This section describes how you can help make the distribution
+grow.
+
+Free software packages are usually distributed in the form of
+@dfn{source code tarballs}---typically @file{tar.gz} files that contain
+all the source files. Adding a package to the distribution means
+essentially two things: adding a @dfn{recipe} that describes how to
+build the package, including a list of other packages required to build
+it, and adding @dfn{package metadata} along with that recipe, such as a
+description and licensing information.
+
+In Guix all this information is embodied in @dfn{package definitions}.
+Package definitions provide a high-level view of the package. They are
+written using the syntax of the Scheme programming language; in fact,
+for each package we define a variable bound to the package definition,
+and export that variable from a module (@pxref{Package Modules}).
+However, in-depth Scheme knowledge is @emph{not} a prerequisite for
+creating packages. For more information on package definitions,
+@pxref{Defining Packages}.
+
+Once a package definition is in place, stored in a file in the Guix
+source tree, it can be tested using the @command{guix build} command
+(@pxref{Invoking guix build}). For example, assuming the new package is
+called @code{gnew}, you may run this command from the Guix build tree
+(@pxref{Running Guix Before It Is Installed}):
+
+@example
+./pre-inst-env guix build gnew --keep-failed
+@end example
+
+Using @code{--keep-failed} makes it easier to debug build failures since
+it provides access to the failed build tree. Another useful
+command-line option when debugging is @code{--log-file}, to access the
+build log.
+
+If the package is unknown to the @command{guix} command, it may be that
+the source file contains a syntax error, or lacks a @code{define-public}
+clause to export the package variable. To figure it out, you may load
+the module from Guile to get more information about the actual error:
+
+@example
+./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
+@end example
+
+Once your package builds correctly, please send us a patch
+(@pxref{Submitting Patches}). Well, if you need help, we will be happy to
+help you too. Once the patch is committed in the Guix repository, the
+new package automatically gets built on the supported platforms by
+@url{http://hydra.gnu.org/jobset/gnu/master, our continuous integration
+system}.
+
+@cindex substituter
+Users can obtain the new package definition simply by running
+@command{guix pull} (@pxref{Invoking guix pull}). When
+@code{@value{SUBSTITUTE-SERVER}} is done building the package, installing the
+package automatically downloads binaries from there
+(@pxref{Substitutes}). The only place where human intervention is
+needed is to review and apply the patch.
+
+
+@menu
+* Software Freedom:: What may go into the distribution.
+* Package Naming:: What's in a name?
+* Version Numbers:: When the name is not enough.
+* Synopses and Descriptions:: Helping users find the right package.
+* Python Modules:: A touch of British comedy.
+* Perl Modules:: Little pearls.
+* Java Packages:: Coffee break.
+* Fonts:: Fond of fonts.
+@end menu
+
+@node Software Freedom
+@subsection Software Freedom
+
+@c Adapted from http://www.gnu.org/philosophy/philosophy.html.
+@cindex free software
+The GNU operating system has been developed so that users can have
+freedom in their computing. GNU is @dfn{free software}, meaning that
+users have the @url{http://www.gnu.org/philosophy/free-sw.html,four
+essential freedoms}: to run the program, to study and change the program
+in source code form, to redistribute exact copies, and to distribute
+modified versions. Packages found in the GNU distribution provide only
+software that conveys these four freedoms.
+
+In addition, the GNU distribution follow the
+@url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free
+software distribution guidelines}. Among other things, these guidelines
+reject non-free firmware, recommendations of non-free software, and
+discuss ways to deal with trademarks and patents.
+
+Some otherwise free upstream package sources contain a small and optional
+subset that violates the above guidelines, for instance because this subset
+is itself non-free code. When that happens, the offending items are removed
+with appropriate patches or code snippets in the @code{origin} form of the
+package (@pxref{Defining Packages}). This way, @code{guix
+build --source} returns the ``freed'' source rather than the unmodified
+upstream source.
+
+
+@node Package Naming
+@subsection Package Naming
+
+@cindex package name
+A package has actually two names associated with it:
+First, there is the name of the @emph{Scheme variable}, the one following
+@code{define-public}. By this name, the package can be made known in the
+Scheme code, for instance as input to another package. Second, there is
+the string in the @code{name} field of a package definition. This name
+is used by package management commands such as
+@command{guix package} and @command{guix build}.
+
+Both are usually the same and correspond to the lowercase conversion of
+the project name chosen upstream, with underscores replaced with
+hyphens. For instance, GNUnet is available as @code{gnunet}, and
+SDL_net as @code{sdl-net}.
+
+We do not add @code{lib} prefixes for library packages, unless these are
+already part of the official project name. But @pxref{Python
+Modules} and @ref{Perl Modules} for special rules concerning modules for
+the Python and Perl languages.
+
+Font package names are handled differently, @pxref{Fonts}.
+
+
+@node Version Numbers
+@subsection Version Numbers
+
+@cindex package version
+We usually package only the latest version of a given free software
+project. But sometimes, for instance for incompatible library versions,
+two (or more) versions of the same package are needed. These require
+different Scheme variable names. We use the name as defined
+in @ref{Package Naming}
+for the most recent version; previous versions use the same name, suffixed
+by @code{-} and the smallest prefix of the version number that may
+distinguish the two versions.
+
+The name inside the package definition is the same for all versions of a
+package and does not contain any version number.
+
+For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
+
+@example
+(define-public gtk+
+ (package
+ (name "gtk+")
+ (version "3.9.12")
+ ...))
+(define-public gtk+-2
+ (package
+ (name "gtk+")
+ (version "2.24.20")
+ ...))
+@end example
+If we also wanted GTK+ 3.8.2, this would be packaged as
+@example
+(define-public gtk+-3.8
+ (package
+ (name "gtk+")
+ (version "3.8.2")
+ ...))
+@end example
+
+@c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
+@c for a discussion of what follows.
+@cindex version number, for VCS snapshots
+Occasionally, we package snapshots of upstream's version control system
+(VCS) instead of formal releases. This should remain exceptional,
+because it is up to upstream developers to clarify what the stable
+release is. Yet, it is sometimes necessary. So, what should we put in
+the @code{version} field?
+
+Clearly, we need to make the commit identifier of the VCS snapshot
+visible in the version string, but we also need to make sure that the
+version string is monotonically increasing so that @command{guix package
+--upgrade} can determine which version is newer. Since commit
+identifiers, notably with Git, are not monotonically increasing, we add
+a revision number that we increase each time we upgrade to a newer
+snapshot. The resulting version string looks like this:
+
+@example
+2.0.11-3.cabba9e
+ ^ ^ ^
+ | | `-- upstream commit ID
+ | |
+ | `--- Guix package revision
+ |
+latest upstream version
+@end example
+
+It is a good idea to strip commit identifiers in the @code{version}
+field to, say, 7 digits. It avoids an aesthetic annoyance (assuming
+aesthetics have a role to play here) as well as problems related to OS
+limits such as the maximum shebang length (127 bytes for the Linux
+kernel.) It is best to use the full commit identifiers in
+@code{origin}s, though, to avoid ambiguities. A typical package
+definition may look like this:
+
+@example
+(define my-package
+ (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
+ (revision "1")) ;Guix package revision
+ (package
+ (version (git-version "0.9" revision commit))
+ (source (origin
+ (method git-fetch)
+ (uri (git-reference
+ (url "git://example.org/my-package.git")
+ (commit commit)))
+ (sha256 (base32 "1mbikn@dots{}"))
+ (file-name (git-file-name name version))))
+ ;; @dots{}
+ )))
+@end example
+
+@node Synopses and Descriptions
+@subsection Synopses and Descriptions
+
+@cindex package description
+@cindex package synopsis
+As we have seen before, each package in GNU@tie{}Guix includes a
+synopsis and a description (@pxref{Defining Packages}). Synopses and
+descriptions are important: They are what @command{guix package
+--search} searches, and a crucial piece of information to help users
+determine whether a given package suits their needs. Consequently,
+packagers should pay attention to what goes into them.
+
+Synopses must start with a capital letter and must not end with a
+period. They must not start with ``a'' or ``the'', which usually does
+not bring anything; for instance, prefer ``File-frobbing tool'' over ``A
+tool that frobs files''. The synopsis should say what the package
+is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is
+used for---e.g., the synopsis for GNU@tie{}grep is ``Print lines
+matching a pattern''.
+
+Keep in mind that the synopsis must be meaningful for a very wide
+audience. For example, ``Manipulate alignments in the SAM format''
+might make sense for a seasoned bioinformatics researcher, but might be
+fairly unhelpful or even misleading to a non-specialized audience. It
+is a good idea to come up with a synopsis that gives an idea of the
+application domain of the package. In this example, this might give
+something like ``Manipulate nucleotide sequence alignments'', which
+hopefully gives the user a better idea of whether this is what they are
+looking for.
+
+Descriptions should take between five and ten lines. Use full
+sentences, and avoid using acronyms without first introducing them.
+Please avoid marketing phrases such as ``world-leading'',
+``industrial-strength'', and ``next-generation'', and avoid superlatives
+like ``the most advanced''---they are not helpful to users looking for a
+package and may even sound suspicious. Instead, try to be factual,
+mentioning use cases and features.
+
+@cindex Texinfo markup, in package descriptions
+Descriptions can include Texinfo markup, which is useful to introduce
+ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or
+hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you
+should be careful when using some characters for example @samp{@@} and
+curly braces which are the basic special characters in Texinfo
+(@pxref{Special Characters,,, texinfo, GNU Texinfo}). User interfaces
+such as @command{guix package --show} take care of rendering it
+appropriately.
+
+Synopses and descriptions are translated by volunteers
+@uref{http://translationproject.org/domain/guix-packages.html, at the
+Translation Project} so that as many users as possible can read them in
+their native language. User interfaces search them and display them in
+the language specified by the current locale.
+
+To allow @command{xgettext} to extract them as translatable strings,
+synopses and descriptions @emph{must be literal strings}. This means
+that you cannot use @code{string-append} or @code{format} to construct
+these strings:
+
+@lisp
+(package
+ ;; @dots{}
+ (synopsis "This is translatable")
+ (description (string-append "This is " "*not*" " translatable.")))
+@end lisp
+
+Translation is a lot of work so, as a packager, please pay even more
+attention to your synopses and descriptions as every change may entail
+additional work for translators. In order to help them, it is possible
+to make recommendations or instructions visible to them by inserting
+special comments like this (@pxref{xgettext Invocation,,, gettext, GNU
+Gettext}):
+
+@example
+;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
+(description "ARandR is designed to provide a simple visual front end
+for the X11 resize-and-rotate (RandR) extension. @dots{}")
+@end example
+
+
+@node Python Modules
+@subsection Python Modules
+
+@cindex python
+We currently package Python 2 and Python 3, under the Scheme variable names
+@code{python-2} and @code{python} as explained in @ref{Version Numbers}.
+To avoid confusion and naming clashes with other programming languages, it
+seems desirable that the name of a package for a Python module contains
+the word @code{python}.
+
+Some modules are compatible with only one version of Python, others with both.
+If the package Foo compiles only with Python 3, we name it
+@code{python-foo}; if it compiles only with Python 2, we name it
+@code{python2-foo}. If it is compatible with both versions, we create two
+packages with the corresponding names.
+
+If a project already contains the word @code{python}, we drop this;
+for instance, the module python-dateutil is packaged under the names
+@code{python-dateutil} and @code{python2-dateutil}. If the project name
+starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
+described above.
+
+@subsubsection Specifying Dependencies
+@cindex inputs, for Python packages
+
+Dependency information for Python packages is usually available in the
+package source tree, with varying degrees of accuracy: in the
+@file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}.
+
+Your mission, when writing a recipe for a Python package, is to map
+these dependencies to the appropriate type of ``input'' (@pxref{package
+Reference, inputs}). Although the @code{pypi} importer normally does a
+good job (@pxref{Invoking guix import}), you may want to check the
+following check list to determine which dependency goes where.
+
+@itemize
+
+@item
+We currently package Python 2 with @code{setuptools} and @code{pip}
+installed like Python 3.4 has per default. Thus you don't need to
+specify either of these as an input. @command{guix lint} will warn you
+if you do.
+
+@item
+Python dependencies required at run time go into
+@code{propagated-inputs}. They are typically defined with the
+@code{install_requires} keyword in @file{setup.py}, or in the
+@file{requirements.txt} file.
+
+@item
+Python packages required only at build time---e.g., those listed with
+the @code{setup_requires} keyword in @file{setup.py}---or only for
+testing---e.g., those in @code{tests_require}---go into
+@code{native-inputs}. The rationale is that (1) they do not need to be
+propagated because they are not needed at run time, and (2) in a
+cross-compilation context, it's the ``native'' input that we'd want.
+
+Examples are the @code{pytest}, @code{mock}, and @code{nose} test
+frameworks. Of course if any of these packages is also required at
+run-time, it needs to go to @code{propagated-inputs}.
+
+@item
+Anything that does not fall in the previous categories goes to
+@code{inputs}, for example programs or C libraries required for building
+Python packages containing C extensions.
+
+@item
+If a Python package has optional dependencies (@code{extras_require}),
+it is up to you to decide whether to add them or not, based on their
+usefulness/overhead ratio (@pxref{Submitting Patches, @command{guix
+size}}).
+
+@end itemize
+
+
+@node Perl Modules
+@subsection Perl Modules
+
+@cindex perl
+Perl programs standing for themselves are named as any other package,
+using the lowercase upstream name.
+For Perl packages containing a single class, we use the lowercase class name,
+replace all occurrences of @code{::} by dashes and prepend the prefix
+@code{perl-}.
+So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
+Modules containing several classes keep their lowercase upstream name and
+are also prepended by @code{perl-}. Such modules tend to have the word
+@code{perl} somewhere in their name, which gets dropped in favor of the
+prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
+
+
+@node Java Packages
+@subsection Java Packages
+
+@cindex java
+Java programs standing for themselves are named as any other package,
+using the lowercase upstream name.
+
+To avoid confusion and naming clashes with other programming languages,
+it is desirable that the name of a package for a Java package is
+prefixed with @code{java-}. If a project already contains the word
+@code{java}, we drop this; for instance, the package @code{ngsjava} is
+packaged under the name @code{java-ngs}.
+
+For Java packages containing a single class or a small class hierarchy,
+we use the lowercase class name, replace all occurrences of @code{.} by
+dashes and prepend the prefix @code{java-}. So the class
+@code{apache.commons.cli} becomes package
+@code{java-apache-commons-cli}.
+
+
+@node Fonts
+@subsection Fonts
+
+@cindex fonts
+For fonts that are in general not installed by a user for typesetting
+purposes, or that are distributed as part of a larger software package,
+we rely on the general packaging rules for software; for instance, this
+applies to the fonts delivered as part of the X.Org system or fonts that
+are part of TeX Live.
+
+To make it easier for a user to search for fonts, names for other packages
+containing only fonts are constructed as follows, independently of the
+upstream package name.
+
+The name of a package containing only one font family starts with
+@code{font-}; it is followed by the foundry name and a dash @code{-}
+if the foundry is known, and the font family name, in which spaces are
+replaced by dashes (and as usual, all upper case letters are transformed
+to lower case).
+For example, the Gentium font family by SIL is packaged under the name
+@code{font-sil-gentium}.
+
+For a package containing several font families, the name of the collection
+is used in the place of the font family name.
+For instance, the Liberation fonts consist of three families,
+Liberation Sans, Liberation Serif and Liberation Mono.
+These could be packaged separately under the names
+@code{font-liberation-sans} and so on; but as the
This message was truncated. Download the full message here.
L
L
Ludovic Courtès wrote on 22 Jan 2019 23:20
Re: [bug#34156] [PATCH 0/4] Re-organize the manual
(address . 34156-done@debbugs.gnu.org)
87r2d4ibbi.fsf@gnu.org
Ludovic Courtès <ludo@gnu.org> skribis:

Toggle quote (5 lines)
> doc: Move sections under "GNU Distribution" one level higher.
> doc: Move "System Installation" right after "Installation".
> doc: Move "Packaging Guidelines" under "Contributing".
> doc: Move "Package Modules" under "Programming Interface".

Ricardo and Julien were almost enthusiastic about this change on IRC
;-), so I’ve just pushed it.

Ludo’.
Closed
R
R
Ricardo Wurmus wrote on 23 Jan 2019 09:21
Re: bug#34156: [PATCH 0/4] Re-organize the manual
(name . Ludovic Courtès)(address . ludo@gnu.org)(address . 34156-done@debbugs.gnu.org)
87k1iv7pjb.fsf@elephly.net
Ludovic Courtès <ludo@gnu.org> writes:

Toggle quote (10 lines)
> Ludovic Courtès <ludo@gnu.org> skribis:
>
>> doc: Move sections under "GNU Distribution" one level higher.
>> doc: Move "System Installation" right after "Installation".
>> doc: Move "Packaging Guidelines" under "Contributing".
>> doc: Move "Package Modules" under "Programming Interface".
>
> Ricardo and Julien were almost enthusiastic about this change on IRC
> ;-), so I’ve just pushed it.

Yay, thanks for the work!

--
Ricardo
Closed
?