bug#68505: [PATCH v2] Add more detailed instructions into the HACKING file.

bug#68505: [PATCH v2] Add more detailed instructions into the HACKING file.

[Tomas Volf]

Until now, the ./meta/guile was not mentioned anywhere, and therefore it
was not obvious how to run the locally compiled Guile without installing
it.

While modifying the file, I took the liberty to also mention a bit about
compiling Guile using Guix.

Finally, the header lines where cleaned up, ensuring all of them end at
70 and have a leading space.

* HACKING (Hacking It Yourself): Add Guix instructions.  Add a note
about meta/guile script.
(Sample GDB Initialization File),
(Naming conventions): Clean up the header line.
---
v2:
Add note regarding JIT and GNU Hurd.  Add note regarding -fexcess-precision.
Add --disable-static and explain it.

Previous discussion happened on the mailing list.

 HACKING | 38 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 36 insertions(+), 2 deletions(-)

diff --git a/HACKING b/HACKING
index 387643bf7..5926fb275 100644
--- a/HACKING
+++ b/HACKING
@@ -26,6 +26,40 @@ http://www.gnu.org/software/guile/mail/mail.html for more info.
 
 Hacking It Yourself ==================================================
 
+You can spawn a shell with all the required dependencies using GNU Guix
+by running the following command:
+
+    guix shell -D -f guix.scm --pure
+
+In this way, you can effortlessly compile Guile from the Git checkout
+with just these three lines:
+
+    guix shell -D -f guix.scm --pure -- ./autogen.sh
+    guix shell -D -f guix.scm --pure -- ./configure \
+    	 --enable-mini-gmp --disable-static
+    guix shell -D -f guix.scm --pure -- make
+
+Disabling of the static libraries is optional, but it does speed up the
+builds, and you are unlikely to need them for local development.
+
+  Note: Currently JIT causes Guile to crash in obscure ways on GNU Hurd,
+        so on that platform you want to also pass the --disable-jit flag
+        to the configure script.
+
+  Note: On any i*86 architecture, you also need to pass in the compiler
+        flag -fexcess-precision=standard in order to get the test suite
+        to pass.  That can be done by passing an additional argument to
+        the configure script:
+	  CFLAGS='-g -O2 -fexcess-precision=standard'
+
+Once that finishes, you can execute your newly compiled Guile using the
+./meta/guile script:
+
+    $ ./meta/guile -v | head -n1
+    guile (GNU Guile) 3.0.9.139-d7cf5-dirty
+
+For more manual approach, read on.
+
 When Guile is obtained from Git, a few extra steps must be taken
 before the usual configure, make, make install.  You will need to have
 up-to-date versions of the tools as listed below, correctly installed.
@@ -73,7 +107,7 @@ Here is the authoritative list of tool/version/platform tuples that
 have been known to cause problems, and a short description of the problem.
 
 
-Sample GDB Initialization File=========================================
+Sample GDB Initialization File =======================================
 
 In GDB, you probably want to load the gdbinit file included with Guile,
 which defines a number of GDB helpers to inspect Scheme values.
@@ -215,7 +249,7 @@ The goal is to reduce (and over time, eliminate) spurious diffs.
 For Emacs users:
   (add-hook 'before-save-hook 'delete-trailing-whitespace)
 
-Naming conventions =================================================
+Naming conventions ===================================================
 
 We use certain naming conventions to structure the considerable number
 of global identifiers.  All identifiers should be either all lower
-- 
2.41.0

bug#68505: [PATCH v2] Add more detailed instructions into the HACKING file.

[Ludovic Courtès]

Hi,

Tomas Volf <~@wolfsden.cz> skribis:

> Until now, the ./meta/guile was not mentioned anywhere, and therefore it
> was not obvious how to run the locally compiled Guile without installing
> it.
>
> While modifying the file, I took the liberty to also mention a bit about
> compiling Guile using Guix.
>
> Finally, the header lines where cleaned up, ensuring all of them end at
> 70 and have a leading space.
>
> * HACKING (Hacking It Yourself): Add Guix instructions.  Add a note
> about meta/guile script.
> (Sample GDB Initialization File),
> (Naming conventions): Clean up the header line.
> ---
> v2:
> Add note regarding JIT and GNU Hurd.  Add note regarding -fexcess-precision.
> Add --disable-static and explain it.

Much welcome addition!

> +You can spawn a shell with all the required dependencies using GNU Guix
> +by running the following command:
> +
> +    guix shell -D -f guix.scm --pure

I would suggest running:

  guix shell -CP

(Currently ‘README’ suggests ‘guix shell’.)

The rationale is: it’s shorter, using a container avoids interference,
and ‘-P’ works well with ‘config.cache’ & co. (because the cached file
names then are $HOME/.guix-profile/…).

WDYT?

Thanks,
Ludo’.

bug#68505: [PATCH v3] Add more detailed instructions into the HACKING file.

[Tomas Volf]

Until now, the ./meta/guile was not mentioned anywhere, and therefore it
was not obvious how to run the locally compiled Guile without installing
it.

While modifying the file, I took the liberty to also mention a bit about
compiling Guile using Guix.

Finally, the header lines where cleaned up, ensuring all of them end at
70 and have a leading space.

* HACKING (Hacking It Yourself): Add Guix instructions.  Add a note
about meta/guile script.
(Sample GDB Initialization File),
(Naming conventions): Clean up the header line.
---
v2:
Add note regarding JIT and GNU Hurd.  Add note regarding -fexcess-precision.
Add --disable-static and explain it.

v3:
Use -CP instead of --pure.

 HACKING | 38 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 36 insertions(+), 2 deletions(-)

diff --git a/HACKING b/HACKING
index 387643bf7..94fba199c 100644
--- a/HACKING
+++ b/HACKING
@@ -26,6 +26,40 @@ http://www.gnu.org/software/guile/mail/mail.html for more info.

 Hacking It Yourself ==================================================

+You can spawn a shell with all the required dependencies using GNU Guix
+by running the following command:
+
+    guix shell -D -f guix.scm --pure
+
+In this way, you can effortlessly compile Guile from the Git checkout
+with just these three lines:
+
+    guix shell -CP -D -f guix.scm -- ./autogen.sh
+    guix shell -CP -D -f guix.scm -- ./configure \
+    	 --enable-mini-gmp --disable-static
+    guix shell -CP -D -f guix.scm -- make
+
+Disabling of the static libraries is optional, but it does speed up the
+builds, and you are unlikely to need them for local development.
+
+  Note: Currently JIT causes Guile to crash in obscure ways on GNU Hurd,
+        so on that platform you want to also pass the --disable-jit flag
+        to the configure script.
+
+  Note: On any i*86 architecture, you also need to pass in the compiler
+        flag -fexcess-precision=standard in order to get the test suite
+        to pass.  That can be done by passing an additional argument to
+        the configure script:
+	  CFLAGS='-g -O2 -fexcess-precision=standard'
+
+Once that finishes, you can execute your newly compiled Guile using the
+./meta/guile script:
+
+    $ guix shell -CP -D -f guix.scm -- ./meta/guile -v | head -n1
+    guile (GNU Guile) 3.0.9.139-d7cf5-dirty
+
+For more manual approach, read on.
+
 When Guile is obtained from Git, a few extra steps must be taken
 before the usual configure, make, make install.  You will need to have
 up-to-date versions of the tools as listed below, correctly installed.
@@ -73,7 +107,7 @@ Here is the authoritative list of tool/version/platform tuples that
 have been known to cause problems, and a short description of the problem.


-Sample GDB Initialization File=========================================
+Sample GDB Initialization File =======================================

 In GDB, you probably want to load the gdbinit file included with Guile,
 which defines a number of GDB helpers to inspect Scheme values.
@@ -215,7 +249,7 @@ The goal is to reduce (and over time, eliminate) spurious diffs.
 For Emacs users:
   (add-hook 'before-save-hook 'delete-trailing-whitespace)

-Naming conventions =================================================
+Naming conventions ===================================================

 We use certain naming conventions to structure the considerable number
 of global identifiers.  All identifiers should be either all lower
--
2.41.0

bug#68505: [PATCH v2] Add more detailed instructions into the HACKING file.

[Tomas Volf]

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

Thank you for the review.

On 2024-01-24 11:18:27 +0100, Ludovic Courtès wrote:
> > +You can spawn a shell with all the required dependencies using GNU Guix
> > +by running the following command:
> > +
> > +    guix shell -D -f guix.scm --pure
>
> I would suggest running:
>
>   guix shell -CP
>
> (Currently ‘README’ suggests ‘guix shell’.)
>
> The rationale is: it’s shorter, using a container avoids interference,
> and ‘-P’ works well with ‘config.cache’ & co. (because the cached file
> names then are $HOME/.guix-profile/…).
>
> WDYT?

Modified as agreed on irc.  I am not convinced on the -P, but I defer to your
judgment on this.

Have a nice day,
Tomas Volf

--
There are only two hard things in Computer Science:
cache invalidation, naming things and off-by-one errors.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

bug#68505: [PATCH v2] Add more detailed instructions into the HACKING file.

[Ludovic Courtès]

Tomas Volf <~@wolfsden.cz> skribis:

> Until now, the ./meta/guile was not mentioned anywhere, and therefore it
> was not obvious how to run the locally compiled Guile without installing
> it.
>
> While modifying the file, I took the liberty to also mention a bit about
> compiling Guile using Guix.
>
> Finally, the header lines where cleaned up, ensuring all of them end at
> 70 and have a leading space.
>
> * HACKING (Hacking It Yourself): Add Guix instructions.  Add a note
> about meta/guile script.
> (Sample GDB Initialization File),
> (Naming conventions): Clean up the header line.

Applied, thanks!