From 227e0469dbfec7e47b57d824dcf45a04ac4026c9 Mon Sep 17 00:00:00 2001 From: Matthew Trzcinski Date: Sun, 24 Mar 2024 10:02:40 +0100 Subject: [PATCH] doc: Simplify installation instructions * doc/guix.texi (Installation): - Move the definition of "foreign distro" out of quotation - Repeat overwrite warning - Remove superfluous commentary * doc/guix.texi (Binary Installation): - Clarify that installing on a foreign distro has two methods: using packaged binaries and building from source - Add cross reference to "Building from Git" - Move the foreign distro installation instructions out of quotation - Move directions for 'guix-install.sh' after instructions to use distribution-specific package managers - Specify "distributions" as "GNU/Linux distributions" - Add GnuPG as a requirement for 'guix-install.sh' - Add comma after "Likewise" - Remove redundant instructions to use 'guix-install.sh' - Split the requirements between system requirements for binary installations, GNU/Linux or GNU/Hurd, and requirements for running 'guix-install.sh' - Clarify that 'guix-install.sh' guides users through the steps - Summarize the steps 'guix-install.sh' follows rather than try to detail them - Make explicit that the 'guix-install.sh' default is to download substitutes - Emphasize that the substitute authorization code is an example and may need modification Link: Signed-off-by: Maxim Cournoyer --- doc/guix.texi | 296 +++++++++----------------------------------------- 1 file changed, 51 insertions(+), 245 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index acfe60b47a..3cae7495f6 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -691,19 +691,20 @@ to join! @xref{Contributing}, for information about how you can help. @chapter Installation @cindex installing Guix +@cindex foreign distro +@cindex Guix System +You can install the package management tool Guix on top of an existing +GNU/Linux or GNU/Hurd system@footnote{Hurd support is currently +limited.}, referred to as a @dfn{foreign distro}. If, instead, you want +to install the complete, standalone GNU system distribution, +@dfn{Guix@tie{}System}, @pxref{System Installation}. This section is +concerned only with the installation of Guix on a foreign distro. -@quotation Note -We recommend the use of this -@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh, -shell installer script} to install Guix on top of a running GNU/Linux system, -thereafter called a @dfn{foreign distro}@footnote{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, @pxref{System Installation}.}. @xref{Binary -Installation}, for more information. +@quotation Important +This section only applies to systems without Guix. Following it for +existing Guix installations will overwrite important system files. @end quotation -@cindex foreign distro @cindex directories related to foreign distro When installed on a foreign distro, GNU@tie{}Guix complements the available tools without interference. Its data lives exclusively in two directories, @@ -713,11 +714,6 @@ such as @file{/etc}, are left untouched. Once installed, Guix can be updated by running @command{guix pull} (@pxref{Invoking guix pull}). -If you prefer to perform the installation steps manually or want to tweak -them, you may find the following subsections useful. They describe the -software requirements of Guix, as well as how to install it manually and get -ready to use it. - @menu * Binary Installation:: Getting Guix running in no time! * Requirements:: Software needed to build and run Guix. @@ -735,226 +731,69 @@ ready to use it. @cindex installer script This section describes how to install Guix from a self-contained tarball providing binaries for Guix and for all its dependencies. This is often -quicker than installing from source, which is described in the next -sections. Binary installation requires a system using a Hurd or Linux -kernel; the GNU@tie{}tar and Xz commands must also be available. +quicker than installing from source, described later (@pxref{Building +from Git}). @quotation Important This section only applies to systems without Guix. Following it for existing Guix installations will overwrite important system files. +@end quotation -@c Note duplicated from the ``Installation'' node. -We recommend the use of this -@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh, -shell installer script}. The script automates the download, installation, and -initial configuration steps described below. It should be run as the root -user. As root, you can thus run this: +Some GNU/Linux distributions, such as Debian, Ubuntu, and openSUSE +provide Guix through their own package managers. The version of Guix +may be older than @value{VERSION} but you can update it afterwards by +running @samp{guix pull}. -@example -cd /tmp -wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh -chmod +x guix-install.sh -./guix-install.sh -@end example - -The script automates the download, installation, and initial -configuration of Guix, interactively offering various configuration -options. - -@cindex uninstalling Guix -@cindex uninstallation, of Guix -Should you eventually want to uninstall Guix, run the same script with -the @option{--uninstall} flag: - -@example -./guix-install.sh --uninstall -@end example - -With @option{--uninstall}, the script irreversibly deletes all the Guix -files, configuration, and services. - -If you're running Debian or a derivative such as Ubuntu, you can instead -install the package (it might be a version older than @value{VERSION} -but you can update it afterwards by running @samp{guix pull}): +For Debian and Ubuntu-based systems, call: @example sudo apt install guix @end example -Likewise on openSUSE: +Likewise, on openSUSE: @example sudo zypper install guix @end example -When you're done, @pxref{Application Setup} for extra configuration you -might need, and @ref{Getting Started} for your first steps! -@end quotation +The Guix project also provides a shell script, @file{guix-install.sh}, +which automates the binary installation process without use of a foreign +distro package +manager@footnote{@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh}}. +Use of @file{guix-install.sh} requires Bash, GnuPG, GNU@tie{}tar, wget, +and Xz. -Installing goes along these lines: +The script guides you through the following: -@enumerate -@item -@cindex downloading Guix binary -Download the binary tarball from -@indicateurl{@value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz}, -where @code{x86_64-linux} can be replaced with @code{i686-linux} for an -@code{i686} (32-bits) machine already running the kernel Linux, and so on -(@pxref{GNU Distribution}). +@itemize +@item Downloading and extracting the binary tarball +@item Setting up the build daemon +@item Making the ‘guix’ command available to non-root users +@item Configuring substitute servers +@end itemize -@c The following is somewhat duplicated in ``System Installation''. -Make sure to download the associated @file{.sig} file and to verify the -authenticity of the tarball against it, along these lines: - -@example -$ wget @value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig -$ gpg --verify guix-binary-@value{VERSION}.x86_64-linux.tar.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 -$ wget '@value{OPENPGP-SIGNING-KEY-URL}' \ - -qO - | gpg --import - -@end example - -@noindent -and rerun the @code{gpg --verify} command. - -Take note that a warning like ``This key is not certified with a trusted -signature!'' is normal. - -@c end authentication part - -@item -Now, you need to become the @code{root} user. Depending on your distribution, -you may have to run @code{su -} or @code{sudo -i}. As @code{root}, run: +As root, run: @example # cd /tmp -# tar --warning=no-timestamp -xf \ - /path/to/guix-binary-@value{VERSION}.x86_64-linux.tar.xz -# mv var/guix /var/ && mv gnu / +# wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh +# chmod +x guix-install.sh +# ./guix-install.sh @end example -This creates @file{/gnu/store} (@pxref{The Store}) and @file{/var/guix}. -The latter contains a ready-to-use profile for @code{root} (see next -step). +@quotation Note +By default, @file{guix-install.sh} will configure Guix to download +pre-built package binaries, called @dfn{substitutes} +(@pxref{Substitutes}), from the project's build farms. If you choose +not to permit this, Guix will build @emph{everything} from source, +making each installation and upgrade very expensive. @xref{On Trusting +Binaries} for a discussion of why you may want to build packages from +source. -Do @emph{not} unpack the tarball on a working Guix system since that -would overwrite its own essential files. - -The @option{--warning=no-timestamp} option makes sure GNU@tie{}tar does -not emit warnings about ``implausibly old time stamps'' (such -warnings were triggered by GNU@tie{}tar 1.26 and older; recent -versions are fine). -They stem from the fact that all the -files in the archive have their modification time set to 1 (which -means January 1st, 1970). This is done on purpose to make sure the -archive content is independent of its creation time, thus making it -reproducible. - -@item -Make the profile available under @file{~root/.config/guix/current}, which is -where @command{guix pull} will install updates (@pxref{Invoking guix pull}): - -@example -# mkdir -p ~root/.config/guix -# ln -sf /var/guix/profiles/per-user/root/current-guix \ - ~root/.config/guix/current -@end example - -Source @file{etc/profile} to augment @env{PATH} and other relevant -environment variables: - -@example -# GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \ - source $GUIX_PROFILE/etc/profile -@end example - -@item -Create the group and user accounts for build users as explained below -(@pxref{Build Environment Setup}). - -@item -Run the daemon, and set it to automatically start on boot. - -If your host distro uses the systemd init system, this can be achieved -with these commands: - -@c Versions of systemd that supported symlinked service files are not -@c yet widely deployed, so we should suggest that users copy the service -@c files into place. -@c -@c See this thread for more information: -@c https://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html - -@example -# cp ~root/.config/guix/current/lib/systemd/system/gnu-store.mount \ - ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \ - /etc/systemd/system/ -# systemctl enable --now gnu-store.mount guix-daemon -@end example - -You may also want to arrange for @command{guix gc} to run periodically: - -@example -# cp ~root/.config/guix/current/lib/systemd/system/guix-gc.service \ - ~root/.config/guix/current/lib/systemd/system/guix-gc.timer \ - /etc/systemd/system/ -# systemctl enable --now guix-gc.timer -@end example - -You may want to edit @file{guix-gc.service} to adjust the command line -options to fit your needs (@pxref{Invoking guix gc}). - -If your host distro uses the Upstart init system: - -@example -# initctl reload-configuration -# cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \ - /etc/init/ -# start guix-daemon -@end example - -Otherwise, you can still start the daemon manually with: - -@example -# ~root/.config/guix/current/bin/guix-daemon \ - --build-users-group=guixbuild -@end example - -@item -Make the @command{guix} command available to other users on the machine, -for instance with: - -@example -# mkdir -p /usr/local/bin -# cd /usr/local/bin -# ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix -@end example - -It is also a good idea to make the Info version of this manual available -there: - -@example -# mkdir -p /usr/local/share/info -# cd /usr/local/share/info -# for i in /var/guix/profiles/per-user/root/current-guix/share/info/* ; - do ln -s $i ; done -@end example - -That way, assuming @file{/usr/local/share/info} is in the search path, -running @command{info guix} will open this manual (@pxref{Other Info -Directories,,, texinfo, GNU Texinfo}, for more details on changing the -Info search path). - -@item @cindex substitutes, authorization thereof To use substitutes from @code{@value{SUBSTITUTE-SERVER-1}}, -@code{@value{SUBSTITUTE-SERVER-2}} or a mirror (@pxref{Substitutes}), -authorize them: +@code{@value{SUBSTITUTE-SERVER-2}} or a mirror, you must authorize them. +For example, @example # guix archive --authorize < \ @@ -962,45 +801,8 @@ authorize them: # guix archive --authorize < \ ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-2}.pub @end example - -@quotation Note -If you do not enable substitutes, Guix will end up building -@emph{everything} from source on your machine, making each installation -and upgrade very expensive. @xref{On Trusting Binaries}, for a -discussion of reasons why one might want do disable substitutes. @end quotation -@item -Each user may need to perform a few additional steps to make their Guix -environment ready for use, @pxref{Application Setup}. -@end enumerate - -Voilà, the installation is complete! - -You can confirm that Guix is working by installing a sample package into -the root profile: - -@example -# guix install hello -@end example - -The binary installation tarball can be (re)produced and verified simply -by running the following command in the Guix source tree: - -@example -make guix-binary.@var{system}.tar.xz -@end example - -@noindent -...@: which, in turn, runs: - -@example -guix pack -s @var{system} --localstatedir \ - --profile-name=current-guix guix -@end example - -@xref{Invoking guix pack}, for more info on this handy tool. - @node Requirements @section Requirements @@ -1194,6 +996,9 @@ Some of them require a lot of storage space to hold VM images. Again in case of test failures, please send @email{bug-guix@@gnu.org} all the details. +When you're done installing Guix, @pxref{Application Setup} for extra +configuration you might need, and @ref{Getting Started} for your first +steps! @node Setting Up the Daemon @section Setting Up the Daemon @@ -17726,6 +17531,7 @@ configuration (@pxref{Using the Configuration System}). @table @asis @item @code{kernel} (default: @code{linux-libre}) +@c footnote duplicated in @pxref{Installation} The package object of the operating system kernel to use@footnote{Currently only the Linux-libre kernel is fully supported. Using GNU@tie{}mach with the GNU@tie{}Hurd is experimental and only