From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: "Basil L. Contovounesios" Newsgroups: gmane.emacs.devel Subject: Re: Some native compiler related renaming Date: Sat, 08 May 2021 16:03:50 +0100 Message-ID: <87bl9lmfmx.fsf@tcd.ie> References: <83bl9l9wuz.fsf@gnu.org> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="17302"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) Cc: emacs-devel@gnu.org, Andrea Corallo To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat May 08 17:04:58 2021 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1lfOVm-0004KK-CK for ged-emacs-devel@m.gmane-mx.org; Sat, 08 May 2021 17:04:58 +0200 Original-Received: from localhost ([::1]:58356 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lfOVk-0002Zz-PE for ged-emacs-devel@m.gmane-mx.org; Sat, 08 May 2021 11:04:56 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:47104) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lfOUo-0001pC-S8 for emacs-devel@gnu.org; Sat, 08 May 2021 11:03:58 -0400 Original-Received: from mail-wr1-x429.google.com ([2a00:1450:4864:20::429]:34543) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1lfOUm-00081B-Ex for emacs-devel@gnu.org; Sat, 08 May 2021 11:03:58 -0400 Original-Received: by mail-wr1-x429.google.com with SMTP id t18so12118858wry.1 for ; Sat, 08 May 2021 08:03:53 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=tcd.ie; s=google21; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version; bh=jGXKLqqPB24tTQDA3+CJyg4q6EHaSJkcjW2n4V2UZFQ=; b=dfgwL8pX4bymtVFg6PbvT05bICPOwEg43ffRkHPDug2tp+gVpTYBKL2xLQvrnA5iut V6UBxd4NRMGGDIesX7OWsfpObnAb5GqSSJAo6Kbt2+7HOo89SIIdNAnwbhdJEe2yt+DB hV8pQ2FpqhD7NJvWtGiK87zuN3DGHz30nZetQ2Xq1sosH7g+depXWjXMMGRtWDJ+zDxU c1kpDAyw2srmVxyAi7EfB/2+nU6k+gf9pPGacmJsAH5UwhUgzMpU+Ee3rIeccurkNR8z yQAk29zS8emtt7/0FmH8XYGv8UV6kmGKeVPGiAl/dd11mg8/XD5vR/4c7mGWr19fCfTm JcPw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version; bh=jGXKLqqPB24tTQDA3+CJyg4q6EHaSJkcjW2n4V2UZFQ=; b=VLh0z9hrySyKlY9Ii6mGsGD6xf9gc8mNjTdVTjf+35iMJQPOVMR8iJL3nqyiCC1RHK 0Zx5eQv64dCziDTUP5w37Yi0qMOOy3f8nuzJg2XGZo9f3gqbhjo8dKWTKfmZsq/KGKi5 0U+xcLuUkZkPKZAYA4Fn207pRVPUFzB+Z6ZaKjhscXxo3pDdElxT3X+shcve5cKhue0C PmtH4W3K5ajCFxIG8z0CtfJPnq8P0V/WFtV6Wpd+rK8QcfzMbOJRkAgFObUHSSOKoEU5 vGP+W55R0ba52hF+J498JTvMMBsfcQU1rHJCoHrzGObDXmZIaFliBtejm/sYL3pReIPR twkw== X-Gm-Message-State: AOAM532Ruplx+6rWk0+VEWt0iCxfL9mBDGVkHpdIseyfhaAotii03AfK LHkaehuzWzob6Wf44GrQUdy4Kw== X-Google-Smtp-Source: ABdhPJzYDUMrKjkCvmJ2YkJ3JEO7pHd+s0GC8zIgEi6JHBCxM/0gYbDcFLA8oCOIbPxeQjOh6nvUGA== X-Received: by 2002:adf:ee83:: with SMTP id b3mr19228570wro.329.1620486232418; Sat, 08 May 2021 08:03:52 -0700 (PDT) Original-Received: from localhost ([2a02:8084:20e2:c380:d15:339e:aa10:60f1]) by smtp.gmail.com with ESMTPSA id w25sm11124961wmk.39.2021.05.08.08.03.51 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 08 May 2021 08:03:51 -0700 (PDT) In-Reply-To: <83bl9l9wuz.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 08 May 2021 16:30:12 +0300") Received-SPF: pass client-ip=2a00:1450:4864:20::429; envelope-from=contovob@tcd.ie; helo=mail-wr1-x429.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:269051 Archived-At: --=-=-= Content-Type: text/plain Eli Zaretskii 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: --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=0001-Minor-fixes-to-native-compilation-Texinfo.patch >From e799a7248b40139af63859bac6da68551ae53ce3 Mon Sep 17 00:00:00 2001 From: "Basil L. Contovounesios" 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 --=-=-= Content-Type: text/plain -- Basil --=-=-=--