From 7351b73d45a2f6f33230e6725fdfdf9e122eff14 Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Sat, 17 Nov 2012 17:38:42 -0800 Subject: [PATCH] Document eager macro expansion * doc/lispref/loading.texi (How Programs Do Loading): Add eager macro expansion. * doc/lispref/macros.texi (Expansion): Mention eager macro expansion. * etc/NEWS: Related edit. --- doc/lispref/ChangeLog | 5 +++++ doc/lispref/loading.texi | 19 +++++++++++++++++++ doc/lispref/macros.texi | 4 ++++ etc/NEWS | 12 ++++++------ 4 files changed, 34 insertions(+), 6 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index da82ece39c1..43ca9ac4aa5 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,8 @@ +2012-11-18 Glenn Morris + + * loading.texi (How Programs Do Loading): Add eager macro expansion. + * macros.texi (Expansion): Mention eager macro expansion. + 2012-11-17 Glenn Morris * minibuf.texi (Basic Completion): Mention misc completion-table funcs. diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index 3a511d34829..54acd0b4d4c 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -113,6 +113,25 @@ When loading a source file (not compiled), @code{load} performs character set translation just as Emacs would do when visiting the file. @xref{Coding Systems}. +@c This is referred to from the Macros chapter. +@c Not sure if it should be the other way round. +@cindex eager macro expansion +When loading an uncompiled file, Emacs tries to expand any macros +that the file contains (@pxref{Macros}). We refer to this as +@dfn{eager macro expansion}. Doing this (rather than deferring +the expansion until the relevant code runs) can significantly speed +up the execution of uncompiled code. Sometimes, this macro expansion +cannot be done, owing to a cyclic dependency. In the simplest +example of this, the file you are loading refers to a macro defined +in another file, and that file in turn requires the file you are +loading. This is generally harmless. Emacs prints a warning +(@samp{Eager macro-expansion skipped due to cycle@dots{}}) +giving details of the problem, but it still loads the file, just +leaving the macro unexpanded for now. You may wish to restructure +your code so that this does not happen. Loading a compiled file does +not cause macroexpansion, because this should already have happened +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}. diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi index 8be6a3fbcde..b0dee1bf215 100644 --- a/doc/lispref/macros.texi +++ b/doc/lispref/macros.texi @@ -86,6 +86,10 @@ macro. calls to other macros. It may even be a call to the same macro, though this is unusual. + Note that Emacs tries to expand macros when loading an uncompiled +Lisp file. This is not always possible, but if it is, it speeds up +subsequent execution. @xref{How Programs Do Loading}. + You can see the expansion of a given macro call by calling @code{macroexpand}. diff --git a/etc/NEWS b/etc/NEWS index f518605b572..388af4a7d40 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -923,13 +923,13 @@ Previously, they returned NaNs on some platforms but signaled errors on others. The affected functions are acos, asin, tan, exp, expt, log, log10, sqrt, and mod. -** Interpreted files are eagerly macro-expanded during load. ++++ +** Emacs tries to macroexpand interpreted (non-compiled) files during load. This can significantly speed up execution of non-byte-compiled code, -but can also bump into harmless and previously unnoticed cyclic -dependencies. These should not be fatal: they will simply cause the -macro-calls to be left for later expansion (as before), but will also -result in a warning ("Eager macro-expansion skipped due to cycle") -describing the cycle. +but can also bump into previously unnoticed cyclic dependencies. +These are generally harmless: they will simply cause the macro calls +to be left for later expansion (as before), but will result in a +warning ("Eager macro-expansion skipped due to cycle") describing the cycle. ** Miscellaneous new functions: +++ -- 2.11.4.GIT