summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/guix.texi85
1 files changed, 83 insertions, 2 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index 9b2fe3fdb8..0054022fb9 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -34,7 +34,8 @@ Copyright @copyright{} 2017 Clément Lassieur@*
Copyright @copyright{} 2017 Mathieu Othacehe@*
Copyright @copyright{} 2017 Federico Beffa@*
Copyright @copyright{} 2017 Carlo Zancanaro@*
-Copyright @copyright{} 2017 Thomas Danckaert
+Copyright @copyright{} 2017 Thomas Danckaert@*
+Copyright @copyright{} 2017 humanitiesNerd
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -2879,7 +2880,8 @@ unavailable to the build process, possibly leading to a build failure.
Once a package definition is in place, the
package may actually be built using the @code{guix build} command-line
-tool (@pxref{Invoking guix build}). You can easily jump back to the
+tool (@pxref{Invoking guix build}), troubleshooting any build failures
+you encounter (@pxref{Debugging Build Failures}). You can easily jump back to the
package definition using the @command{guix edit} command
(@pxref{Invoking guix edit}).
@xref{Packaging Guidelines}, for
@@ -4832,6 +4834,7 @@ described in the subsections below.
* Common Build Options:: Build options for most commands.
* Package Transformation Options:: Creating variants of packages.
* Additional Build Options:: Options specific to 'guix build'.
+* Debugging Build Failures:: Real life packaging experience
@end menu
@node Common Build Options
@@ -4857,6 +4860,8 @@ the command-line tools.
Keep the build tree of failed builds. Thus, if a build fails, its build
tree is kept under @file{/tmp}, in a directory whose name is shown at
the end of the build log. This is useful when debugging build issues.
+@xref{Debugging Build Failures}, for tips and tricks on how to debug
+build issues.
@item --keep-going
@itemx -k
@@ -5244,6 +5249,82 @@ https://hydra.gnu.org/log/@dots{}-gdb-7.10
You can freely access a huge library of build logs!
@end table
+@node Debugging Build Failures
+@subsection Debugging Build Failures
+
+@cindex build failures, debugging
+When defining a new package (@pxref{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 @option{--keep-failed}
+or @option{-K} option of @command{guix build}, which will keep the
+failed build tree in @file{/tmp} or whatever directory you specified as
+@code{TMPDIR} (@pxref{Invoking guix build, @code{--keep-failed}}).
+
+From there on, you can @command{cd} to the failed build tree and source
+the @file{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
+@code{foo}; a typical session would look like this:
+
+@example
+$ guix build foo -K
+@dots{} @i{build fails}
+$ cd /tmp/guix-build-foo.drv-0
+$ source ./environment-variables
+$ cd foo-1.2
+@end example
+
+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, @file{/bin/sh} does not
+exist, etc. (@pxref{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:
+
+@example
+$ guix build -K foo
+@dots{}
+$ cd /tmp/guix-build-foo.drv-0
+$ guix environment -C foo --ad-hoc strace gdb
+[env]# source ./environment-variables
+[env]# cd foo-1.2
+@end example
+
+Here, @command{guix environment -C} creates a container and spawns a new
+shell in it (@pxref{Invoking guix environment}). The @command{--ad-hoc
+strace gdb} part adds the @command{strace} and @command{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 @file{/bin/sh}:
+
+@example
+[env]# rm /bin/sh
+@end example
+
+(Don't worry, this is harmless: this is all happening in the throw-away
+container created by @command{guix environment}.)
+
+The @command{strace} command is probably not in the search path, but we
+can run:
+
+@example
+[env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check
+@end example
+
+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.
+
@node Invoking guix edit
@section Invoking @command{guix edit}