guix: update docs

This commit is contained in:
tobtoht 2023-10-10 14:54:19 +02:00
parent 10272e88ea
commit cdc31c5929
No known key found for this signature in database
GPG key ID: E45B10DD027D2472
2 changed files with 94 additions and 64 deletions

View file

@ -58,11 +58,11 @@ writing (July 2021). Guix is expected to be more widely packaged over time. For
an up-to-date view on Guix's package status/version across distros, please see: an up-to-date view on Guix's package status/version across distros, please see:
https://repology.org/project/guix/versions https://repology.org/project/guix/versions
### Debian 11 (Bullseye)/Ubuntu 21.04 (Hirsute Hippo) ### Debian / Ubuntu
Guix v1.2.0 is available as a distribution package starting in [Debian Guix v1.2.0 is available as a distribution package starting in [Debian
11](https://packages.debian.org/bullseye/guix) and [Ubuntu 11](https://packages.debian.org/bullseye/guix) and [Ubuntu
21.04](https://packages.ubuntu.com/hirsute/guix). 21.04](https://packages.ubuntu.com/search?keywords=guix).
Note that if you intend on using Guix without using any substitutes (more Note that if you intend on using Guix without using any substitutes (more
details [here][security-model]), v1.2.0 has a known problem when building GnuTLS details [here][security-model]), v1.2.0 has a known problem when building GnuTLS
@ -102,7 +102,7 @@ either:
2. Or, check their build directory's length beforehand 2. Or, check their build directory's length beforehand
- For those building with `makepkg`: `pwd | wc -c` - For those building with `makepkg`: `pwd | wc -c`
## Option 4: Building from source ## Option 5: Building from source
Building Guix from source is a rather involved process but a rewarding one for Building Guix from source is a rather involved process but a rewarding one for
those looking to minimize trust and maximize customizability (e.g. building a those looking to minimize trust and maximize customizability (e.g. building a
@ -153,6 +153,10 @@ For reference, the graphic below outlines Guix v1.3.0's dependency graph:
![bootstrap map](https://user-images.githubusercontent.com/6399679/125064185-a9a59880-e0b0-11eb-82c1-9b8e5dc9950d.png) ![bootstrap map](https://user-images.githubusercontent.com/6399679/125064185-a9a59880-e0b0-11eb-82c1-9b8e5dc9950d.png)
#### Consider /tmp on tmpfs
If you use an NVME (SSD) drive, you may encounter [cryptic build errors](#coreutils-fail-teststail-2inotify-dir-recreate). Mounting a [tmpfs at /tmp](https://ubuntu.com/blog/data-driven-analysis-tmp-on-tmpfs) should prevent this and may improve performance as a bonus.
#### Guile #### Guile
##### Choosing a Guile version and sticking to it ##### Choosing a Guile version and sticking to it
@ -320,6 +324,8 @@ packages in Debian at the time of writing.
|-----------------------|---------------------| |-----------------------|---------------------|
| guile-gcrypt | libgcrypt-dev | | guile-gcrypt | libgcrypt-dev |
| guile-git | libgit2-dev | | guile-git | libgit2-dev |
| guile-gnutls | (none) |
| guile-json | (none) |
| guile-lzlib | liblz-dev | | guile-lzlib | liblz-dev |
| guile-ssh | libssh-dev | | guile-ssh | libssh-dev |
| guile-sqlite3 | libsqlite3-dev | | guile-sqlite3 | libsqlite3-dev |
@ -367,13 +373,6 @@ Start by cloning Guix:
``` ```
git clone https://git.savannah.gnu.org/git/guix.git git clone https://git.savannah.gnu.org/git/guix.git
cd guix cd guix
```
You will likely want to build the latest release, however, if the latest release
when you're reading this is still 1.2.0 then you may want to use 95aca29 instead
to avoid a problem in the GnuTLS test suite.
```
git branch -a -l 'origin/version-*' # check for the latest release git branch -a -l 'origin/version-*' # check for the latest release
git checkout <latest-release> git checkout <latest-release>
``` ```
@ -556,7 +555,7 @@ sudo --login guix pull --commit=<particular-commit>
``` ```
`guix pull` is quite a long process (especially if you're using `guix pull` is quite a long process (especially if you're using
`--no-substitute`). If you encounter build problems, please refer to the `--no-substitutes`). If you encounter build problems, please refer to the
[troubleshooting section](#troubleshooting). [troubleshooting section](#troubleshooting).
Note that running a bare `guix pull` with no commit or branch specified will Note that running a bare `guix pull` with no commit or branch specified will
@ -594,6 +593,8 @@ systemctl enable guix-daemon
systemctl start guix-daemon systemctl start guix-daemon
``` ```
Remember to set `--no-substitutes` in `$libdir/systemd/system/guix-daemon.service` and other customizations if you used them for `guix-daemon-original.service`.
##### If you installed Guix via the Debian/Ubuntu distribution packages ##### If you installed Guix via the Debian/Ubuntu distribution packages
You will need to create a `guix-daemon-latest` service which points to the new You will need to create a `guix-daemon-latest` service which points to the new
@ -702,6 +703,19 @@ $ bzcat /var/log/guix/drvs/../...-foo-3.6.12.drv.bz2 | less
times, it may be `/tmp/...drv-1` or `/tmp/...drv-2`. Always consult the build times, it may be `/tmp/...drv-1` or `/tmp/...drv-2`. Always consult the build
failure output for the most accurate, up-to-date information. failure output for the most accurate, up-to-date information.
### openssl-1.1.1l and openssl-1.1.1n
OpenSSL includes tests that will fail once some certificate has expired. A workaround
is to change your system clock:
```sh
sudo timedatectl set-ntp no
sudo date --set "28 may 2022 15:00:00"
sudo --login guix build --cores=1 /gnu/store/g9alz81w4q03ncm542487xd001s6akd4-openssl-1.1.1l.drv
sudo --login guix build --cores=1 /gnu/store/mw6ax0gk33gh082anrdrxp2flrbskxv6-openssl-1.1.1n.drv
sudo timedatectl set-ntp yes
```
### python(-minimal): [Errno 84] Invalid or incomplete multibyte or wide character ### python(-minimal): [Errno 84] Invalid or incomplete multibyte or wide character
This error occurs when your `$TMPDIR` (default: /tmp) exists on a filesystem This error occurs when your `$TMPDIR` (default: /tmp) exists on a filesystem
@ -759,7 +773,7 @@ The inotify-dir-create test fails on "remote" filesystems such as overlayfs
as non-remote. as non-remote.
A relatively easy workaround to this is to make sure that a somewhat traditional A relatively easy workaround to this is to make sure that a somewhat traditional
filesystem is mounted at `/tmp` (where `guix-daemon` performs its builds). For filesystem is mounted at `/tmp` (where `guix-daemon` performs its builds), see [/tmp on tmpfs](#consider-tmp-on-tmpfs). For
Docker users, this might mean [using a volume][docker/volumes], [binding Docker users, this might mean [using a volume][docker/volumes], [binding
mounting][docker/bind-mnt] from host, or (for those with enough RAM and swap) mounting][docker/bind-mnt] from host, or (for those with enough RAM and swap)
[mounting a tmpfs][docker/tmpfs] using the `--tmpfs` flag. [mounting a tmpfs][docker/tmpfs] using the `--tmpfs` flag.
@ -767,7 +781,7 @@ mounting][docker/bind-mnt] from host, or (for those with enough RAM and swap)
Please see the following links for more details: Please see the following links for more details:
- An upstream coreutils bug has been filed: [debbugs#47940](https://debbugs.gnu.org/cgi/bugreport.cgi?bug=47940) - An upstream coreutils bug has been filed: [debbugs#47940](https://debbugs.gnu.org/cgi/bugreport.cgi?bug=47940)
- A Guix bug detailing the underlying problem has been filed: [guix-issues#47935](https://issues.guix.gnu.org/47935) - A Guix bug detailing the underlying problem has been filed: [guix-issues#47935](https://issues.guix.gnu.org/47935), [guix-issues#49985](https://issues.guix.gnu.org/49985#5)
- A commit to skip this test in Guix has been merged into the core-updates branch: - A commit to skip this test in Guix has been merged into the core-updates branch:
[savannah/guix@6ba1058](https://git.savannah.gnu.org/cgit/guix.git/commit/?id=6ba1058df0c4ce5611c2367531ae5c3cdc729ab4) [savannah/guix@6ba1058](https://git.savannah.gnu.org/cgit/guix.git/commit/?id=6ba1058df0c4ce5611c2367531ae5c3cdc729ab4)
@ -784,3 +798,39 @@ Please see the following links for more details:
[docker/volumes]: https://docs.docker.com/storage/volumes/ [docker/volumes]: https://docs.docker.com/storage/volumes/
[docker/bind-mnt]: https://docs.docker.com/storage/bind-mounts/ [docker/bind-mnt]: https://docs.docker.com/storage/bind-mounts/
[docker/tmpfs]: https://docs.docker.com/storage/tmpfs/ [docker/tmpfs]: https://docs.docker.com/storage/tmpfs/
# Purging/Uninstalling Guix
In the extraordinarily rare case where you messed up your Guix installation in
an irreversible way, you may want to completely purge Guix from your system and
start over.
1. Uninstall Guix itself according to the way you installed it (e.g. `sudo apt
purge guix` for Ubuntu packaging, `sudo make uninstall` for a build from source).
2. Remove all build users and groups
You may check for relevant users and groups using:
```
getent passwd | grep guix
getent group | grep guix
```
Then, you may remove users and groups using:
```
sudo userdel <user>
sudo groupdel <group>
```
3. Remove all possible Guix-related directories
- `/var/guix/`
- `/var/log/guix/`
- `/gnu/`
- `/etc/guix/`
- `/home/*/.config/guix/`
- `/home/*/.cache/guix/`
- `/home/*/.guix-profile/`
- `/root/.config/guix/`
- `/root/.cache/guix/`
- `/root/.guix-profile/`

View file

@ -301,6 +301,12 @@ Where `<PREFIX>` is likely:
- `/usr/local` if you installed Guix from source and didn't supply any - `/usr/local` if you installed Guix from source and didn't supply any
prefix-modifying flags to Guix's `./configure` prefix-modifying flags to Guix's `./configure`
For dongcarl's substitute server at https://guix.carldong.io, run as root:
```sh
wget -qO- 'https://guix.carldong.io/signing-key.pub' | guix archive --authorize
```
#### Removing authorized keys #### Removing authorized keys
To remove previously authorized keys, simply edit `/etc/guix/acl` and remove the To remove previously authorized keys, simply edit `/etc/guix/acl` and remove the
@ -311,7 +317,30 @@ To remove previously authorized keys, simply edit `/etc/guix/acl` and remove the
Once its key is authorized, the official Guix build farm at Once its key is authorized, the official Guix build farm at
https://ci.guix.gnu.org is automatically used unless the `--no-substitutes` flag https://ci.guix.gnu.org is automatically used unless the `--no-substitutes` flag
is supplied. This default list of substitute servers is overridable both on a is supplied. This default list of substitute servers is overridable both on a
`guix-daemon` level and when you invoke `guix` commands. `guix-daemon` level and when you invoke `guix` commands. See examples below for
the various ways of adding dongcarl's substitute server after having [authorized
his signing key](#step-1-authorize-the-signing-keys).
Change the **default list** of substitute servers by starting `guix-daemon` with
the `--substitute-urls` option (you will likely need to edit your init script):
```sh
guix-daemon <cmd> --substitute-urls='https://guix.carldong.io https://ci.guix.gnu.org'
```
Override the default list of substitute servers by passing the
`--substitute-urls` option for invocations of `guix` commands:
```sh
guix <cmd> --substitute-urls='https://guix.carldong.io https://ci.guix.gnu.org'
```
For scripts under `./contrib/guix`, set the `SUBSTITUTE_URLS` environment
variable:
```sh
export SUBSTITUTE_URLS='https://guix.carldong.io https://ci.guix.gnu.org'
```
## Option 2: Disabling substitutes on an ad-hoc basis ## Option 2: Disabling substitutes on an ad-hoc basis
@ -338,55 +367,6 @@ used.
If you start `guix-daemon` using an init script, you can edit said script to If you start `guix-daemon` using an init script, you can edit said script to
supply this flag. supply this flag.
# Purging/Uninstalling Guix
In the extraordinarily rare case where you messed up your Guix installation in
an irreversible way, you may want to completely purge Guix from your system and
start over.
1. Uninstall Guix itself according to the way you installed it (e.g. `sudo apt
purge guix` for Ubuntu packaging, `sudo make uninstall` for a build from source).
2. Remove all build users and groups
You may check for relevant users and groups using:
```
getent passwd | grep guix
getent group | grep guix
```
Then, you may remove users and groups using:
```
sudo userdel <user>
sudo groupdel <group>
```
3. Remove all possible Guix-related directories
- `/var/guix/`
- `/var/log/guix/`
- `/gnu/`
- `/etc/guix/`
- `/home/*/.config/guix/`
- `/home/*/.cache/guix/`
- `/home/*/.guix-profile/`
- `/root/.config/guix/`
- `/root/.cache/guix/`
- `/root/.guix-profile/`
[b17e]: https://bootstrappable.org/ [b17e]: https://bootstrappable.org/
[r12e/source-date-epoch]: https://reproducible-builds.org/docs/source-date-epoch/ [r12e/source-date-epoch]: https://reproducible-builds.org/docs/source-date-epoch/
[guix/install.sh]: https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
[guix/bin-install]: https://www.gnu.org/software/guix/manual/en/html_node/Binary-Installation.html
[guix/env-setup]: https://www.gnu.org/software/guix/manual/en/html_node/Build-Environment-Setup.html
[guix/substitutes]: https://www.gnu.org/software/guix/manual/en/html_node/Substitutes.html
[guix/substitute-server-auth]: https://www.gnu.org/software/guix/manual/en/html_node/Substitute-Server-Authorization.html
[guix/time-machine]: https://guix.gnu.org/manual/en/html_node/Invoking-guix-time_002dmachine.html
[debian/guix-bullseye]: https://packages.debian.org/bullseye/guix
[ubuntu/guix-hirsute]: https://packages.ubuntu.com/hirsute/guix
[fanquake/guix-docker]: https://github.com/fanquake/core-review/tree/master/guix
[env-vars-list]: #recognized-environment-variables [env-vars-list]: #recognized-environment-variables