procyberian/emacs
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add some 'compilation-safety' documentation

Browse source 
* lisp/emacs-lisp/bytecomp.el (compilation-safety): Better doc.
* doc/lispref/functions.texi (Declare Form): Add 'safety'.
* doc/lispref/compile.texi (Native-Compilation Variables): Add
'compilation-safety'.
This commit is contained in:
Andrea Corallo 2024-05-04 08:55:56 +02:00
parent 9e4e6d0fc9
commit 04e7078d5e
3 changed files with 33 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

18
doc/lispref/compile.texi
View file

@ -987,6 +987,24 @@ form, @pxref{Declare Form}.)
The default value is 2. The default value is 2.
@end defopt @end defopt
@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:
@table @asis
@item 0
Emitted code can misbehave or crash Emacs if function declarations are
not correct and the function is native compiled.
@item 1
Emitted code is generated in a safe matter even if function are
miss-declared."
@end table
This can be controlled at function granularity as well by using the
@code{safety} @code{declare} form, @pxref{Declare Form}.
@end defopt
@defopt native-comp-debug @defopt native-comp-debug
This variable specifies the level of debugging information produced by This variable specifies the level of debugging information produced by
native-compilation. Its value should be a number between zero and 3, native-compilation. Its value should be a number between zero and 3,

13
doc/lispref/functions.texi
View file

@ -2709,6 +2709,12 @@ native code emitted for the function. In particular, if @var{n} is
@minus{}1, native compilation of the function will emit bytecode @minus{}1, native compilation of the function will emit bytecode
instead of native code for the function. instead of native code for the function.
@item (safety @var{n})
Specify the value of @code{compilation-safety} in effect for this
function. This allows function-level control of the safety level used
for the code emitted for the function (@pxref{Native-Compilation
Variables}).
@item (type @var{type}) @item (type @var{type})
Declare @var{type} to be the type of this function. This is used for Declare @var{type} to be the type of this function. This is used for
documentation by @code{describe-function}. Also it can be used by the documentation by @code{describe-function}. Also it can be used by the
@ -2756,9 +2762,10 @@ For description of additional types, see @ref{Lisp Data Types}).
Declaring a function with an incorrect type produces undefined behavior Declaring a function with an incorrect type produces undefined behavior
and could lead to unexpected results or might even crash Emacs when code and could lead to unexpected results or might even crash Emacs when code
is native-compiled and loaded. Note also that when redefining (or is native-compiled and loaded if compiled with @ref{compilation-safety}
advising) a type declared function the replacement should respect the 0. Note also that when redefining (or advising) a type declared
original signature to avoid undefined behavior. function the replacement should respect the original signature to avoid
undefined behavior.
@item no-font-lock-keyword @item no-font-lock-keyword
This is valid for macros only. Macros with this declaration are This is valid for macros only. Macros with this declaration are

6
lisp/emacs-lisp/bytecomp.el
View file

@ -138,7 +138,11 @@
:group 'lisp) :group 'lisp)
(defcustom compilation-safety 1 (defcustom compilation-safety 1
"Safety level." "Safety level for compilation.
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."
:type 'integer :type 'integer
:safe #'integerp :safe #'integerp
:version "30.1") :version "30.1")