bug#26295: [PATCH] 'Debugging Build Failures' subsection

[ludo@gnu.org (Ludovic Courtès)]

Hi Catonano, and apologies for the delay!

Catonano <catonano@gmail.com> skribis:

> From 55b9fab0c6f218b73fdf1804c606a4bdcf2ddda4 Mon Sep 17 00:00:00 2001
> From: humanitiesNerd <catonano@gmail.com>
> Date: Wed, 29 Mar 2017 11:43:55 +0200
> Subject: [PATCH 1/1] gnu: Add 'Debugging Build Failures' subsection to
>  'Invoking guix build'
>
> * doc/guix.texi (Debugging Build Failures): New subsection.

I ended up editing it somewhat and adding cross-references (hope that’s
OK!) and pushed a revised version of this patch as
fc06b15e86d40549dc30097621a2c7c6bcd69f2e (modified text below.)

Thank you!

Ludo’.


When defining a new package (*note Defining Packages::), you will
probably find yourself spending some time debugging and tweaking the
build until it succeeds.  To do that, you need to operate the build
commands yourself in an environment as close as possible to the one the
build daemon uses.

   To that end, the first thing to do is to use the ‘--keep-failed’ or
‘-K’ option of ‘guix build’, which will keep the failed build tree in
‘/tmp’ or whatever directory you specified as ‘TMPDIR’ (*note
‘--keep-failed’: Invoking guix build.).

   From there on, you can ‘cd’ to the failed build tree and source the
‘environment-variables’ file, which contains all the environment
variable definitions that were in place when the build failed.  So let’s
say you’re debugging a build failure in package ‘foo’; a typical session
would look like this:

     $ guix build foo -K
     ... build fails
     $ cd /tmp/guix-build-foo.drv-0
     $ source ./environment-variables
     $ cd foo-1.2

   Now, you can invoke commands as if you were the daemon (almost) and
troubleshoot your build process.

   Sometimes it happens that, for example, a package’s tests pass when
you run them manually but they fail when the daemon runs them.  This can
happen because the daemon runs builds in containers where, unlike in our
environment above, network access is missing, ‘/bin/sh’ does not exist,
etc.  (*note Build Environment Setup::).

   In such cases, you may need to run inspect the build process from
within a container similar to the one the build daemon creates:

     $ guix build -K foo
     ...
     $ cd /tmp/guix-build-foo.drv-0
     $ guix environment -C foo --ad-hoc strace gdb
     [env]# source ./environment-variables
     [env]# cd foo-1.2

   Here, ‘guix environment -C’ creates a container and spawns a new
shell in it (*note Invoking guix environment::).  The ‘--ad-hoc strace
gdb’ part adds the ‘strace’ and ‘gdb’ commands to the container, which
would may find handy while debugging.

   To get closer to a container like that used by the build daemon, we
can remove ‘/bin/sh’:

     [env]# rm /bin/sh

   (Don’t worry, this is harmless: this is all happening in the
throw-away container created by ‘guix environment’.)

   The ‘strace’ command is probably not in the search path, but we can
run:

     [env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check

   In this way, not only you will have reproduced the environment
variables the daemon uses, you will also be running the build process in
a container similar to the one the daemon uses.