bug#71730: Manual section 2.6.5 on Emacs Packages needs updating regarding native-compilation

bug#71730: Manual section 2.6.5 on Emacs Packages needs updating regarding native-compilation

[Adam Porter]

Hello,

I just noticed that the Guix manual at
<https://guix.gnu.org/manual/en/guix.html>, in section 2.6.5, says:

> Note: Emacs can now compile packages natively. Under the default
> configuration, this means that Emacs packages will now be
> just-in-time (JIT) compiled as you use them, and the results stored
> in a subdirectory of your user-emacs-directory.
> 
> Furthermore, the build system for Emacs packages transparently
> supports native compilation, but note, that emacs-minimal—the default
> Emacs for building packages—has been configured without native
> compilation. To natively compile your emacs packages ahead of time,
> use a transformation like --with-input=emacs-minimal=emacs.

Given the patch that disables such JIT compilation, discussed in 
bug#71725, seems to disable that, it would seem that this section in the 
manual should be updated accordingly.  (Or, ideally, that behavior would 
be restored for packages installed outside of Guix, but that's what 
bug#71725 is about.)

Thanks,
Adam

bug#71730: [PATCH] doc: Update note on Emacs packages.

[Liliana Marie Prikler]

* doc/guix.texi ("Emacs packages"): Expand note to talk about differences
between native compilation upstream and as used in Guix.
---
 doc/guix.texi | 31 ++++++++++++++++++++++---------
 1 file changed, 22 insertions(+), 9 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 9bbf85e32b..67c5cef757 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -1878,15 +1878,28 @@ Application Setup
 File,,, emacs, The GNU Emacs Manual}).
 
 @quotation Note
-Emacs can now compile packages natively.  Under the default
-configuration, this means that Emacs packages will now be
-just-in-time (JIT) compiled as you use them, and the results
-stored in a subdirectory of your @code{user-emacs-directory}.
-
-Furthermore, the build system for Emacs packages transparently
-supports native compilation, but note, that
-@code{emacs-minimal}---the default Emacs for building
-packages---has been configured without native compilation.
+Most Emacs variants are now capable of doing native compilation.
+The approach taken by Guix Emacs however differs greatly
+from the approach taken upstream.
+
+Upstream Emacs compiles packages just-in-time and typically places
+shared object files  in a special folder within your
+@code{user-emacs-directory}.
+These shared objects within said folder are organized in a
+flat hierarchy, and their file names contain two hashes to
+verify the original file name and contents of the source code.
+
+Guix Emacs on the other hand prefers to compile packages ahead-of-time.
+Shared objects retain much of the original file name and no hashes
+are added to verify the original file name or the contents of the file.
+Crucially, this allows Guix Emacs and packages built against it
+to be grafted (@pxref{Security Updates, grafts}), but at the same time,
+Guix Emacs lacks the hash-based verification of source code baked
+into upstream Emacs.  As this naming schema is trivial to exploit,
+we disable just-in-time compilation.
+
+Further note, that @code{emacs-minimal}---the default Emacs
+for building packages---has been configured without native compilation.
 To natively compile your emacs packages ahead of time, use a
 transformation like @option{--with-input=emacs-minimal=emacs}.
 @end quotation

base-commit: 11c403ec0554be0e1c888ec6f8147a232e09adbd
-- 
2.45.1

bug#71730: [PATCH] doc: Update note on Emacs packages.

[Adam Porter]

Hi Liliana,

On 6/23/24 08:17, Liliana Marie Prikler wrote:
> * doc/guix.texi ("Emacs packages"): Expand note to talk about differences
> between native compilation upstream and as used in Guix.
> ---
>   doc/guix.texi | 31 ++++++++++++++++++++++---------
>   1 file changed, 22 insertions(+), 9 deletions(-)

Thanks, I think that is a great addition to the manual.

--Adam

bug#71730: [PATCH] doc: Update note on Emacs packages.

[Liliana Marie Prikler]

Am Donnerstag, dem 27.06.2024 um 09:00 -0500 schrieb Adam Porter:
> Hi Liliana,
> 
> On 6/23/24 08:17, Liliana Marie Prikler wrote:
> > * doc/guix.texi ("Emacs packages"): Expand note to talk about
> > differences
> > between native compilation upstream and as used in Guix.
> > ---
> >   doc/guix.texi | 31 ++++++++++++++++++++++---------
> >   1 file changed, 22 insertions(+), 9 deletions(-)
> 
> Thanks, I think that is a great addition to the manual.
Pushed now.

Cheers