guix_mirror_bot pushed a commit to branch master
in repository guix.
commit d7234541055f0bc99d00b060a0f073d5c834d2d0
Author: Hugo Buddelmeijer <[email protected]>
AuthorDate: Fri Jun 19 23:40:17 2026 +0200
doc: Improve instructions to minimize unexpected test failures.
* doc/contributing.texi (Building from Git): Suggest `guix shell --pure`
as that is currenlty the only way to make the tests pass on the first run.
(Running the Test Suite): Explain which test failures are expected depending
on each setup.
Change-Id: I3425879dcd2a71c2e3c2fd00b55c819447ac9437
Signed-off-by: Ludovic Courtès <[email protected]>
Modified-by: Ludovic Courtès <[email protected]>
Merges: #9408
---
doc/contributing.texi | 49 ++++++++++++++++++++++++++++++++-----------------
1 file changed, 32 insertions(+), 17 deletions(-)
diff --git a/doc/contributing.texi b/doc/contributing.texi
index 95ba08c508..576aee8a81 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -175,24 +175,16 @@ all the dependencies and appropriate environment
variables are set up to
hack on Guix:
@example
-guix shell -D guix -CPW
+guix shell -D guix --pure
@end example
or even, from within a Git worktree for Guix:
@example
echo $(pwd) >> ~/.config/guix/shell-authorized-directories
-guix shell -CPW
+guix shell --pure
@end example
-If @option{-C} (short for @option{--container}) is not supported on your
-system, try @command{--pure} instead of @option{-CPW}.
-@xref{Invoking guix shell}, for more information on that command.
-
-Most of the test suite runs without an internet connection. The @option{-N}
-(short for @option{--network}) can be added to the @code{guix shell} command
-to run the tests that require internet access.
-
If you are unable to use Guix when building Guix from a checkout, the
following are the required packages in addition to those mentioned in the
installation instructions (@pxref{Requirements}).
@@ -210,7 +202,7 @@ On Guix, other development tools, like @code{strace}, can
be included by
giving them as extra arguments to @command{guix shell}:
@example
-guix shell -D guix -CPW strace
+guix shell --pure -D guix strace
@end example
From there you can generate the build system infrastructure
@@ -261,18 +253,14 @@ right @code{localstatedir} and @code{sysconfdir} values,
which get
recorded in the @code{(guix config)} Guile module.
Finally, you can build Guix and, if you feel so inclined, run the tests
-(@pxref{Running the Test Suite}):
+(depending on how you setup your environment, some tests might fail,
+@pxref{Running the Test Suite}):
@example
make
make check
@end example
-@noindent
-If anything fails, take a look at installation instructions
-(@pxref{Installation}) or send a message to the
-@email{guix-devel@@gnu.org, mailing list}.
-
From there on, you can authenticate all the commits included in your
checkout by running:
@@ -345,6 +333,33 @@ suite, type:
make check
@end example
+Some tests might fail or be skipped, depending on your environment.
+For example, many tests require Internet access to download test
+binaries into the temporary store used for testing.
+
+Assuming you set up your environment with @command{guix shell},
+this is what you can expect:
+
+@table @option
+@item --pure
+all tests should either pass or be skipped. This will also
+set up the test store;
+@item -CPWN
+all tests should either pass or be skipped and this should
+also set up the test store@footnote{At the time of writing, June 2026,
+some tests might fail in a @option{-CPWN} shell; those are
+@url{https://codeberg.org/guix/guix/issues/9381, bugs}.};
+@item -CPW
+all network tests should automatically be skipped, but tests
+that require the test store are run, so those will fail unless the test store
+has been set up during an earlier test run with network access.
+@end table
+
+@quotation Note
+Some tests are skipped for other reasons, for example because they are
+only applicable for a specific system.
+@end quotation
+
Test cases can run in parallel: you can use the @code{-j} option of
GNU@tie{}make to speed things up. The first run may take a few minutes
on a recent machine; subsequent runs will be faster because the store
