From f6d060b39a02da14aa1763bb688cb2e048f0c666 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Tue, 14 May 2024 08:51:13 +0300 Subject: [PATCH] ; Fix documentation of recently-installed changes * lisp/emacs-lisp/bytecomp.el (compilation-safety): Doc fix. * etc/NEWS: Fix wording of the 'compilation-safety' entry. * doc/lispref/functions.texi (Declare Form): Fix cross-reference and wording. * doc/lispref/compile.texi (Native-Compilation Variables): Add the missing @anchor. Fix wording. --- doc/lispref/compile.texi | 18 ++++++++++-------- doc/lispref/functions.texi | 9 +++++---- etc/NEWS | 8 +++++--- lisp/emacs-lisp/bytecomp.el | 11 +++++++---- 4 files changed, 27 insertions(+), 19 deletions(-) diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index f8f1242586e..9f93fb4a981 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -987,21 +987,23 @@ form, @pxref{Declare Form}.) The default value is 2. @end defopt +@anchor{compilation-safety} @defopt compilation-safety -This variable specifies the safetyness level used for the code emitted -native code. The value of compilation-safety should be a number between -zero and one with the following meaning: +This variable specifies the safety level to be used for the emitted +native code. The value should be a number, either 0 or 1 with the +following meanings: @table @asis @item 0 -Emitted code can misbehave or crash Emacs if function declarations are -not correct and the function is native compiled. +Emitted code can misbehave (up to even crashing Emacs) if a function's +declaration does not describe correctly what the function does or how it +is called, and the function is natively compiled. @item 1 -Emitted code is generated in a safe matter even if function are -miss-declared." +Emitted code must be generated in a safe manner even if functions are +mis-declared. @end table -This can be controlled at function granularity as well by using the +This can also be controlled at a function granularity, by using the @code{safety} @code{declare} form, @pxref{Declare Form}. @end defopt diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 9d4ecd8da25..deca99960c7 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -2761,10 +2761,11 @@ argument of type @var{string} and return one of the symbols For description of additional types, see @ref{Lisp Data Types}). Declaring a function with an incorrect type produces undefined behavior -and could lead to unexpected results or might even crash Emacs when code -is native-compiled and loaded if compiled with @ref{compilation-safety} -0. Note also that when redefining (or advising) a type declared -function the replacement should respect the original signature to avoid +and could lead to unexpected results or might even crash Emacs when +natively-compiled code is loaded, if it was compiled with +@code{compilation-safety} level of zero (@pxref{compilation-safety}). +Note also that when redefining (or advising) a type-declared function, +the replacement should respect the original signature to avoid such undefined behavior. @item no-font-lock-keyword diff --git a/etc/NEWS b/etc/NEWS index 5f131386a43..5ecc385fa5b 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1986,9 +1986,11 @@ unibyte string. * Lisp Changes in Emacs 30.1 +++ -** New 'compilation-safety' compilation parameter. -It's now possible to use the safety parameter to control how safe is -code generated by the native compiler. +** New user option 'compilation-safety' to control safety of native code. +It's now possible to control how safe is the code generated by native +compilation, by customizing this user option. It is also possible to +control this at function granularity by using the new 'safety' parameter +in the function's 'declare' form. ** New types 'closure' and 'interpreted-function'. 'interpreted-function' is the new type used for interpreted functions, diff --git a/lisp/emacs-lisp/bytecomp.el b/lisp/emacs-lisp/bytecomp.el index 3e7674eeef6..12b45f9f5b8 100644 --- a/lisp/emacs-lisp/bytecomp.el +++ b/lisp/emacs-lisp/bytecomp.el @@ -138,11 +138,14 @@ :group 'lisp) (defcustom compilation-safety 1 - "Safety level for compilation. + "Safety level for generated compiled code. Possible values are: -0 emitted code can misbehave or crash Emacs if function declarations are not -correct. -1 emitted code is generated in a safe matter even if function are miss-declared." + 0 - emitted code can misbehave, even crash Emacs, if declarations of + functions do not correctly describe their actual behavior; + 1 - emitted code is to be generated in a safe manner, even if functions + are mis-declared. + +This currently affects only code produced by native-compilation." :type 'integer :safe #'integerp :version "30.1")