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

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

[Catonano]

[-- Attachment #1.1: Type: text/plain, Size: 313 bytes --]

This is my first attempt at editing the manual

The line in the git log is completely made up, I couldn't find an example
of logging edits to the manual

I managed to compile it without warning and errors and I even managed to
see it rendered in html (thanks ng0 !!)

Also, I'm not sure about the language style.

[-- Attachment #1.2: Type: text/html, Size: 398 bytes --]

[-- Attachment #2: series.patch --]
[-- Type: text/x-patch, Size: 3467 bytes --]

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.
---
 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 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
@@ -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
 
+@node Debugging Build Failures
+@subsection 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
+
+@example
+cd /tmp/guix-build-foo.drv-0
+@end example
+
+Here, you will find an ``environment-variables'' file
+containing all the environment variables the daemon is using.
+
+@example
+source environment-variables
+cd foo-1.2
+@end 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.
+
+@example
+  guix build -K foo
+  # build fails…
+  cd /tmp/guix-build-foo.drv-0
+@end example
+
+this is equal to the previous example.
+
+Now:
+
+@example
+  guix environment -C foo --ad-hoc strace gdb
+
+@end example
+
+here, the @option{-C} option creates a container
+and runs your process in it.
+Note the inclusion of @command{strace} and @command{gdb}
+
+@example
+  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
+@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}
-- 
2.12.0

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

[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.

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

[Catonano]

[-- Attachment #1: Type: text/plain, Size: 729 bytes --]

2017-05-03 23:53 GMT+02:00 Ludovic Courtès <ludo@gnu.org>:

> 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!
>

Thanks !

[-- Attachment #2: Type: text/html, Size: 1215 bytes --]