02/02: doc: Provide more details about system installation.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository guix.

commit dedb8d5ece44da217452af203c8278d33ecd77eb
Author: Ludovic Courtès <address@hidden>
Date:   Wed Feb 10 21:26:29 2016 +0100

    doc: Provide more details about system installation.
    
    * doc/guix.texi (System Installation): Turn all subsections into
    individual nodes.
    (Limitations): Update the number of packages.
    (Preparing for Installation)[Keyboard Layout, Networking, Disk
    Partitionning]: New subsections.  Move the 'cow-store' thing to...
    (Proceeding with the Installation): ... here.  Describe things in more
    detail.
    (Base Services): Add index entry for "keyboard layout".
    
    Co-authored-by: Petter <address@hidden>.
---
 doc/guix.texi |  206 ++++++++++++++++++++++++++++++++++++++++++++------------
 1 files changed, 162 insertions(+), 44 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index bcb51c5..ee5cb5d 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -5527,6 +5527,15 @@ link that follows: @pxref{Help,,, info, Info: An 
Introduction}.  Hit
 @kbd{l} afterwards to come back here.
 @end ifinfo
 
address@hidden
+* Limitations::                         What you can expect.
+* USB Stick Installation::              Preparing the installation medium.
+* Preparing for Installation::          Networking, partitioning, etc.
+* Proceeding with the Installation::    The real thing.
+* Building the Installation Image::     How this comes to be.
address@hidden menu
+
address@hidden Limitations
 @subsection Limitations
 
 As of version @value{VERSION}, the Guix System Distribution (GuixSD) is
@@ -5561,7 +5570,7 @@ Few system services are currently supported out-of-the-box
 (@pxref{Services}).
 
 @item
-More than 2,000 packages are available, but you may
+More than 3,000 packages are available, but you may
 occasionally find that a useful package is missing.
 @end itemize
 
@@ -5569,6 +5578,7 @@ You've been warned.  But more than a disclaimer, this is 
an invitation
 to report issues (and success stories!), and join us in improving it.
 @xref{Contributing}, for more info.
 
address@hidden USB Stick Installation
 @subsection USB Stick Installation
 
 An installation image for USB sticks can be downloaded from
@@ -5613,6 +5623,7 @@ Once this is done, you should be able to reboot the 
system and boot from
 the USB stick.  The latter usually requires you to get in the BIOS' boot
 menu, where you can choose to boot from the USB stick.
 
address@hidden Preparing for Installation
 @subsection Preparing for Installation
 
 Once you have successfully booted the image on the USB stick, you should
@@ -5623,47 +5634,123 @@ Introduction}).  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.
 
-To install the system, you would:
address@hidden Keyboard Layout
 
address@hidden
address@hidden 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:
 
address@hidden
-Configure the network, by running:
address@hidden
+loadkeys dvorak
address@hidden 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.
+
address@hidden Networking
+
+Run the following command see what your network interfaces are called:
 
 @example
-ifconfig eno1 up && dhclient eno1
+ifconfig -a
 @end example
 
-to get an automatically assigned IP address from the wired
-network interface address@hidden
 @c 
http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
-The name @code{eno1} is for the first on-board Ethernet controller.  The
-interface name for an Ethernet controller that is in the first slot of
-the first PCI bus, for instance, would be @code{enp1s0}.  Use
address@hidden -a} to list all the available network interfaces.},
-or using the @command{ifconfig} command.
+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
address@hidden, like @samp{w1p2s0}.
+
address@hidden @asis
address@hidden Wired connection
+To configure a wired network run the following command, substituting
address@hidden with the name of the wired interface you want to use.
+
address@hidden
+ifconfig @var{interface} up
address@hidden example
+
address@hidden Wireless connection
+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
address@hidden:
+
address@hidden
+zile wpa_supplicant.conf
address@hidden 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:
+
address@hidden
address@hidden
+  address@hidden
+  key_mgmt=WPA-PSK
+  psk="the network's secret passphrase"
address@hidden
address@hidden 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):
+
address@hidden
+wpa_supplicant -c wpa_supplicant.conf -i @var{interface} -B
address@hidden example
+
+Run @command{man wpa_supplication} for more information.
address@hidden table
+
+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:
+
address@hidden
+dhclient @var{interface}
address@hidden example
 
-The system automatically loads drivers for your network interface
-controllers.
+Try to ping a server to see if networking is up and running:
+
address@hidden
+ping -c 3 gnu.org
address@hidden 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.
 
address@hidden
-Unless this has already been done, you must partition, and then format
-the target partition.
address@hidden 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}),
address@hidden, and @command{cfdisk}.  Run it and set up your disk with
+the partition layout you want:
+
address@hidden
+cfdisk
address@hidden example
+
+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 pretty much assumes an ext4 file system.  In particular, code
+that reads partition UUIDs and labels only works with ext4.  This will
+be fixed in the future.}.
 
 Preferably, assign partitions 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
address@hidden and related commands.
address@hidden and related commands.  So, assuming the target root
+partition lives at @file{/dev/sda1}, a file system with the label
address@hidden can be created with:
 
-Be sure that your partition labels match the value of their respective
address@hidden fields in your @code{file-system} configuration, if your
address@hidden configuration sets the value of @code{title} to
address@hidden'label}, as do the example configurations found on the USB
-installation image under @file{/etc/configuration} (@pxref{Using the
-Configuration System}).
address@hidden
+mkfs.ext4 -L my-root /dev/sda1
address@hidden example
 
 @c FIXME: Uncomment this once GRUB fully supports encrypted roots.
 @c A typical command sequence may be:
@@ -5676,37 +5763,66 @@ Configuration System}).
 @c # mkfs.ext4 -L my-root /dev/mapper/my-partition
 @c @end example
 
-The installation image includes Parted (@pxref{Overview,,, parted, GNU
-Parted User Manual}), @command{fdisk}, Cryptsetup/LUKS for disk
-encryption, and e2fsprogs, the suite of tools to manipulate
-ext2/ext3/ext4 file systems.
+In addition to e2fsprogs, the suite of tools to manipulate
+ext2/ext3/ext4 file systems, the installation image includes
+Cryptsetup/LUKS for disk encryption.
 
address@hidden
-Once that is done, mount the target root partition under @file{/mnt}.
+Once that is done, mount the target root partition under @file{/mnt}
+with a command like (again, assuming @file{/dev/sda1} is the root
+partition):
 
address@hidden
-Lastly, run @code{herd start cow-store /mnt}.
address@hidden
+mount /dev/sda1 /mnt
address@hidden example
 
-This will make @file{/gnu/store} copy-on-write, such that packages added
-to it during the installation phase will be written to the target disk
-rather than kept in memory.
address@hidden Proceeding with the Installation
address@hidden Proceeding with the Installation
 
address@hidden enumerate
+With the target partitions ready and the target root mounted on
address@hidden/mnt}, we're ready to go.  First, run:
 
address@hidden
+herd start cow-store /mnt
address@hidden example
 
address@hidden Proceeding with the Installation
+This makes @file{/gnu/store} copy-on-write, such that packages added to
+it during the installation phase are written to the target disk rather
+than kept in memory.
 
-With the target partitions ready, you now have to edit a file and
+Next, you have to edit a file and
 provide the declaration of the operating system to be installed.  To
 that end, the installation system comes with two text editors: GNU nano
 (@pxref{Top,,, nano, GNU nano Manual}), and GNU Zile, an Emacs clone.
 It is better to store that file on the target root file system, say, as
 @file{/mnt/etc/config.scm}.
 
address@hidden the Configuration System}, for examples of operating system
-configurations.  These examples are available under
address@hidden/etc/configuration} in the installation image, so you can copy
-them and use them as a starting point for your own configuration.
address@hidden the Configuration System}, for an overview of the
+configuration file.  The example configurations discussed in that
+section are available under @file{/etc/configuration} in the
+installation image.  Thus, to get started with a system configuration
+providing a graphical display server (a ``desktop'' system), you can run
+something along these lines:
+
address@hidden
+# mkdir /mnt/etc
+# cp /etc/configuration/desktop.scm /mnt/etc/config.scm
+# zile /mnt/etc/config.scm
address@hidden example
+
+You should pay attention to what your configuration file contains, and
+in particular:
+
address@hidden
address@hidden
+Make sure the @code{grub-configuration} form refers to the device you
+want to install GRUB on.
+
address@hidden
+Be sure that your partition labels match the value of their respective
address@hidden fields in your @code{file-system} configuration, assuming
+your @code{file-system} configuration sets the value of @code{title} to
address@hidden'label}.
address@hidden itemize
 
 Once you are done preparing the configuration file, the new system must
 be initialized (remember that the target root file system is mounted
@@ -5717,7 +5833,7 @@ guix system init /mnt/etc/config.scm /mnt
 @end example
 
 @noindent
-This will copy all the necessary files, and install GRUB on
+This copies all the necessary files and installs GRUB on
 @file{/dev/sdX}, unless you pass the @option{--no-grub} option.  For
 more information, @pxref{Invoking guix system}.  This command may trigger
 downloads or builds of missing packages, which can take some time.
@@ -5733,6 +5849,7 @@ Join us on @code{#guix} on the Freenode IRC network or on
 @file{guix-devel@@gnu.org} to share your experience---good or not so
 good.
 
address@hidden Building the Installation Image
 @subsection Building the Installation Image
 
 The installation image described above was built using the @command{guix
@@ -6844,6 +6961,7 @@ Run @var{udev}, which populates the @file{/dev} directory 
dynamically.
 @end deffn
 
 @deffn {Scheme Procedure} console-keymap-service @var{file}
address@hidden keyboard layout
 Return a service to load console keymap from @var{file} using
 @command{loadkeys} command.
 @end deffn