GNU Info

(elisp)Docs and Compilation

---

Next: Dynamic Loading Prev: Compilation Functions Up: Byte Compilation

---

Enter node , (file) or (file)node

Documentation Strings and Compilation
=====================================

   Functions and variables loaded from a byte-compiled file access their
documentation strings dynamically from the file whenever needed.  This
saves space within Emacs, and makes loading faster because the
documentation strings themselves need not be processed while loading the
file.  Actual access to the documentation strings becomes slower as a
result, but this normally is not enough to bother users.

   Dynamic access to documentation strings does have drawbacks:

   * If you delete or move the compiled file after loading it, Emacs
     can no longer access the documentation strings for the functions
     and variables in the file.

   * If you alter the compiled file (such as by compiling a new
     version), then further access to documentation strings in this
     file will give nonsense results.

   If your site installs Emacs following the usual procedures, these
problems will never normally occur.  Installing a new version uses a new
directory with a different name; as long as the old version remains
installed, its files will remain unmodified in the places where they are
expected to be.

   However, if you have built Emacs yourself and use it from the
directory where you built it, you will experience this problem
occasionally if you edit and recompile Lisp files.  When it happens, you
can cure the problem by reloading the file after recompiling it.

   Byte-compiled files made with recent versions of Emacs (since 19.29)
will not load into older versions because the older versions don't
support this feature.  You can turn off this feature at compile time by
setting `byte-compile-dynamic-docstrings' to `nil'; then you can
compile files that will load into older Emacs versions.  You can do
this globally, or for one source file by specifying a file-local binding
for the variable.  One way to do that is by adding this string to the
file's first line:

     -*-byte-compile-dynamic-docstrings: nil;-*-

 - Variable: byte-compile-dynamic-docstrings
     If this is non-`nil', the byte compiler generates compiled files
     that are set up for dynamic loading of documentation strings.

   The dynamic documentation string feature writes compiled files that
use a special Lisp reader construct, `#@COUNT'.  This construct skips
the next COUNT characters.  It also uses the `#$' construct, which
stands for "the name of this file, as a string."  It is usually best
not to use these constructs in Lisp source files, since they are not
designed to be clear to humans reading the file.