guix_mirror_bot pushed a commit to branch master
in repository guix.
commit 65044ffcb0dcca1a464e30ed6d39523b744508bb
Author: Yarl Baudig <[email protected]>
AuthorDate: Mon Nov 16 19:52:28 2026 +0100
doc: contributing: Document installation image hacking
* doc/contributing.texi (Running Guix Before It Is Installed): Add a
subsection documenting how to work on the installation image.
Co-Authored-By: Rutherther <[email protected]>
Change-Id: I5687fa4ab795e8eb71292bd2630115e7841dbce6
Signed-off-by: Ludovic Courtès <[email protected]>
Merges: #12354
---
doc/contributing.texi | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 56 insertions(+)
diff --git a/doc/contributing.texi b/doc/contributing.texi
index cdcc341d76f..401591161fe 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -551,6 +551,62 @@ You can run @command{make} automatically as you work using
to build again each time you update a package file, run
@samp{watchexec -w gnu/packages -- make -j4}.
+@menu
+* Working on the System Installer:: Hack the installation image.
+@end menu
+
+@node Working on the System Installer
+@subsection Working on the System Installer
+
+If you want to build the installation image with your local tree
+checkout and ensure that your changes land in it, please read this
+section.
+
+You can produce an image of the system installer by running a command
+like this one (@pxref{Building the
+Installation Image}):
+
+@example
+./pre-inst-env guix system image -t iso9660 gnu/system/install.scm
+@end example
+
+This will print a message such as:
+
+@example
+Updating channel 'guix' from Git repository at
+'/home/user/projects/guix/'...
+@end example
+
+The installation image uses @code{(current-guix)} for both the system
+itself and the installer program. That means that you will always be on
+the commit you built from when you boot the installer. You can be in
+shell in a TTY, you can be installing the system from the installer,
+both will run the Guix commit you built the installation image from.
+This means you should commit your changes before building the installer
+if you want to ensure the changes will appear.
+
+Still, the image will use the @code{guix} package from @code{(gnu
+packages package-management)} for the new system it creates in the
+installation process---e.g., for @code{guix-service-type}. This means
+that the installed system might not have the changes you made. If you
+need them, make sure to bump the @code{guix} package to one of your
+commits as well. On releases, right after the tagged commit, the
+package is bumped and image built from it to mitigate this issue. The
+image also refers to the package (through the
+@file{gnu/system/examples/bare-bones.tmpl} template) to ensure that the
+installation doesn't have to redownload the package unnecessarily.
+
+This will also print a message such as:
+
+@example
+guix system: warning: channel authentication disabled
+@end example
+
+This happens because authentication of commits is disabled for default
+@code{(current-guix)} because otherwise, you would have to sign those
+commits. There is nothing to worry about, every commits up to yours are
+authenticated.
+
@node The Perfect Setup
@section The Perfect Setup