Some native compiler related renaming

Some native compiler related renaming

[Andrea Corallo via Emacs development discussions.]

Hi all,

just to mention that as suggested in bug#48025 I've pushed a bunch of
commits to perform the following renamings:

comp-eln-load-path → native-comp-eln-load-path
comp-warning-on-missing-source -> native-comp-warning-on-missing-source
comp-native-driver-options → native-comp-driver-options
comp-async-query-on-exit → native-comp-async-query-on-exit
comp-async-report-warnings-errors -> native-comp-async-report-warnings-errors
comp-async-env-modifier-form → native-comp-async-env-modifier-form
comp-async-all-done-hook → native-comp-async-all-done-hook
comp-async-cu-done-functions → native-comp-async-cu-done-functions
comp-async-jobs-number → native-comp-async-jobs-number
comp-never-optimize-functions → native-comp-never-optimize-functions
comp-bootstrap-deny-list → native-comp-bootstrap-deny-list
comp-always-compile → native-comp-always-compile
comp-verbose -> native-comp-verbose
comp-debug -> native-comp-debug
comp-speed -> native-comp-speed
comp-limple-mode -> native-comp-limple-mode

Hopefully I'm not creating too much breakage.

Regards

  Andrea

Re: Some native compiler related renaming

[Eli Zaretskii]

> Date: Thu, 06 May 2021 15:17:22 +0000
> From:  Andrea Corallo via "Emacs development discussions." <emacs-devel@gnu.org>
> 
> just to mention that as suggested in bug#48025 I've pushed a bunch of
> commits to perform the following renamings:
> 
> comp-eln-load-path → native-comp-eln-load-path
> comp-warning-on-missing-source -> native-comp-warning-on-missing-source
> comp-native-driver-options → native-comp-driver-options
> comp-async-query-on-exit → native-comp-async-query-on-exit
> comp-async-report-warnings-errors -> native-comp-async-report-warnings-errors
> comp-async-env-modifier-form → native-comp-async-env-modifier-form
> comp-async-all-done-hook → native-comp-async-all-done-hook
> comp-async-cu-done-functions → native-comp-async-cu-done-functions
> comp-async-jobs-number → native-comp-async-jobs-number
> comp-never-optimize-functions → native-comp-never-optimize-functions
> comp-bootstrap-deny-list → native-comp-bootstrap-deny-list
> comp-always-compile → native-comp-always-compile
> comp-verbose -> native-comp-verbose
> comp-debug -> native-comp-debug
> comp-speed -> native-comp-speed
> comp-limple-mode -> native-comp-limple-mode

Thanks.

I have now written some documentation of this new feature in the ELisp
manual.  Suggestions for improvements are welcome.  Bonus points for
submitting patches that improve this documentation.

Andrea, if you think some of the stuff in your blog should be in the
docs, please tell which parts do you consider worthy of being in our
manuals or the comments to the code.

Re: Some native compiler related renaming

[Basil L. Contovounesios]

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

Eli Zaretskii <eliz@gnu.org> writes:

> I have now written some documentation of this new feature in the ELisp
> manual.

Thanks!

> Suggestions for improvements are welcome.  Bonus points for submitting
> patches that improve this documentation.

No bonus points for me please, only some nits.  How's this:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Minor-fixes-to-native-compilation-Texinfo.patch --]
[-- Type: text/x-diff, Size: 8283 bytes --]

From e799a7248b40139af63859bac6da68551ae53ce3 Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <contovob@tcd.ie>
Date: Sat, 8 May 2021 15:45:47 +0100
Subject: [PATCH] Minor fixes to native compilation Texinfo

For discussion, see the following thread:
https://lists.gnu.org/r/emacs-devel/2021-05/msg00347.html

* doc/lispref/compile.texi (Native Compilation): Fix grammar in @ref
online label.
(Native-Compilation Functions): Consistently mark LIMPLE as an
@acronym and unhyphenate 'sub-process'.  Fix grammar.
(Native-Compilation Variables): Fix @cindex entry.
* doc/lispref/loading.texi (Library Search): Prefer @file over @samp
to refer to particular types of files (as opposed to particular
affixes when constructing file names).  Follow i.e. with US-style
comma.
---
 doc/lispref/compile.texi | 50 ++++++++++++++++++++--------------------
 doc/lispref/loading.texi | 12 +++++-----
 2 files changed, 31 insertions(+), 31 deletions(-)

diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index f0787795ca..09a3973d64 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -801,13 +801,13 @@ Native Compilation
 
 @cindex native code
   In addition to the byte-compilation, described in @ref{Byte
-Compilation, previous chapter}, Emacs can also optionally compile Lisp
-function definitions into a true compiled code, known as @dfn{native
-code}.  This feature uses the @file{libgccjit} library, which is part
-of the GCC distribution, and requires that Emacs be built with support
-for using that library.  It also requires to have GCC and Binutils
-(the assembler and linker) available on your system for you to be able
-to native-compile Lisp code.
+Compilation, the previous chapter}, Emacs can also optionally compile
+Lisp function definitions into a true compiled code, known as
+@dfn{native code}.  This feature uses the @file{libgccjit} library,
+which is part of the GCC distribution, and requires that Emacs be
+built with support for using that library.  It also requires to have
+GCC and Binutils (the assembler and linker) available on your system
+for you to be able to native-compile Lisp code.
 
 @vindex native-compile@r{, a Lisp feature}
   To determine whether the current Emacs process can produce and load
@@ -857,7 +857,7 @@ Native-Compilation Functions
 @section Native-Compilation Functions
 @cindex native-compilation functions
 
-   Native-Compilation is implemented as side effect of
+   Native-Compilation is implemented as a side effect of
 byte-compilation (@pxref{Byte Compilation}).  Thus, compiling Lisp
 code natively always produces its byte code as well, and therefore all
 the rules and caveats of preparing Lisp code for byte compilation
@@ -875,9 +875,9 @@ Native-Compilation Functions
   Native compilation might produce warning or error messages; these
 are normally recorded in the buffer called
 @file{*Native-compile-Log*}.  In interactive sessions, it uses the
-special LIMPLE mode (@code{native-comp-limple-mode}), which sets up
-@code{font-lock} as appropriate for this log, and is otherwise the
-same as Fundamental mode.  Logging of messages resulting from
+special @acronym{LIMPLE} mode (@code{native-comp-limple-mode}), which
+sets up @code{font-lock} as appropriate for this log, and is otherwise
+the same as Fundamental mode.  Logging of messages resulting from
 native-compilation can be controlled by the @code{native-comp-verbose}
 variable (@pxref{Native-Compilation Variables}).
 
@@ -892,14 +892,14 @@ Native-Compilation Functions
 or a name (a string) of the file which contains the Emacs Lisp source
 code to compile.  If the optional argument @var{output} is provided,
 it must be a string specifying the name of the file to write the
-compiled code.  Otherwise, if @var{function-or-file} is a function or
-a Lisp form, this function returns the compiled object, and if
-@var{function-or-file} is a file name, the function returns the full
-absolute name of the file it created for the compiled code.  The
+compiled code into.  Otherwise, if @var{function-or-file} is a
+function or a Lisp form, this function returns the compiled object,
+and if @var{function-or-file} is a file name, the function returns the
+full absolute name of the file it created for the compiled code.  The
 output file is by default given the @file{.eln} extension.
 
 This function runs the final phase of the native compilation, which
-invokes GCC via @file{libgccjit}, in a separate sub-process, which
+invokes GCC via @file{libgccjit}, in a separate subprocess, which
 invokes the same Emacs executable as the process that called this
 function.
 @end defun
@@ -913,12 +913,12 @@ Native-Compilation Functions
 non-zero status code.
 @end defun
 
-Native compilation can be run entirely asynchronously, in a
-sub-process of the main Emacs process.  This leaves the main Emacs
-process free to use while the compilation runs in the background.
-This is the method used by Emacs to natively-compile any Lisp file or
-byte-compiled Lisp file that is loaded into Emacs, when no
-natively-compiled file for it is available.
+Native compilation can be run entirely asynchronously, in a subprocess
+of the main Emacs process.  This leaves the main Emacs process free to
+use while the compilation runs in the background.  This is the method
+used by Emacs to natively-compile any Lisp file or byte-compiled Lisp
+file that is loaded into Emacs, when no natively-compiled file for it
+is available.
 
 @defun native-compile-async files &optional recursively load selector
 This function compiles the named @var{files} asynchronously.  The
@@ -944,12 +944,12 @@ Native-Compilation Functions
 
 On systems with multiple CPU execution units, when @var{files} names
 more than one file, this function will normally start several
-compilation sub-processes in parallel, under the control of
+compilation subprocesses in parallel, under the control of
 @code{native-comp-async-jobs-number} (@pxref{Native-Compilation
 Variables}).
 @end defun
 
-  The following function allows Lisp program to test whether
+  The following function allows Lisp programs to test whether
 native-compilation is available at runtime.
 
 @defun native-comp-available-p
@@ -962,7 +962,7 @@ Native-Compilation Functions
 
 @node Native-Compilation Variables
 @section Native-Compilation Variables
-@cindex native-compilation variable
+@cindex native-compilation variables
 
   This section documents the variables that control
 native-compilation.
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 4d683da1ad..f1fed7a2da 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -438,21 +438,21 @@ Library Search
 @end deffn
 
   If Emacs was compiled with support for native compilation
-(@pxref{Native Compilation}), then when a @samp{.elc} byte-compiled
+(@pxref{Native Compilation}), then when a @file{.elc} byte-compiled
 file is found by searching @code{load-path}, Emacs will try to look
-for a corresponding @samp{.eln} file holding the corresponding
+for a corresponding @file{.eln} file holding the corresponding
 natively-compiled code.  The natively-compiled files are looked up in
 the directories listed by the @code{native-comp-eln-load-path}.
 
 @vindex comp-native-version-dir
 @defvar native-comp-eln-load-path
 This variable holds a list of directories where Emacs looks for
-natively-compiled @samp{.eln} files.  File names in the list that are
+natively-compiled @file{.eln} files.  File names in the list that are
 not absolute are interpreted as relative to @code{invocation-directory}
 (@pxref{System Environment}).  The last directory in the list is the
-system directory, i.e.@: the directory with @samp{.eln} files
-installed by the Emacs build and installation procedure.  In each of
-the directories in the list, Emacs looks for @samp{.eln} files in a
+system directory, i.e., the directory with @file{.eln} files installed
+by the Emacs build and installation procedure.  In each of the
+directories in the list, Emacs looks for @file{.eln} files in a
 subdirectory whose name is constructed from the Emacs version and an
 8-character hash that depends on the current native-compilation
 @acronym{ABI}; the name of this subdirectory is stored in the variable
-- 
2.30.2


[-- Attachment #3: Type: text/plain, Size: 11 bytes --]


-- 
Basil

Re: Some native compiler related renaming

[Eli Zaretskii]

> From: "Basil L. Contovounesios" <contovob@tcd.ie>
> Cc: Andrea Corallo <akrl@sdf.org>,  emacs-devel@gnu.org
> Date: Sat, 08 May 2021 16:03:50 +0100
> 
> No bonus points for me please, only some nits.  How's this:

Thanks.  I don't agree with some of your changes:

> @@ -875,9 +875,9 @@ Native-Compilation Functions
>    Native compilation might produce warning or error messages; these
>  are normally recorded in the buffer called
>  @file{*Native-compile-Log*}.  In interactive sessions, it uses the
> -special LIMPLE mode (@code{native-comp-limple-mode}), which sets up
> -@code{font-lock} as appropriate for this log, and is otherwise the
> -same as Fundamental mode.  Logging of messages resulting from
> +special @acronym{LIMPLE} mode (@code{native-comp-limple-mode}), which

Here "LIMPLE" shouldn't be an acronym, since it's part of a mode
name.

>    If Emacs was compiled with support for native compilation
> -(@pxref{Native Compilation}), then when a @samp{.elc} byte-compiled
> +(@pxref{Native Compilation}), then when a @file{.elc} byte-compiled
>  file is found by searching @code{load-path}, Emacs will try to look
> -for a corresponding @samp{.eln} file holding the corresponding
> +for a corresponding @file{.eln} file holding the corresponding

The text uses @samp elsewhere for file-name extensions, so I wanted to
be consistent.

> -system directory, i.e.@: the directory with @samp{.eln} files
> -installed by the Emacs build and installation procedure.  In each of
> -the directories in the list, Emacs looks for @samp{.eln} files in a
> +system directory, i.e., the directory with @file{.eln} files installed

I VERY much dislike using a comma after "i.e.".

Re: Some native compiler related renaming

[Basil L. Contovounesios]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: "Basil L. Contovounesios" <contovob@tcd.ie>
>> Cc: Andrea Corallo <akrl@sdf.org>,  emacs-devel@gnu.org
>> Date: Sat, 08 May 2021 16:03:50 +0100
>> 
>> No bonus points for me please, only some nits.  How's this:
>
> Thanks.  I don't agree with some of your changes:

Sure, that's why I wanted to check with you first.

>>    If Emacs was compiled with support for native compilation
>> -(@pxref{Native Compilation}), then when a @samp{.elc} byte-compiled
>> +(@pxref{Native Compilation}), then when a @file{.elc} byte-compiled
>>  file is found by searching @code{load-path}, Emacs will try to look
>> -for a corresponding @samp{.eln} file holding the corresponding
>> +for a corresponding @file{.eln} file holding the corresponding
>
> The text uses @samp elsewhere for file-name extensions, so I wanted to
> be consistent.

Fair enough; it seemed to me like most of those occurrences in the
affected sections were talking about constructing file names.

>> -system directory, i.e.@: the directory with @samp{.eln} files
>> -installed by the Emacs build and installation procedure.  In each of
>> -the directories in the list, Emacs looks for @samp{.eln} files in a
>> +system directory, i.e., the directory with @file{.eln} files installed
>
> I VERY much dislike using a comma after "i.e.".

I do too, but I thought that was the preferred US convention.

Pushed with the objectionable parts removed.

Tiny fixes to recent native compilation docs
bb8b8d717f 2021-05-08 17:53:41 +0100
https://git.sv.gnu.org/cgit/emacs.git/commit/?id=bb8b8d717f91a85ca41de9e82246e6975e1ed719

Thanks,

-- 
Basil

Re: Some native compiler related renaming

[Alan Mackenzie]

Hello, Eli.

On Sat, May 08, 2021 at 16:30:12 +0300, Eli Zaretskii wrote:

[ .... ]

> I have now written some documentation of this new feature [native
> compilation] in the ELisp manual.  Suggestions for improvements are
> welcome.  Bonus points for submitting patches that improve this
> documentation.

Thanks.  This is most welcome.

The function `disassemble' works on natively compiled functions now, as
well as on byte-compiled functions.  Perhaps this should be mentioned
somewhere in the new section about native compilation.  I think the page
"Disassembly" in the Elisp manual might need some radical surgery, to
make it read smoothly for both types of compiled function.

There may be other functions which Andrea has also enhanced to work on
native compiled code.  I found out about disassemble because I needed
it, and I just tried it.

I do not claim any bonus points at this stage.

[ .... ]

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Some native compiler related renaming

[Eli Zaretskii]

> Date: Sat, 8 May 2021 21:28:05 +0000
> Cc: Andrea Corallo <akrl@sdf.org>, emacs-devel@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> The function `disassemble' works on natively compiled functions now, as
> well as on byte-compiled functions.  Perhaps this should be mentioned
> somewhere in the new section about native compilation.  I think the page
> "Disassembly" in the Elisp manual might need some radical surgery, to
> make it read smoothly for both types of compiled function.

That's a good idea, but I'd need some place with the description of
using that for native code, or someone who has experience in doing
that will have to describe that first.  Any pointers?

> There may be other functions which Andrea has also enhanced to work on
> native compiled code.  I found out about disassemble because I needed
> it, and I just tried it.

Specific function names whose descriptions you think need updates for
the native compilation would be welcome.

Re: Some native compiler related renaming

[Andrea Corallo via Emacs development discussions.]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Thu, 06 May 2021 15:17:22 +0000
>> From:  Andrea Corallo via "Emacs development discussions." <emacs-devel@gnu.org>
>> 
>> just to mention that as suggested in bug#48025 I've pushed a bunch of
>> commits to perform the following renamings:
>> 
>> comp-eln-load-path → native-comp-eln-load-path
>> comp-warning-on-missing-source -> native-comp-warning-on-missing-source
>> comp-native-driver-options → native-comp-driver-options
>> comp-async-query-on-exit → native-comp-async-query-on-exit
>> comp-async-report-warnings-errors -> native-comp-async-report-warnings-errors
>> comp-async-env-modifier-form → native-comp-async-env-modifier-form
>> comp-async-all-done-hook → native-comp-async-all-done-hook
>> comp-async-cu-done-functions → native-comp-async-cu-done-functions
>> comp-async-jobs-number → native-comp-async-jobs-number
>> comp-never-optimize-functions → native-comp-never-optimize-functions
>> comp-bootstrap-deny-list → native-comp-bootstrap-deny-list
>> comp-always-compile → native-comp-always-compile
>> comp-verbose -> native-comp-verbose
>> comp-debug -> native-comp-debug
>> comp-speed -> native-comp-speed
>> comp-limple-mode -> native-comp-limple-mode
>
> Thanks.
>
> I have now written some documentation of this new feature in the ELisp
> manual.  Suggestions for improvements are welcome.  Bonus points for
> submitting patches that improve this documentation.
>
> Andrea, if you think some of the stuff in your blog should be in the
> docs, please tell which parts do you consider worthy of being in our
> manuals or the comments to the code.

Hi Eli,

great thanks!

I'll have a look then.

Regards

  Andrea

Re: Some native compiler related renaming

[Andrea Corallo via Emacs development discussions.]

Hi Eli & all,

question: should we rename also `comp-deferred-compilation'? (and
possibly `comp-deferred-compilation-deny-list' too)?

Regards

  Andrea

Re: Some native compiler related renaming

[Eli Zaretskii]

> From: Andrea Corallo <akrl@sdf.org>
> Cc: emacs-devel@gnu.org
> Date: Tue, 11 May 2021 08:40:25 +0000
> 
> Hi Eli & all,
> 
> question: should we rename also `comp-deferred-compilation'? (and
> possibly `comp-deferred-compilation-deny-list' too)?

If we expect downstream distros to stick to the "no *.el files"
policy, then yeah, I guess so.  (I didn't include it in the list I
posted a week ago because I thought no one in their right mind would
want to disable native-compilation, except for debugging special
situations.)

Re: Some native compiler related renaming

[Andrea Corallo via Emacs development discussions.]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Andrea Corallo <akrl@sdf.org>
>> Cc: emacs-devel@gnu.org
>> Date: Tue, 11 May 2021 08:40:25 +0000
>> 
>> Hi Eli & all,
>> 
>> question: should we rename also `comp-deferred-compilation'? (and
>> possibly `comp-deferred-compilation-deny-list' too)?
>
> If we expect downstream distros to stick to the "no *.el files"
> policy, then yeah, I guess so.  (I didn't include it in the list I
> posted a week ago because I thought no one in their right mind would
> want to disable native-compilation, except for debugging special
> situations.)

Not sure what downstream distros will stick to so I did the renaming.
Also the deny list is something that might be useful to some user, and
ATM we have all defcustoms in comp.el with the native- prefix (with the
exception of comp-libgccjit-reproducer that is really a debug thing).

Thanks

  Andrea