From d1be48fdedabb451d5c6cf315fd5f09a632e771f Mon Sep 17 00:00:00 2001 From: Stefan Monnier Date: Fri, 12 Feb 2021 19:28:25 -0500 Subject: Edebug: Overload `edebug-form-spec` even less The `edebug-form-spec` symbol property was used both to map forms's head symbol to the corresponding spec, and to map spec element names to their expansion. This lead to name conflicts which break instrumentation of examples such as (cl-flet ((gate (x) x)) (gate 4)) because of the Edebug spec element `gate`. So introduce a new symbol property `edebug-elem-spec`. * lisp/subr.el (def-edebug-elem-spec): New function. * lisp/emacs-lisp/edebug.el (edebug--get-elem-spec): New function. (edebug-match-symbol): Use it. (Core Edebug elems): Put them on `edebug-elem-spec` instead of `edebug-form-spec`. (ELisp special forms): Set their `edebug-form-spec` via dolist. (Other non-core Edebug elems): Use `def-edebug-elem-spec`. (edebug-\`): Use `declare`. * lisp/emacs-lisp/pcase.el (pcase-PAT, pcase-FUN, pcase-QPAT): * lisp/skeleton.el (skeleton-edebug-spec): * lisp/emacs-lisp/cl-macs.el: Use `def-edebug-elem-spec`. * test/lisp/emacs-lisp/edebug-tests.el (edebug-tests--conflicting-internal-names): New test. * test/lisp/emacs-lisp/edebug-resources/edebug-test-code.el (edebug-test-code-cl-flet1): New test case. * doc/lispref/edebug.texi (Specification List): Add `def-edebug-elem-spec`. (Specification Examples): Use it. * doc/lispref/loading.texi (Hooks for Loading): Avoid the use of `def-edebug-spec` in example (better use `debug` declaration). --- doc/lispref/loading.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/lispref/loading.texi') diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index 22f0dde593a..33f37331947 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -1125,7 +1125,7 @@ You don't need to give a directory or extension in the file name @var{library}. Normally, you just give a bare file name, like this: @example -(with-eval-after-load "edebug" (def-edebug-spec c-point t)) +(with-eval-after-load "js" (define-key js-mode-map "\C-c\C-c" 'js-eval)) @end example To restrict which files can trigger the evaluation, include a -- cgit v1.2.3 From 58e0c8ee86e2c36245f1c5a1483f1c73600b4914 Mon Sep 17 00:00:00 2001 From: Lars Ingebrigtsen Date: Sun, 14 Feb 2021 13:21:24 +0100 Subject: Extend the syntax of `interactive' to list applicable modes * doc/lispref/commands.texi (Using Interactive): Document the extended `interactive' form. * doc/lispref/loading.texi (Autoload): Document list-of-modes form. * lisp/emacs-lisp/autoload.el (make-autoload): Pick the list of modes from `interactive' out of the functions. * lisp/emacs-lisp/bytecomp.el (byte-compile-lambda): Allow for the extended `interactive' form. * src/callint.c (Finteractive): Document the extended form. * src/data.c (Finteractive_form): Return the interactive form in the old format (even when there's an extended `interactive') to avoid having other parts of Emacs be aware of this. (Fcommand_modes): New defun. * src/emacs-module.c (GCALIGNED_STRUCT): Allow for modules to return command modes. * src/lisp.h: New function module_function_command_modes. --- doc/lispref/commands.texi | 19 +++++++++- doc/lispref/loading.texi | 3 ++ etc/NEWS | 8 ++++ lisp/emacs-lisp/autoload.el | 15 ++++++-- lisp/emacs-lisp/bytecomp.el | 40 ++++++++++++-------- src/callint.c | 9 ++++- src/data.c | 92 ++++++++++++++++++++++++++++++++++++++++++--- src/emacs-module.c | 8 +++- src/eval.c | 9 ++++- src/lisp.h | 3 ++ src/lread.c | 1 + 11 files changed, 179 insertions(+), 28 deletions(-) (limited to 'doc/lispref/loading.texi') diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 3a2c7d019ef..d60745a825b 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -156,7 +156,7 @@ commands by adding the @code{interactive} form to them. makes a Lisp function an interactively-callable command, and how to examine a command's @code{interactive} form. -@defspec interactive arg-descriptor +@defspec interactive &optional arg-descriptor &rest modes This special form declares that a function is a command, and that it may therefore be called interactively (via @kbd{M-x} or by entering a key sequence bound to it). The argument @var{arg-descriptor} declares @@ -177,6 +177,23 @@ forms are executed; at this time, if the @code{interactive} form occurs within the body, the form simply returns @code{nil} without even evaluating its argument. +The @var{modes} list allows specifying which modes the command is +meant to be used in. This affects, for instance, completion in +@kbd{M-x} (commands won't be offered as completions if they don't +match (using @code{derived-mode-p}) the current major mode, or if the +mode is a minor mode, whether it's switched on in the current buffer). +This will also make @kbd{C-h m} list these commands (if they aren't +bound to any keys). + +For instance: + +@lisp +(interactive "p" dired-mode) +@end lisp + +This will mark the command as applicable for modes derived from +@code{dired-mode} only. + By convention, you should put the @code{interactive} form in the function body, as the first top-level form. If there is an @code{interactive} form in both the @code{interactive-form} symbol diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index 33f37331947..8c6aeb04721 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -510,6 +510,9 @@ specification is not given here; it's not needed unless the user actually calls @var{function}, and when that happens, it's time to load the real definition. +If @var{interactive} is a list, it is interpreted as a list of modes +this command is applicable for. + You can autoload macros and keymaps as well as ordinary functions. Specify @var{type} as @code{macro} if @var{function} is really a macro. Specify @var{type} as @code{keymap} if @var{function} is really a diff --git a/etc/NEWS b/etc/NEWS index 08e1e94d83d..d8f0bc60726 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -2266,6 +2266,14 @@ back in Emacs 23.1. The affected functions are: 'make-obsolete', * Lisp Changes in Emacs 28.1 ++++ +** The 'interactive' syntax has been extended to allow listing applicable modes. +Forms like '(interactive "p" dired-mode)' can be used to annotate the +commands as being applicable for modes derived from 'dired-mode', +or if the mode is a minor mode, that the current buffer has that +minor mode activated. Note that using this form will create byte code +that is not compatible with byte code in previous Emacs versions. + +++ ** New buffer-local variable 'minor-modes'. This permanently buffer-local variable holds a list of currently diff --git a/lisp/emacs-lisp/autoload.el b/lisp/emacs-lisp/autoload.el index ec7492dd4b1..ae17039645a 100644 --- a/lisp/emacs-lisp/autoload.el +++ b/lisp/emacs-lisp/autoload.el @@ -141,9 +141,12 @@ expression, in which case we want to handle forms differently." ((stringp (car-safe rest)) (car rest)))) ;; Look for an interactive spec. (interactive (pcase body - ((or `((interactive . ,_) . ,_) - `(,_ (interactive . ,_) . ,_)) - t)))) + ((or `((interactive . ,iargs) . ,_) + `(,_ (interactive . ,iargs) . ,_)) + ;; List of modes or just t. + (if (nthcdr 1 iargs) + (list 'quote (nthcdr 1 iargs)) + t))))) ;; Add the usage form at the end where describe-function-1 ;; can recover it. (when (consp args) (setq doc (help-add-fundoc-usage doc args))) @@ -207,7 +210,11 @@ expression, in which case we want to handle forms differently." easy-mmode-define-minor-mode define-minor-mode)) t) - (eq (car-safe (car body)) 'interactive)) + (and (eq (car-safe (car body)) 'interactive) + ;; List of modes or just t. + (or (if (nthcdr 1 (car body)) + (list 'quote (nthcdr 1 (car body))) + t)))) ,(if macrop ''macro nil)))) ;; For defclass forms, use `eieio-defclass-autoload'. diff --git a/lisp/emacs-lisp/bytecomp.el b/lisp/emacs-lisp/bytecomp.el index 89068a14f02..5c6b9c2e39a 100644 --- a/lisp/emacs-lisp/bytecomp.el +++ b/lisp/emacs-lisp/bytecomp.el @@ -2939,7 +2939,8 @@ for symbols generated by the byte compiler itself." ;; unless it is the last element of the body. (if (cdr body) (setq body (cdr body)))))) - (int (assq 'interactive body))) + (int (assq 'interactive body)) + command-modes) (when lexical-binding (dolist (var arglistvars) (when (assq var byte-compile--known-dynamic-vars) @@ -2951,9 +2952,10 @@ for symbols generated by the byte compiler itself." (if (eq int (car body)) (setq body (cdr body))) (cond ((consp (cdr int)) - (if (cdr (cdr int)) - (byte-compile-warn "malformed interactive spec: %s" - (prin1-to-string int))) + (unless (seq-every-p #'symbolp (cdr (cdr int))) + (byte-compile-warn "malformed interactive specc: %s" + (prin1-to-string int))) + (setq command-modes (cdr (cdr int))) ;; If the interactive spec is a call to `list', don't ;; compile it, because `call-interactively' looks at the ;; args of `list'. Actually, compile it to get warnings, @@ -2964,14 +2966,15 @@ for symbols generated by the byte compiler itself." (while (consp (cdr form)) (setq form (cdr form))) (setq form (car form))) - (if (and (eq (car-safe form) 'list) - ;; For code using lexical-binding, form is not - ;; valid lisp, but rather an intermediate form - ;; which may include "calls" to - ;; internal-make-closure (Bug#29988). - (not lexical-binding)) - nil - (setq int `(interactive ,newform))))) + (setq int + (if (and (eq (car-safe form) 'list) + ;; For code using lexical-binding, form is not + ;; valid lisp, but rather an intermediate form + ;; which may include "calls" to + ;; internal-make-closure (Bug#29988). + (not lexical-binding)) + `(interactive ,form) + `(interactive ,newform))))) ((cdr int) (byte-compile-warn "malformed interactive spec: %s" (prin1-to-string int))))) @@ -3002,9 +3005,16 @@ for symbols generated by the byte compiler itself." (list (help-add-fundoc-usage doc arglist))) ((or doc int) (list doc))) - ;; optionally, the interactive spec. - (if int - (list (nth 1 int)))))))) + ;; optionally, the interactive spec (and the modes the + ;; command applies to). + (cond + ;; We have some command modes, so use the vector form. + (command-modes + (list (vector (nth 1 int) command-modes))) + ;; No command modes, use the simple form with just the + ;; interactive spec. + (int + (list (nth 1 int))))))))) (defvar byte-compile-reserved-constants 0) diff --git a/src/callint.c b/src/callint.c index d3f49bc35d1..18624637843 100644 --- a/src/callint.c +++ b/src/callint.c @@ -104,7 +104,14 @@ If the string begins with `^' and `shift-select-mode' is non-nil, Emacs first calls the function `handle-shift-selection'. You may use `@', `*', and `^' together. They are processed in the order that they appear, before reading any arguments. -usage: (interactive &optional ARG-DESCRIPTOR) */ + +If MODES is present, it should be a list of mode names (symbols) that +this command is applicable for. The main effect of this is that +`M-x TAB' (by default) won't list this command if the current buffer's +mode doesn't match the list. That is, if either the major mode isn't +derived from them, or (when it's a minor mode) the mode isn't in effect. + +usage: (interactive &optional ARG-DESCRIPTOR &rest MODES) */ attributes: const) (Lisp_Object args) { diff --git a/src/data.c b/src/data.c index 38cde0ff8b2..7bddc039f6f 100644 --- a/src/data.c +++ b/src/data.c @@ -904,7 +904,17 @@ Value, if non-nil, is a list (interactive SPEC). */) else if (COMPILEDP (fun)) { if (PVSIZE (fun) > COMPILED_INTERACTIVE) - return list2 (Qinteractive, AREF (fun, COMPILED_INTERACTIVE)); + { + Lisp_Object form = AREF (fun, COMPILED_INTERACTIVE); + if (VECTORP (form)) + /* The vector form is the new form, where the first + element is the interactive spec, and the second is the + command modes. */ + return list2 (Qinteractive, AREF (form, 0)); + else + /* Old form -- just the interactive spec. */ + return list2 (Qinteractive, form); + } } #ifdef HAVE_MODULES else if (MODULE_FUNCTIONP (fun)) @@ -920,10 +930,80 @@ Value, if non-nil, is a list (interactive SPEC). */) else if (CONSP (fun)) { Lisp_Object funcar = XCAR (fun); - if (EQ (funcar, Qclosure)) - return Fassq (Qinteractive, Fcdr (Fcdr (XCDR (fun)))); - else if (EQ (funcar, Qlambda)) - return Fassq (Qinteractive, Fcdr (XCDR (fun))); + if (EQ (funcar, Qclosure) + || EQ (funcar, Qlambda)) + { + Lisp_Object form = Fcdr (XCDR (fun)); + if (EQ (funcar, Qclosure)) + form = Fcdr (form); + Lisp_Object spec = Fassq (Qinteractive, form); + if (NILP (Fcdr (Fcdr (spec)))) + return spec; + else + return list2 (Qinteractive, Fcar (Fcdr (spec))); + } + } + return Qnil; +} + +DEFUN ("command-modes", Fcommand_modes, Scommand_modes, 1, 1, 0, + doc: /* Return the modes COMMAND is defined for. +If COMMAND is not a command, the return value is nil. +The value, if non-nil, is a list of mode name symbols. */) + (Lisp_Object command) +{ + Lisp_Object fun = indirect_function (command); /* Check cycles. */ + + if (NILP (fun)) + return Qnil; + + fun = command; + while (SYMBOLP (fun)) + fun = Fsymbol_function (fun); + + if (SUBRP (fun)) + { + if (!NILP (XSUBR (fun)->command_modes)) + return XSUBR (fun)->command_modes; + } + else if (COMPILEDP (fun)) + { + Lisp_Object form = AREF (fun, COMPILED_INTERACTIVE); + if (VECTORP (form)) + /* New form -- the second element is the command modes. */ + return AREF (form, 1); + else + /* Old .elc file -- no command modes. */ + return Qnil; + } +#ifdef HAVE_MODULES + else if (MODULE_FUNCTIONP (fun)) + { + Lisp_Object form + = module_function_command_modes (XMODULE_FUNCTION (fun)); + if (! NILP (form)) + return form; + } +#endif + else if (AUTOLOADP (fun)) + { + Lisp_Object modes = Fnth (make_int (3), fun); + if (CONSP (modes)) + return modes; + else + return Qnil; + } + else if (CONSP (fun)) + { + Lisp_Object funcar = XCAR (fun); + if (EQ (funcar, Qclosure) + || EQ (funcar, Qlambda)) + { + Lisp_Object form = Fcdr (XCDR (fun)); + if (EQ (funcar, Qclosure)) + form = Fcdr (form); + return Fcdr (Fcdr (Fassq (Qinteractive, form))); + } } return Qnil; } @@ -3908,6 +3988,7 @@ syms_of_data (void) defsubr (&Sindirect_variable); defsubr (&Sinteractive_form); + defsubr (&Scommand_modes); defsubr (&Seq); defsubr (&Snull); defsubr (&Stype_of); @@ -4030,6 +4111,7 @@ This variable cannot be set; trying to do so will signal an error. */); DEFSYM (Qunlet, "unlet"); DEFSYM (Qset, "set"); DEFSYM (Qset_default, "set-default"); + DEFSYM (Qcommand_modes, "command-modes"); defsubr (&Sadd_variable_watcher); defsubr (&Sremove_variable_watcher); defsubr (&Sget_variable_watchers); diff --git a/src/emacs-module.c b/src/emacs-module.c index 894dffcf21e..f8fb54c0728 100644 --- a/src/emacs-module.c +++ b/src/emacs-module.c @@ -549,7 +549,7 @@ struct Lisp_Module_Function union vectorlike_header header; /* Fields traced by GC; these must come first. */ - Lisp_Object documentation, interactive_form; + Lisp_Object documentation, interactive_form, command_modes; /* Fields ignored by GC. */ ptrdiff_t min_arity, max_arity; @@ -646,6 +646,12 @@ module_function_interactive_form (const struct Lisp_Module_Function *fun) return fun->interactive_form; } +Lisp_Object +module_function_command_modes (const struct Lisp_Module_Function *fun) +{ + return fun->command_modes; +} + static emacs_value module_funcall (emacs_env *env, emacs_value func, ptrdiff_t nargs, emacs_value *args) diff --git a/src/eval.c b/src/eval.c index 91fc4e68377..542d7f686e6 100644 --- a/src/eval.c +++ b/src/eval.c @@ -2080,14 +2080,21 @@ then strings and vectors are not accepted. */) DEFUN ("autoload", Fautoload, Sautoload, 2, 5, 0, doc: /* Define FUNCTION to autoload from FILE. FUNCTION is a symbol; FILE is a file name string to pass to `load'. + Third arg DOCSTRING is documentation for the function. -Fourth arg INTERACTIVE if non-nil says function can be called interactively. + +Fourth arg INTERACTIVE if non-nil says function can be called +interactively. If INTERACTIVE is a list, it is interpreted as a list +of modes the function is applicable for. + Fifth arg TYPE indicates the type of the object: nil or omitted says FUNCTION is a function, `keymap' says FUNCTION is really a keymap, and `macro' or t says FUNCTION is really a macro. + Third through fifth args give info about the real definition. They default to nil. + If FUNCTION is already defined other than as an autoload, this does nothing and returns nil. */) (Lisp_Object function, Lisp_Object file, Lisp_Object docstring, Lisp_Object interactive, Lisp_Object type) diff --git a/src/lisp.h b/src/lisp.h index 0847324d1ff..697dd89363c 100644 --- a/src/lisp.h +++ b/src/lisp.h @@ -2060,6 +2060,7 @@ struct Lisp_Subr const char *symbol_name; const char *intspec; EMACS_INT doc; + Lisp_Object command_modes; } GCALIGNED_STRUCT; union Aligned_Lisp_Subr { @@ -4221,6 +4222,8 @@ extern Lisp_Object module_function_documentation (struct Lisp_Module_Function const *); extern Lisp_Object module_function_interactive_form (const struct Lisp_Module_Function *); +extern Lisp_Object module_function_command_modes + (const struct Lisp_Module_Function *); extern module_funcptr module_function_address (struct Lisp_Module_Function const *); extern void *module_function_data (const struct Lisp_Module_Function *); diff --git a/src/lread.c b/src/lread.c index dea1b232fff..8b8ba93c607 100644 --- a/src/lread.c +++ b/src/lread.c @@ -4467,6 +4467,7 @@ defsubr (union Aligned_Lisp_Subr *aname) XSETPVECTYPE (sname, PVEC_SUBR); XSETSUBR (tem, sname); set_symbol_function (sym, tem); + sname->command_modes = Qnil; } #ifdef NOTDEF /* Use fset in subr.el now! */ -- cgit v1.2.3 From a1c84b4308b509c2215fe19f8c8754d76413d43c Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Wed, 10 Mar 2021 05:45:47 +0100 Subject: Remove several references to Emacs 22 and earlier * admin/charsets/mapfiles/README: * doc/emacs/custom.texi (Saving Customizations): * doc/lispintro/emacs-lisp-intro.texi (Simple Extension): * doc/misc/efaq-w32.texi (Location of init file): * doc/misc/gnus-faq.texi (FAQ 1-3): * doc/misc/gnus.texi (Top, Various, Image Enhancements): * lisp/erc/erc-menu.el (menu): * lisp/progmodes/cfengine.el (cfengine-fill-paragraph): Remove some references to Emacs 22 and earlier. * doc/lispref/buffers.texi: * doc/lispref/eval.texi: * doc/lispref/files.texi: * doc/lispref/keymaps.texi: * doc/lispref/loading.texi: * doc/lispref/minibuf.texi: * doc/lispref/positions.texi: * doc/lispref/variables.texi: Remove comments about "Emacs 19 specific" features. --- admin/charsets/mapfiles/README | 4 ++-- doc/emacs/custom.texi | 14 +++++++------- doc/lispintro/emacs-lisp-intro.texi | 17 ++++++++--------- doc/lispref/buffers.texi | 3 --- doc/lispref/eval.texi | 1 - doc/lispref/files.texi | 5 ----- doc/lispref/keymaps.texi | 6 ------ doc/lispref/loading.texi | 1 - doc/lispref/minibuf.texi | 4 ---- doc/lispref/positions.texi | 1 - doc/lispref/variables.texi | 2 -- doc/misc/efaq-w32.texi | 9 ++++----- doc/misc/gnus-faq.texi | 8 +------- doc/misc/gnus.texi | 9 ++++----- lisp/erc/erc-menu.el | 4 ++-- lisp/progmodes/cfengine.el | 4 +--- 16 files changed, 29 insertions(+), 63 deletions(-) (limited to 'doc/lispref/loading.texi') diff --git a/admin/charsets/mapfiles/README b/admin/charsets/mapfiles/README index 60f09125a91..fb078269d6f 100644 --- a/admin/charsets/mapfiles/README +++ b/admin/charsets/mapfiles/README @@ -63,8 +63,8 @@ to "JIS X 0213:2004". * MULE-*.map -Created by using ../mule-charsets.el in Emacs 22 as this: - % emacs-22 -batch -l ../mule-charsets.el +Created by using ../mule-charsets.el in Emacs as this: + % emacs -batch -l ../mule-charsets.el This file is part of GNU Emacs. diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index 22900c57392..bd505d27eca 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -388,15 +388,15 @@ file. For example: Emacs versions, like this: @example -(cond ((< emacs-major-version 22) - ;; @r{Emacs 21 customization.} - (setq custom-file "~/.config/custom-21.el")) - ((and (= emacs-major-version 22) +(cond ((< emacs-major-version 28) + ;; @r{Emacs 27 customization.} + (setq custom-file "~/.config/custom-27.el")) + ((and (= emacs-major-version 26) (< emacs-minor-version 3)) - ;; @r{Emacs 22 customization, before version 22.3.} - (setq custom-file "~/.config/custom-22.el")) + ;; @r{Emacs 26 customization, before version 26.3.} + (setq custom-file "~/.config/custom-26.el")) (t - ;; @r{Emacs version 22.3 or later.} + ;; @r{Emacs version 28.1 or later.} (setq custom-file "~/.config/emacs-custom.el"))) (load custom-file) diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index d5c280b7924..5b15a456ff0 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -17532,10 +17532,9 @@ Here is the definition: @need 1250 Now for the keybinding. -Nowadays, function keys as well as mouse button events and -non-@sc{ascii} characters are written within square brackets, without -quotation marks. (In Emacs version 18 and before, you had to write -different function key bindings for each different make of terminal.) +Function keys as well as mouse button events and non-@sc{ascii} +characters are written within square brackets, without quotation +marks. I bind @code{line-to-top-of-window} to my @key{F6} function key like this: @@ -17550,18 +17549,18 @@ Your Init File, emacs, The GNU Emacs Manual}. @cindex Conditional 'twixt two versions of Emacs @cindex Version of Emacs, choosing @cindex Emacs version, choosing -If you run two versions of GNU Emacs, such as versions 22 and 23, and +If you run two versions of GNU Emacs, such as versions 27 and 28, and use one @file{.emacs} file, you can select which code to evaluate with the following conditional: @smallexample @group (cond - ((= 22 emacs-major-version) - ;; evaluate version 22 code + ((= 27 emacs-major-version) + ;; evaluate version 27 code ( @dots{} )) - ((= 23 emacs-major-version) - ;; evaluate version 23 code + ((= 28 emacs-major-version) + ;; evaluate version 28 code ( @dots{} ))) @end group @end smallexample diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 69733f91c4a..0d31b0bc4c6 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -309,7 +309,6 @@ foo This function renames the current buffer to @var{newname}. An error is signaled if @var{newname} is not a string. -@c Emacs 19 feature Ordinarily, @code{rename-buffer} signals an error if @var{newname} is already in use. However, if @var{unique} is non-@code{nil}, it modifies @var{newname} to make a name that is not in use. Interactively, you can @@ -344,7 +343,6 @@ a name. For example: See also the function @code{get-buffer-create} in @ref{Creating Buffers}. @end defun -@c Emacs 19 feature @defun generate-new-buffer-name starting-name &optional ignore This function returns a name that would be unique for a new buffer---but does not create the buffer. It starts with @var{starting-name}, and @@ -879,7 +877,6 @@ then @code{other-buffer} uses that predicate to decide which buffers to consider. It calls the predicate once for each buffer, and if the value is @code{nil}, that buffer is ignored. @xref{Buffer Parameters}. -@c Emacs 19 feature If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning a buffer visible in any window on any visible frame, except as a last resort. If @var{visible-ok} is non-@code{nil}, then it does not matter diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index 80e038c96d9..448b8ae17ab 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -332,7 +332,6 @@ or just The built-in function @code{indirect-function} provides an easy way to perform symbol function indirection explicitly. -@c Emacs 19 feature @defun indirect-function function &optional noerror @anchor{Definition of indirect-function} This function returns the meaning of @var{function} as a function. If diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 4110c51099d..2828b50cadb 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -455,7 +455,6 @@ Even though this is not a normal hook, you can use @code{add-hook} and @code{remove-hook} to manipulate the list. @xref{Hooks}. @end defvar -@c Emacs 19 feature @defvar write-contents-functions This works just like @code{write-file-functions}, but it is intended for hooks that pertain to the buffer's contents, not to the particular @@ -486,7 +485,6 @@ this hook to make sure the file you are saving has the current year in its copyright notice. @end defopt -@c Emacs 19 feature @defopt after-save-hook This normal hook runs after a buffer has been saved in its visited file. @end defopt @@ -622,7 +620,6 @@ If @var{start} is @code{nil}, then the command writes the entire buffer contents (@emph{not} just the accessible portion) to the file and ignores @var{end}. -@c Emacs 19 feature If @var{start} is a string, then @code{write-region} writes or appends that string, rather than text from the buffer. @var{end} is ignored in this case. @@ -653,7 +650,6 @@ It also sets the last file modification time for the current buffer to feature is used by @code{save-buffer}, but you probably should not use it yourself. -@c Emacs 19 feature If @var{visit} is a string, it specifies the file name to visit. This way, you can write the data to one file (@var{filename}) while recording the buffer as visiting another file (@var{visit}). The argument @@ -3094,7 +3090,6 @@ which generate the listing with Lisp code. @node Create/Delete Dirs @section Creating, Copying and Deleting Directories @cindex creating, copying and deleting directories -@c Emacs 19 features Most Emacs Lisp file-manipulation functions get errors when used on files that are directories. For example, you cannot delete a directory diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 6a227e3a792..dabf985018f 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -369,7 +369,6 @@ appear directly as bindings in @var{keymap} are also copied recursively, and so on to any number of levels. However, recursive copying does not take place when the definition of a character is a symbol whose function definition is a keymap; the same symbol appears in the new copy. -@c Emacs 19 feature @example @group @@ -1140,7 +1139,6 @@ and have extra events at the end that do not fit into a single key sequence. Then the value is a number, the number of events at the front of @var{key} that compose a complete key. -@c Emacs 19 feature If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key} considers default bindings as well as bindings for the specific events in @var{key}. Otherwise, @code{lookup-key} reports only bindings for @@ -1182,7 +1180,6 @@ not cause an error. This function returns the binding for @var{key} in the current local keymap, or @code{nil} if it is undefined there. -@c Emacs 19 feature The argument @var{accept-defaults} controls checking for default bindings, as in @code{lookup-key} (above). @end defun @@ -1191,12 +1188,10 @@ as in @code{lookup-key} (above). This function returns the binding for command @var{key} in the current global keymap, or @code{nil} if it is undefined there. -@c Emacs 19 feature The argument @var{accept-defaults} controls checking for default bindings, as in @code{lookup-key} (above). @end defun -@c Emacs 19 feature @defun minor-mode-key-binding key &optional accept-defaults This function returns a list of all the active minor mode bindings of @var{key}. More precisely, it returns an alist of pairs @@ -1414,7 +1409,6 @@ standard bindings: @end group @end smallexample -@c Emacs 19 feature If @var{oldmap} is non-@code{nil}, that changes the behavior of @code{substitute-key-definition}: the bindings in @var{oldmap} determine which keys to rebind. The rebindings still happen in @var{keymap}, not diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index 8c6aeb04721..e68a1ef314a 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -1052,7 +1052,6 @@ rather than replacing that element. @xref{Eval}. @section Unloading @cindex unloading packages -@c Emacs 19 feature You can discard the functions and variables loaded by a library to reclaim memory for other Lisp objects. To do this, use the function @code{unload-feature}: diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index bbc834004b0..d16409d6c89 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -379,8 +379,6 @@ default, it makes the following bindings: @end table @end defvar -@c In version 18, initial is required -@c Emacs 19 feature @defun read-no-blanks-input prompt &optional initial inherit-input-method This function reads a string from the minibuffer, but does not allow whitespace characters as part of the input: instead, those characters @@ -2475,7 +2473,6 @@ usual minibuffer input functions because they all start by choosing the minibuffer window according to the selected frame. @end defun -@c Emacs 19 feature @defun window-minibuffer-p &optional window This function returns @code{t} if @var{window} is a minibuffer window. @var{window} defaults to the selected window. @@ -2619,7 +2616,6 @@ when the minibuffer is active, not even if you switch to another window to do it. @end defopt -@c Emacs 19 feature If a command name has a property @code{enable-recursive-minibuffers} that is non-@code{nil}, then the command can use the minibuffer to read arguments even if it is invoked from the minibuffer. A command can diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi index dc0c7442d8d..769aeed75f8 100644 --- a/doc/lispref/positions.texi +++ b/doc/lispref/positions.texi @@ -232,7 +232,6 @@ backward until encountering the front of a word, rather than forward. @end deffn @defopt words-include-escapes -@c Emacs 19 feature This variable affects the behavior of @code{forward-word} and @code{backward-word}, and everything that uses them. If it is non-@code{nil}, then characters in the escape and character-quote diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index 63438170d1a..0ddf3e465d6 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -1696,7 +1696,6 @@ buffer has a buffer-local binding. For example, you could use you are in a C or Lisp mode buffer that has a buffer-local value for this variable. -@c Emacs 19 feature The special forms @code{defvar} and @code{defconst} also set the default value (if they set the variable at all), rather than any buffer-local value. @@ -1708,7 +1707,6 @@ this variable. If @var{symbol} is not buffer-local, this is equivalent to @code{symbol-value} (@pxref{Accessing Variables}). @end defun -@c Emacs 19 feature @defun default-boundp symbol The function @code{default-boundp} tells you whether @var{symbol}'s default value is nonvoid. If @code{(default-boundp 'foo)} returns diff --git a/doc/misc/efaq-w32.texi b/doc/misc/efaq-w32.texi index 2abde2c2843..6eff88b76e3 100644 --- a/doc/misc/efaq-w32.texi +++ b/doc/misc/efaq-w32.texi @@ -370,11 +370,10 @@ On Windows, the @file{.emacs} file may be called @file{_emacs} for backward compatibility with DOS and FAT filesystems where filenames could not start with a dot. Some users prefer to continue using such a name due to historical problems various Windows tools had in the -past with file names that begin with a dot. In Emacs 22 and later, -the init file may also be called @file{.emacs.d/init.el}. Many of the -other files that are created by lisp packages are now stored in the -@file{.emacs.d} directory too, so this keeps all your Emacs related -files in one place. +past with file names that begin with a dot. The init file may also be +called @file{.emacs.d/init.el}. Many of the other files that are +created by Lisp packages are stored in the @file{.emacs.d} directory +too, which keeps all your Emacs related files in one place. All the files mentioned above should go in your @env{HOME} directory. The @env{HOME} directory is determined by following the steps below: diff --git a/doc/misc/gnus-faq.texi b/doc/misc/gnus-faq.texi index 4c29976c05e..35a25262115 100644 --- a/doc/misc/gnus-faq.texi +++ b/doc/misc/gnus-faq.texi @@ -160,13 +160,7 @@ Where and how to get Gnus? @subsubheading Answer -Gnus is released independent from releases of Emacs. Therefore, the -version bundled with Emacs might not be up to date (e.g., Gnus 5.9 -bundled with Emacs 21 is outdated). -You can get the latest released version of Gnus from -@uref{https://www.gnus.org/dist/gnus.tar.gz} -or from -@uref{https://ftp.gnus.org/pub/gnus/gnus.tar.gz}. +Gnus is bundled with Emacs. @node FAQ 1-4 @subsubheading Question 1.4 diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index faf5366e2ba..b6553c8a636 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -815,7 +815,7 @@ Various * Undo:: Some actions can be undone. * Predicate Specifiers:: Specifying predicates. * Moderation:: What to do if you're a moderator. -* Image Enhancements:: Modern versions of Emacs can display images. +* Image Enhancements:: Emacs can display images. * Fuzzy Matching:: What's the big fuzz? * Thwarting Email Spam:: Simple ways to avoid unsolicited commercial email. * Spam Package:: A package for filtering and processing spam. @@ -22505,7 +22505,7 @@ to you, using @kbd{G b u} and updating the group will usually fix this. * Predicate Specifiers:: Specifying predicates. * Moderation:: What to do if you're a moderator. * Fetching a Group:: Starting Gnus just to read a group. -* Image Enhancements:: Modern versions of Emacs can display images. +* Image Enhancements:: Emacs can display images. * Fuzzy Matching:: What's the big fuzz? * Thwarting Email Spam:: Simple ways to avoid unsolicited commercial email. * Spam Package:: A package for filtering and processing spam. @@ -23668,9 +23668,8 @@ It takes the group name as a parameter. @node Image Enhancements @section Image Enhancements -Emacs 21@footnote{Emacs 21 on MS Windows doesn't -support images, Emacs 22 does.} and up are able to display pictures and -stuff, so Gnus has taken advantage of that. +Emacs is able to display pictures and stuff, so Gnus has taken +advantage of that. @menu * X-Face:: Display a funky, teensy black-and-white image. diff --git a/lisp/erc/erc-menu.el b/lisp/erc/erc-menu.el index 0e334e93bd9..d76e0a345ef 100644 --- a/lisp/erc/erc-menu.el +++ b/lisp/erc/erc-menu.el @@ -110,11 +110,11 @@ ERC menu yet.") (define-erc-module menu nil "Enable a menu in ERC buffers." ((unless erc-menu-defined - ;; make sure the menu only gets defined once, since Emacs 22 + ;; make sure the menu only gets defined once, since Emacs ;; activates it immediately (easy-menu-define erc-menu erc-mode-map "ERC menu" erc-menu-definition) (setq erc-menu-defined t))) - (;; `easy-menu-remove' is a no-op in Emacs 22 + (;; `easy-menu-remove' is a no-op in Emacs (message "You might have to restart Emacs to remove the ERC menu"))) (defun erc-menu-add () diff --git a/lisp/progmodes/cfengine.el b/lisp/progmodes/cfengine.el index bef99f2484b..472788d18e5 100644 --- a/lisp/progmodes/cfengine.el +++ b/lisp/progmodes/cfengine.el @@ -987,13 +987,11 @@ Intended as the value of `indent-line-function'." (if (> (- (point-max) pos) (point)) (goto-char (- (point-max) pos))))) -;; This doesn't work too well in Emacs 21.2. See 22.1 development -;; code. (defun cfengine-fill-paragraph (&optional justify) "Fill `paragraphs' in Cfengine code." (interactive "P") (or (if (fboundp 'fill-comment-paragraph) - (fill-comment-paragraph justify) ; post Emacs 21.3 + (fill-comment-paragraph justify) ;; else do nothing in a comment (nth 4 (parse-partial-sexp (save-excursion (beginning-of-defun) -- cgit v1.2.3 From 79e2d0486c89c6c452df33792976ea6fdf825185 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 8 May 2021 16:26:41 +0300 Subject: Document native-compilation * doc/lispref/loading.texi (How Programs Do Loading) (Library Search): Update for native-compilation features. * doc/lispref/compile.texi (Native Compilation) (Native-Compilation Functions, Native-Compilation Variables): New chapter and sections. * doc/lispref/elisp.texi (Top): Update the top-level menus. * etc/NEWS: Add a reference to the ELisp manual. --- doc/lispref/compile.texi | 245 +++++++++++++++++++++++++++++++++++++++++++++++ doc/lispref/elisp.texi | 6 ++ doc/lispref/loading.texi | 33 ++++++- etc/NEWS | 5 +- 4 files changed, 286 insertions(+), 3 deletions(-) (limited to 'doc/lispref/loading.texi') diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index bf420040950..f0787795cac 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -793,3 +793,248 @@ The @code{silly-loop} function is somewhat more complex: 17 return ; @r{Return value of the top of stack.} @end group @end example + +@node Native Compilation +@chapter Compilation of Lisp to Native Code +@cindex native compilation +@cindex compilation to native code (Emacs Lisp) + +@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. + +@vindex native-compile@r{, a Lisp feature} + To determine whether the current Emacs process can produce and load +natively-compiled Lisp code, test whether the @code{native-compile} +feature is available (@pxref{Named Features}). Alternatively, call +@code{native-comp-available-p} (@pxref{Native-Compilation Functions}). + + Unlike byte-compiled code, natively-compiled Lisp code is executed +directly by the machine's hardware, and therefore runs at full speed +that the host CPU can provide. The resulting speedup generally +depends on what the Lisp code does, but is usually 2.5 to 5 times +faster than the corresponding byte-compiled code. + + Since native code is generally incompatible between different +systems, the natively-compiled code is @emph{not} transportable from +one machine to another, it can only be used on the same machine where +it was produced or on very similar ones (having the same CPU and +run-time libraries). The transportability of natively-compiled code +is the same as that of shared libraries (@file{.so} or @file{.dll} +files). + + Libraries of natively-compiled code include crucial dependencies on +Emacs Lisp primitives (@pxref{What Is a Function}) and their calling +conventions, and thus Emacs usually won't load natively-compiled code +produced by earlier or later Emacs versions; native compilation of the +same Lisp code by a different Emacs version will usually produce a +natively-compiled library under a unique file name that only that +version of Emacs will be able to load. However, the use of unique +file names allows to have in the same directory several versions of +the same Lisp library natively-compiled by several different versions +of Emacs. + +@vindex no-native-compile + A non-@code{nil} file-local variable binding of +@code{no-byte-compile} (@pxref{Byte Compilation}) also disables the +native compilation of that file. In addition, a similar variable +@code{no-native-compile} disables just the native compilation of the +file. If both @code{no-byte-compile} and @code{no-native-compile} are +specified, the former takes precedence. + +@menu +* Native-Compilation Functions:: Functions to natively-compile Lisp. +* Native-Compilation Variables:: Variables controlling native compilation. +@end menu + +@node Native-Compilation Functions +@section Native-Compilation Functions +@cindex native-compilation functions + + Native-Compilation is implemented as 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 +(@pxref{Compilation Functions}) are valid for native-compilation as +well. + + You can natively-compile either a single function or macro +definition, or a whole file of Lisp code, with the +@code{native-compile} function. Natively-compiling a file will +produce both the corresponding @file{.elc} file with byte code and the +@file{.eln} file with native code. + +@findex native-comp-limple-mode +@vindex native-comp-verbose + 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 +native-compilation can be controlled by the @code{native-comp-verbose} +variable (@pxref{Native-Compilation Variables}). + + When Emacs is run non-interactively, messages produced by +native-compilation are reported by calling @code{message} +(@pxref{Displaying Messages}), and are usually displayed on the +standard error stream of the terminal from which Emacs was invoked. + +@defun native-compile function-or-file &optional output +This function compiles @var{function-or-file} into native code. The +argument @var{function-or-file} can be a function symbol, a Lisp form, +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 +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 the same Emacs executable as the process that called this +function. +@end defun + +@defun batch-native-compile +This function runs native-compilation on files specified on the Emacs +command line in batch mode. It must be used only in a batch execution +of Emacs, as it kills Emacs upon completion of the compilation. If +one or more of the files fail to compile, the Emacs process will +attempt to compile all the other files, and will terminate with a +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. + +@defun native-compile-async files &optional recursively load selector +This function compiles the named @var{files} asynchronously. The +argument @var{files} should be a single file name (a string) or a list +of one or more file and/or directory names. If directories are +present in the list, the optional argument @var{recursively} should be +non-@code{nil} to cause the compilation to recurse into those +directories. If @var{load} is non-@code{nil}, Emacs will load each +file that it succeeded to compile. The optional argument +@var{selector} allows control of which of @var{files} will be +compiled; it can have one of the following values: + +@table @asis +@item @code{nil} or omitted +Select all the files and directories in @var{files}. +@item a regular expression string +Select the files and directories whose names match the regexp. +@item a function +A predicate function, which will be called with each file and +directory in @var{files}, and should return non-@code{nil} if the file +or the directory should be selected for compilation. +@end table + +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 +@code{native-comp-async-jobs-number} (@pxref{Native-Compilation +Variables}). +@end defun + + The following function allows Lisp program to test whether +native-compilation is available at runtime. + +@defun native-comp-available-p +This function returns non-@code{nil} if the running Emacs process has +the native-compilation support compiled into it. On systems that load +@file{libgccjit} dynamically, it also makes sure that library is +available and can be loaded. Lisp programs that need to know up front +whether native-compilation is available should use this predicate. +@end defun + +@node Native-Compilation Variables +@section Native-Compilation Variables +@cindex native-compilation variable + + This section documents the variables that control +native-compilation. + +@defopt native-comp-speed +This variable specifies the optimization level for native compilation. +Its value should be a number between @minus{}1 and 3. Values between +0 and 3 specify the optimization levels equivalent to the +corresponding compiler @option{-O0}, @option{-O1}, etc.@: command-line +options of the compiler. The value @minus{}1 means disable +native-compilation; functions and files will be only byte-compiled. +The default value is 2. +@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, +with the following meaning: + +@table @asis +@item 0 +No debugging output. This is the default. +@item 1 +Emit debugging symbols with the native code. This allows easier +debugging of the native code with debuggers such as @command{gdb}. +@item 2 +Like 1, and in addition dump pseudo-C code. +@item 3 +Like 2, and in addition dump the GCC intermediate passes and +@file{libgccjit} log file. +@end table +@end defopt + +@defopt native-comp-verbose +This variable controls the verbosity of native-compilation by +suppressing some or all of the log messages emitted by it. If its +value is zero, the default, all of the log messages are suppressed. +Setting it to a value between 1 and 3 will allow logging of the +messages whose level is above the value. The values have the +following interpretations: + +@table @asis +@item 0 +No logging. This is the default. +@item 1 +Log the final @acronym{LIMPLE} representation of the code. +@item 2 +Log the @acronym{LAP}, the final @acronym{LIMPLE}, and some additional +pass info. +@item 3 +Maximum verbosity: log everything. +@end table +@end defopt + +@defopt native-comp-async-jobs-number +This variable determines the maximum number of native-compilation +subprocesses that will be started simultaneously. It should be a +non-negative number. The default value is zero, which means use half +the number of the CPU execution units, or 1 if the CPU has only one +execution unit. +@end defopt + +@defopt native-comp-async-report-warnings-errors +If this variable's value is non-@code{nil}, warnings and errors from +asynchronous native-compilation subprocesses are reported in the main +Emacs session. The default is @code{t}. +@end defopt + +@defopt native-comp-async-query-on-exit +If this variable's value is non-nil, Emacs will query upon exiting +whether to exit and kill any asynchronous native-compilation +subprocesses that are still running, thus preventing the corresponding +@file{.eln} files from being written. If the value is @code{nil}, the +default, Emacs will kill these subprocesses without querying. +@end defopt diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index be0c835b035..8b440c79774 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -197,6 +197,7 @@ To view this manual in other formats, click * Loading:: Reading files of Lisp code into Lisp. * Byte Compilation:: Compilation makes programs run faster. +* Native Compilation:: Compile Lisp into native machine code. * Debugging:: Tools and tips for debugging Lisp programs. * Read and Print:: Converting Lisp objects to text and back. @@ -646,6 +647,11 @@ Byte Compilation * Byte-Code Objects:: The data type used for byte-compiled functions. * Disassembly:: Disassembling byte-code; how to read byte-code. +Native Compilation + +* Native-Compilation Functions:: Functions to natively-compile Lisp. +* Native-Compilation Variables:: Variables controlling native compilation. + Debugging Lisp Programs * Debugger:: A debugger for the Emacs Lisp evaluator. diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index e68a1ef314a..4d683da1ad3 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -71,7 +71,11 @@ forms in it, and closes the file. To find the file, @code{load} first looks for a file named @file{@var{filename}.elc}, that is, for a file whose name is @var{filename} with the extension @samp{.elc} appended. If such a -file exists, it is loaded. If there is no file by that name, then +file exists, and Emacs was compiled with native-compilation support +(@pxref{Native Compilation}), @code{load} attempts to find a +corresponding @samp{.eln} file, and if found, loads it instead of +@file{@var{filename}.elc}. Otherwise, it loads +@file{@var{filename}.elc}. If there is no file by that name, then @code{load} looks for a file named @file{@var{filename}.el}. If that file exists, it is loaded. If Emacs was compiled with support for dynamic modules (@pxref{Dynamic Modules}), @code{load} next looks for @@ -109,6 +113,8 @@ explicit directory name. If the option @code{load-prefer-newer} is non-@code{nil}, then when searching suffixes, @code{load} selects whichever version of a file (@samp{.elc}, @samp{.el}, etc.)@: has been modified most recently. +In this case, @code{load} doesn't load the @samp{.eln} +natively-compiled file even if it exists. If @var{filename} is a relative file name, such as @file{foo} or @file{baz/foo.bar}, @code{load} searches for the file using the variable @@ -153,7 +159,8 @@ during compilation. @xref{Compiling Macros}. Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear in the echo area during loading unless @var{nomessage} is -non-@code{nil}. +non-@code{nil}. If a natively-compiled @samp{.eln} file is loaded, +the message says so. @cindex load errors Any unhandled errors while loading a file terminate loading. If the @@ -430,6 +437,28 @@ optional argument @code{stringp} is non-@code{nil}, it instead returns the shadowed files as a string. @end deffn + If Emacs was compiled with support for native compilation +(@pxref{Native Compilation}), then when a @samp{.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 +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 +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 +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 +@code{comp-native-version-dir}. +@end defvar + @node Loading Non-ASCII @section Loading Non-@acronym{ASCII} Characters @cindex loading, and non-ASCII characters diff --git a/etc/NEWS b/etc/NEWS index 9f4ded3aaba..6efadfec6f9 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -26,7 +26,10 @@ applies, and please also update docstrings as needed. ** Emacs now optionally supports native compilation of Lisp files. To enable this, configure Emacs with the '--with-native-compilation' option. -This requires the libgccjit library to be installed and functional. +This requires the libgccjit library to be installed and functional, +and also requires GCC and Binutils to be available when Lisp code is +natively compiled. See the Info node "(elisp) Native Compilation" for +more details. --- ** Support for building with Motif has been removed. -- cgit v1.2.3