[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
scratch/comp-safety2 bf3a49d56fc 3/4: Add some 'compilation-safety' docu
From: |
Andrea Corallo |
Subject: |
scratch/comp-safety2 bf3a49d56fc 3/4: Add some 'compilation-safety' documentation |
Date: |
Fri, 10 May 2024 13:55:36 -0400 (EDT) |
branch: scratch/comp-safety2
commit bf3a49d56fc4cdc92be50c79f41cfd5d97ff5dc6
Author: Andrea Corallo <acorallo@gnu.org>
Commit: Andrea Corallo <acorallo@gnu.org>
Add some 'compilation-safety' documentation
* lisp/emacs-lisp/bytecomp.el (compilation-safety): Better doc.
* lisp/emacs-lisp/comp.el (comp--type-relax-alist): Likewise.
* doc/lispref/functions.texi (Declare Form): Add 'safety'.
* doc/lispref/compile.texi (Native-Compilation Variables): Add
'compilation-safety'.
---
doc/lispref/compile.texi | 18 ++++++++++++++++++
doc/lispref/functions.texi | 13 ++++++++++---
lisp/emacs-lisp/bytecomp.el | 5 ++++-
3 files changed, 32 insertions(+), 4 deletions(-)
diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 19451f31740..f8f1242586e 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -987,6 +987,24 @@ form, @pxref{Declare Form}.)
The default value is 2.
@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
This variable specifies the level of debugging information produced by
native-compilation. Its value should be a number between zero and 3,
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index a77bf6e233d..9d4ecd8da25 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -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
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})
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
@@ -2756,9 +2762,10 @@ 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. Note also that when redefining (or
-advising) a type declared function the replacement should respect the
-original signature to avoid undefined behavior.
+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
+undefined behavior.
@item no-font-lock-keyword
This is valid for macros only. Macros with this declaration are
diff --git a/lisp/emacs-lisp/bytecomp.el b/lisp/emacs-lisp/bytecomp.el
index 732a1629177..5d13ad69284 100644
--- a/lisp/emacs-lisp/bytecomp.el
+++ b/lisp/emacs-lisp/bytecomp.el
@@ -138,7 +138,10 @@
:group 'lisp)
(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
:safe #'integerp
:version "30.1")