diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/contributing.texi | 49 | ||||
| -rw-r--r-- | doc/guix.texi | 101 |
2 files changed, 128 insertions, 22 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index 4ecff0a2dd..e656676c0f 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -38,6 +38,48 @@ version from the Git repository: git clone https://git.savannah.gnu.org/git/guix.git @end example +@cindex authentication, of a Guix checkout +How do you ensure that you obtained a genuine copy of the repository? +Guix itself provides a tool to @dfn{authenticate} your checkout, but you +must first make sure this tool is genuine in order to ``bootstrap'' the +trust chain. To do that, run: + +@c XXX: Adjust instructions when there's a known tag to start from. +@example +git verify-commit `git log --format=%H build-aux/git-authenticate.scm` +@end example + +The output must look something like: + +@example +gpg: Signature made Fri 27 Dec 2019 01:27:41 PM CET +gpg: using RSA key 3CE464558A84FDC69DB40CFB090B11993D9AEBB5 +@dots{} +gpg: Signature made Fri 27 Dec 2019 01:25:22 PM CET +gpg: using RSA key 3CE464558A84FDC69DB40CFB090B11993D9AEBB5 +@dots{} +@end example + +@noindent +... meaning that changes to this file are all signed with key +@code{3CE464558A84FDC69DB40CFB090B11993D9AEBB5} (you may need to fetch +this key from a key server, if you have not done it yet). + +From there on, you can authenticate all the commits included in your +checkout by running: + +@example +make authenticate +@end example + +The first run takes a couple of minutes, but subsequent runs are faster. + +@quotation Note +You are advised to run @command{make authenticate} after every +@command{git pull} invocation. This ensures you keep receiving valid +changes to the repository +@end quotation + The easiest way to set up a development environment for Guix is, of course, by using Guix! The following command starts a new shell where all the dependencies and appropriate environment variables are set up to @@ -962,11 +1004,8 @@ the URL: it is not very useful and if the name changes, the URL will probably be wrong. @item -See if Guix builds with -@example -guix environment --pure guix -- make -@end example -and look for warnings, especially those about use of undefined symbols. +Check if Guix builds (@pxref{Building from Git}) and address the +warnings, especially those about use of undefined symbols. @item Make sure your changes do not break Guix and simulate a @code{guix pull} with: diff --git a/doc/guix.texi b/doc/guix.texi index 01980bf2d3..efc59c1aaf 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -46,7 +46,7 @@ Copyright @copyright{} 2017, 2018 Carlo Zancanaro@* Copyright @copyright{} 2017 Thomas Danckaert@* Copyright @copyright{} 2017 humanitiesNerd@* Copyright @copyright{} 2017 Christopher Allan Webber@* -Copyright @copyright{} 2017, 2018 Marius Bakke@* +Copyright @copyright{} 2017, 2018, 2019 Marius Bakke@* Copyright @copyright{} 2017, 2019 Hartmut Goebel@* Copyright @copyright{} 2017, 2019 Maxim Cournoyer@* Copyright @copyright{} 2017, 2018, 2019 Tobias Geerinckx-Rice@* @@ -2472,7 +2472,7 @@ Boot the USB installation image in an VM: @example qemu-system-x86_64 -m 1024 -smp 1 -enable-kvm \ - -net user -net nic,model=virtio -boot menu=on,order=d \ + -nic user,model=virtio-net-pci -boot menu=on,order=d \ -drive file=guix-system.img \ -drive media=cdrom,file=guix-system-install-@value{VERSION}.@var{system}.iso @end example @@ -4598,6 +4598,18 @@ unsafe. The primary purpose of this operation is to facilitate inspection of archive contents coming from possibly untrusted substitute servers. +@item --list +@itemx -t +Read a single-item archive as served by substitute servers +(@pxref{Substitutes}) and print the list of files it contains, as in +this example: + +@example +$ wget -O - \ + https://@value{SUBSTITUTE-SERVER}/nar/lzip/@dots{}-emacs-26.3 \ + | lzip -d | guix archive -t +@end example + @end table @@ -10309,14 +10321,23 @@ updating list of substitutes from 'https://guix.example.org'... 100.0% local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim + differing files: + /lib/libcrypto.so.1.1 + /lib/libssl.so.1.1 + /gnu/store/@dots{}-git-2.5.0 contents differ: local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73 + differing file: + /libexec/git-core/git-fsck + /gnu/store/@dots{}-pius-2.1.1 contents differ: local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax https://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs + differing file: + /share/man/man1/pius.1.gz @dots{} @@ -10345,8 +10366,20 @@ results, the inclusion of random numbers, and directory listings sorted by inode number. See @uref{https://reproducible-builds.org/docs/}, for more information. -To find out what is wrong with this Git binary, we can do something along -these lines (@pxref{Invoking guix archive}): +To find out what is wrong with this Git binary, the easiest approach is +to run: + +@example +guix challenge git \ + --diff=diffoscope \ + --substitute-urls="https://@value{SUBSTITUTE-SERVER} https://guix.example.org" +@end example + +This automatically invokes @command{diffoscope}, which displays detailed +information about files that differ. + +Alternately, we can do something along these lines (@pxref{Invoking guix +archive}): @example $ wget -q -O - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0 \ @@ -10402,6 +10435,29 @@ The one option that matters is: Consider @var{urls} the whitespace-separated list of substitute source URLs to compare to. +@item --diff=@var{mode} +Upon mismatches, show differences according to @var{mode}, one of: + +@table @asis +@item @code{simple} (the default) +Show the list of files that differ. + +@item @code{diffoscope} +@itemx @var{command} +Invoke @uref{https://diffoscope.org/, Diffoscope}, passing it +two directories whose contents do not match. + +When @var{command} is an absolute file name, run @var{command} instead +of Diffoscope. + +@item @code{none} +Do not show further details about the differences. +@end table + +Thus, unless @code{--diff=none} is passed, @command{guix challenge} +downloads the store items from the given substitute servers so that it +can compare them. + @item --verbose @itemx -v Show details about matches (identical contents) in addition to @@ -20356,6 +20412,19 @@ The port on which to connect to the database. @end table @end deftp +@subsubheading Mumi + +@cindex Mumi, Debbugs Web interface +@cindex Debbugs, Mumi Web interface +@uref{https://git.elephly.net/gitweb.cgi?p=software/mumi.git, Mumi} is a +Web interface to the Debbugs bug tracker, by default for +@uref{https://bugs.gnu.org, the GNU instance}. Mumi is a Web server, +but it also fetches and indexes mail retrieved from Debbugs. + +@defvr {Scheme Variable} mumi-service-type +This is the service type for Mumi. +@end defvr + @subsubheading FastCGI @cindex fastcgi @cindex fcgiwrap @@ -26100,7 +26169,7 @@ below, which enables networking and requests 1@tie{}GiB of RAM for the emulated machine: @example -$ /gnu/store/@dots{}-run-vm.sh -m 1024 -net user +$ /gnu/store/@dots{}-run-vm.sh -m 1024 -smp 2 -net user,model=virtio-net-pci @end example The VM shares its store with the host system. @@ -26586,7 +26655,7 @@ vm-image} on x86_64 hardware: @example $ qemu-system-x86_64 \ - -net user -net nic,model=virtio \ + -nic user,model=virtio-net-pci \ -enable-kvm -m 1024 \ -device virtio-blk,drive=myhd \ -drive if=none,file=/tmp/qemu-image,id=myhd @@ -26599,16 +26668,14 @@ Here is what each of these options means: This specifies the hardware platform to emulate. This should match the host. -@item -net user +@item -nic user,model=virtio-net-pci Enable the unprivileged user-mode network stack. The guest OS can access the host but not vice versa. This is the simplest way to get the -guest OS online. - -@item -net nic,model=virtio -You must create a network interface of a given model. If you do not -create a NIC, the boot will fail. Assuming your hardware platform is +guest OS online. @code{model} specifies which network device to emulate: +@code{virtio-net-pci} is a special device made for virtualized operating +systems and recommended for most uses. Assuming your hardware platform is x86_64, you can get a list of available NIC models by running -@command{qemu-system-x86_64 -net nic,model=help}. +@command{qemu-system-x86_64 -nic model=help}. @item -enable-kvm If your system has hardware virtualization extensions, enabling the @@ -26632,11 +26699,11 @@ the ``myhd'' drive. @end table The default @command{run-vm.sh} script that is returned by an invocation of -@command{guix system vm} does not add a @command{-net user} flag by default. +@command{guix system vm} does not add a @command{-nic user} flag by default. To get network access from within the vm add the @code{(dhcp-client-service)} to your system definition and start the VM using -@command{`guix system vm config.scm` -net user}. An important caveat of using -@command{-net user} for networking is that @command{ping} will not work, because +@command{`guix system vm config.scm` -nic user}. An important caveat of using +@command{-nic user} for networking is that @command{ping} will not work, because it uses the ICMP protocol. You'll have to use a different command to check for network connectivity, for example @command{guix download}. @@ -26650,7 +26717,7 @@ To enable SSH inside a VM you need to add an SSH server like 22 by default, to the host. You can do this with @example -`guix system vm config.scm` -net user,hostfwd=tcp::10022-:22 +`guix system vm config.scm` -nic user,model=virtio-net-pci,hostfwd=tcp::10022-:22 @end example To connect to the VM you can run |