diff options
Diffstat (limited to 'devdocs/elisp/docs-and-compilation.html')
| -rw-r--r-- | devdocs/elisp/docs-and-compilation.html | 12 |
1 files changed, 12 insertions, 0 deletions
diff --git a/devdocs/elisp/docs-and-compilation.html b/devdocs/elisp/docs-and-compilation.html new file mode 100644 index 00000000..8d839e54 --- /dev/null +++ b/devdocs/elisp/docs-and-compilation.html @@ -0,0 +1,12 @@ + <h3 class="section">Documentation Strings and Compilation</h3> <p>When Emacs loads functions and variables from a byte-compiled file, it normally does not load their documentation strings into memory. Each documentation string is dynamically loaded from the byte-compiled file only when needed. This saves memory, and speeds up loading by skipping the processing of the documentation strings. </p> <p>This feature has a drawback: if you delete, move, or alter the compiled file (such as by compiling a new version), Emacs may no longer be able to access the documentation string of previously-loaded functions or variables. Such a problem normally only occurs if you build Emacs yourself, and happen to edit and/or recompile the Lisp source files. To solve it, just reload each file after recompilation. </p> <p>Dynamic loading of documentation strings from byte-compiled files is determined, at compile time, for each byte-compiled file. It can be disabled via the option <code>byte-compile-dynamic-docstrings</code>. </p> <dl> <dt id="byte-compile-dynamic-docstrings">User Option: <strong>byte-compile-dynamic-docstrings</strong> +</dt> <dd> +<p>If this is non-<code>nil</code>, the byte compiler generates compiled files that are set up for dynamic loading of documentation strings. </p> <p>To disable the dynamic loading feature for a specific file, set this option to <code>nil</code> in its header line (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/File-Variables.html#File-Variables">Local Variables in Files</a> in <cite>The GNU Emacs Manual</cite>), like this: </p> <div class="example"> <pre class="example">-*-byte-compile-dynamic-docstrings: nil;-*- +</pre> +</div> <p>This is useful mainly if you expect to change the file, and you want Emacs sessions that have already loaded it to keep working when the file changes. </p> +</dd> +</dl> <p>Internally, the dynamic loading of documentation strings is accomplished by writing compiled files with a special Lisp reader construct, ‘<samp>#@<var>count</var></samp>’. This construct skips the next <var>count</var> characters. It also uses the ‘<samp>#$</samp>’ construct, which stands for the name of this file, as a string. Do not use these constructs in Lisp source files; they are not designed to be clear to humans reading the file. </p><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Docs-and-Compilation.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Docs-and-Compilation.html</a> + </p> +</div> |