summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2014-07-15 00:43:04 +0200
committerLudovic Courtès <ludo@gnu.org>2014-07-15 00:43:04 +0200
commit5af6de3e67cd2f90773d9ca36ecd19a1177063fd (patch)
treee6f3574ac837eb07d6aad032751078db74dff3db
parent8f297d422a2571e303f4ee40081e30304b5394e2 (diff)
doc: Add a "System Installation" node.
* doc/guix.texi (Installation): Add cross-ref to "System Installation". (System Installation): New section. (System Configuration): Remove disclaimer.
-rw-r--r--doc/guix.texi176
1 files changed, 172 insertions, 4 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index 688b5e3d34..7187f76936 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -126,6 +126,11 @@ GNU Guix is available for download from its website at
software requirements of Guix, as well as how to install it and get
ready to use it.
+Note that this section is concerned with the installation of the package
+manager, which can be done on top of a running GNU/Linux system. If,
+instead, you want to install the complete GNU operating system,
+@ref{System Installation}.
+
The build procedure for Guix is the same as for other GNU software, and
is not covered here. Please see the files @file{README} and
@file{INSTALL} in the Guix source tree for additional details.
@@ -2598,6 +2603,7 @@ For information on porting to other architectures or kernels,
@xref{Porting}.
@menu
+* System Installation:: Installing the whole operating system.
* Installing Debugging Files:: Feeding the debugger.
* Package Modules:: Packages from the programmer's viewpoint.
* Packaging Guidelines:: Growing the distribution.
@@ -2609,6 +2615,172 @@ For information on porting to other architectures or kernels,
Building this distribution is a cooperative effort, and you are invited
to join! @ref{Contributing}, for information about how you can help.
+@node System Installation
+@section System Installation
+
+This section explains how to install the complete GNU operating system
+on a machine. The Guix package manager can also be installed on top of
+a running GNU/Linux system, @ref{Installation}.
+
+@ifinfo
+@c This paragraph is for people reading this from tty2 of the
+@c installation image.
+You're 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: @ref{Help,,, info, Info: An Introduction}. Hit
+@kbd{l} afterwards to come back here.
+@end ifinfo
+
+@emph{This section documents work-in-progress. The system lacks
+features and may be buggy. 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.}
+
+@subsection USB Stick Installation
+
+An installation image for USB sticks can be downloaded from
+@url{ftp://alpha.gnu.org/gnu/guix/gnu-usb-install-@value{VERSION}.@var{system}.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
+
+This image contains a single partition with the tools necessary for an
+installation. It is meant to be copied @emph{as is} to a large-enough
+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 gnu-usb-install-@value{VERSION}.@var{system}.xz
+@end example
+
+@item
+Insert a USB stick of 1@tie{}GiB or more in your machine, and determine
+its device name. Assuming that USB stick is known as @file{/dev/sdX},
+copy the image with:
+
+@example
+dd if=gnu-usb-install-20140629.x86_64 of=/dev/sdX
+@end example
+
+Access to @file{/dev/sdX} usually requires root privileges.
+@end enumerate
+
+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.
+
+@subsection Preparing for Installation
+
+Once you have successfully booted the image on the USB stick, you should
+end up with a root prompt. Several console TTYs are configured and can
+be used to run commands as root. TTY2 shows this documentation,
+browsable using the Info reader commands (@pxref{Help,,, info, Info: An
+Introduction}).
+
+To install the system, you would:
+
+@enumerate
+
+@item
+Configure the network, by running @command{dhclient eth0} (to get an
+automatically assigned IP address from the wired network interface
+controller), or using the @command{ifconfig} command.
+
+The system automatically loads drivers for your network interface
+controllers.
+
+Setting up network access is almost always a requirement because the
+image does not contain all the software and tools that may be needed.
+
+@item
+Unless this has already been done, you must partition and format the
+target partitions.
+
+The installation image includes Parted (@pxref{Overview,,, parted, GNU
+Parted User Manual}), @command{fdisk}, and e2fsprogs, the suite of tools
+to manipulate ext2/ext3/ext4 file systems.
+
+@end enumerate
+
+Once that is done, mount the target root partition under @file{/mnt}.
+
+@subsection Proceeding with the Installation
+
+With the target partitions ready, you now 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}.
+
+A minimal operating system configuration, with just the bare minimum and
+only a root account would look like this:
+
+@example
+(use-modules (gnu))
+
+(operating-system
+ (host-name "foo")
+ (timezone "Europe/Paris")
+ (locale "en_US.UTF-8")
+
+ ;; Assuming /dev/sdX is the target hard disk, and /dev/sdX1 the
+ ;; target root file system.
+ (bootloader (grub-configuration (device "/dev/sdX")))
+ (file-systems (list (file-system
+ (device "/dev/sdX1")
+ (mount-point "/")
+ (type "ext4")))))
+@end example
+
+@noindent
+For more information on @code{operating-system} declarations,
+@xref{Using the Configuration System}.
+
+Once that is done, the new system must be initialized (remember that the
+target root file system is mounted under @file{/mnt}):
+
+@example
+guix system init /mnt/etc/config.scm /mnt
+@end example
+
+@noindent
+This will copy all the necessary files, and install GRUB on
+@file{/dev/sdX}, unless you pass the @option{--no-grub} option. For
+more information, @xref{Invoking guix system}. This command may trigger
+downloads or builds of missing packages, which can take some time.
+
+Once that command has completed---and hopefully succeeded!---you can
+unmount @file{/mnt} and boot into the new system. Cross fingers, and
+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.
+
+@subsection Building the Installation Image
+
+The installation image described above was built using the @command{guix
+system} command, specifically:
+
+@example
+guix system disk-image --image-size=800MiB gnu/system/install.scm
+@end example
+
+@xref{Invoking guix system}, for more information. See
+@file{gnu/system/install.scm} in the source tree for more information
+about the installation image.
+
@node Installing Debugging Files
@section Installing Debugging Files
@@ -3079,10 +3251,6 @@ reason.
@node System Configuration
@section System Configuration
-@emph{This section documents work-in-progress. As such it may be
-incomplete, outdated, or open to discussions. Please discuss it on
-@email{guix-devel@@gnu.org}.}
-
@cindex system configuration
The GNU system supports a consistent whole-system configuration
mechanism. By that we mean that all aspects of the global system