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: <https://lists.gnu.org/archive/html/guix-devel/2024-03/msg00023.html> Signed-off-by: Maxim Cournoyer <maxim.cournoyer@gmail.com>master
Matthew Trzcinski
Maxim Cournoyer
parent
93ccf08b4a
commit
227e0469db
296
doc/guix.texi
296
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
|
||||
|
|
|
|||
Reference in New Issue