From 55b9fab0c6f218b73fdf1804c606a4bdcf2ddda4 Mon Sep 17 00:00:00 2001
From: humanitiesNerd <address@hidden>
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.
---
 doc/guix.texi | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 70 insertions(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 57595b95e..418c0c844 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -34,7 +34,8 @@ Copyright @copyright{} 2017 Clément address@hidden
 Copyright @copyright{} 2017 Mathieu address@hidden
 Copyright @copyright{} 2017 Federico address@hidden
 Copyright @copyright{} 2017 Carlo address@hidden
-Copyright @copyright{} 2017 Thomas Danckaert
+Copyright @copyright{} 2017 Thomas address@hidden
+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
@@ -4729,6 +4730,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
@@ -5141,6 +5143,73 @@ https://hydra.gnu.org/log/@dots{}-gdb-7.10
 You can freely access a huge library of build logs!
 @end table
 
address@hidden Debugging Build Failures
address@hidden Debugging Build Failures
+
+When defining a new package, you will probably find yourself
+spending some time debugging and tweaking the build.
+orr example if the Makefile needs to
+be modified, or some test-cases adjusted.
+
+So you need to operate the build commands yourself in an
+environment as close as possible to the one that the daemon uses.
+
+Say you're packaging foo-1.2 and the build is failing.
+
+The option @option{-K} will keep the (failed) build folder in /tmp.
+
+So you can cd in
+
address@hidden
+cd /tmp/guix-build-foo.drv-0
address@hidden example
+
+Here, you will find an ``environment-variables'' file
+containing all the environment variables the daemon is using.
+
address@hidden
+source environment-variables
+cd foo-1.2
address@hidden example
+
+Now, you can call commands as if you were the daemon
+(almost) and troubleshoot your build process.
+
+Sometimes it happens that, for example, the tests pass
+when you run them manually and fail when the daemon runs them.
+
+In such cases you need to run them in a container
+like the daemon does.
+
address@hidden
+  guix build -K foo
+  # build fails…
+  cd /tmp/guix-build-foo.drv-0
address@hidden example
+
+this is equal to the previous example.
+
+Now:
+
address@hidden
+  guix environment -C foo --ad-hoc strace gdb
+
address@hidden example
+
+here, the @option{-C} option creates a container
+and runs your process in it.
+Note the inclusion of @command{strace} and @command{gdb}
+
address@hidden
+  rm /bin/sh           # to be really like in the guix-daemon environment
+  source ./environment-variables
+  cd foo-1.2
+  $GUIX_ENVIRONMENT/bin/strace -f -o log make check
address@hidden 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}
-- 
2.12.0