1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
|
<h3 class="section">Emacs Dynamic Modules</h3> <p>A <em>dynamic Emacs module</em> is a shared library that provides additional functionality for use in Emacs Lisp programs, just like a package written in Emacs Lisp would. </p> <p>Functions that load Emacs Lisp packages can also load dynamic modules. They recognize dynamic modules by looking at their file-name extension, a.k.a. “suffix”. This suffix is platform-dependent. </p> <dl> <dt id="module-file-suffix">Variable: <strong>module-file-suffix</strong>
</dt> <dd><p>This variable holds the system-dependent value of the file-name extension of the module files. Its value is <samp>.so</samp> on POSIX hosts, <samp>.dylib</samp> on macOS, and <samp>.dll</samp> on MS-Windows. </p></dd>
</dl> <p>On macOS, dynamic modules can also have the suffix <samp>.so</samp> in addition to <samp>.dylib</samp>. </p> <p>Every dynamic module should export a C-callable function named <code>emacs_module_init</code>, which Emacs will call as part of the call to <code>load</code> or <code>require</code> which loads the module. It should also export a symbol named <code>plugin_is_GPL_compatible</code> to indicate that its code is released under the GPL or compatible license; Emacs will signal an error if your program tries to load modules that don’t export such a symbol. </p> <p>If a module needs to call Emacs functions, it should do so through the <acronym>API</acronym> (Application Programming Interface) defined and documented in the header file <samp>emacs-module.h</samp> that is part of the Emacs distribution. See <a href="writing-dynamic-modules">Writing Dynamic Modules</a>, for details of using that API when writing your own modules. </p> <p>Modules can create <code>user-ptr</code> Lisp objects that embed pointers to C struct’s defined by the module. This is useful for keeping around complex data structures created by a module, to be passed back to the module’s functions. User-ptr objects can also have associated <em>finalizers</em> – functions to be run when the object is GC’ed; this is useful for freeing any resources allocated for the underlying data structure, such as memory, open file descriptors, etc. See <a href="module-values">Module Values</a>. </p> <dl> <dt id="user-ptrp">Function: <strong>user-ptrp</strong> <em>object</em>
</dt> <dd><p>This function returns <code>t</code> if its argument is a <code>user-ptr</code> object. </p></dd>
</dl> <dl> <dt id="module-load">Function: <strong>module-load</strong> <em>file</em>
</dt> <dd>
<p>Emacs calls this low-level primitive to load a module from the specified <var>file</var> and perform the necessary initialization of the module. This is the primitive which makes sure the module exports the <code>plugin_is_GPL_compatible</code> symbol, calls the module’s <code>emacs_module_init</code> function, and signals an error if that function returns an error indication, or if the use typed <kbd>C-g</kbd> during the initialization. If the initialization succeeds, <code>module-load</code> returns <code>t</code>. Note that <var>file</var> must already have the proper file-name extension, as this function doesn’t try looking for files with known extensions, unlike <code>load</code>. </p> <p>Unlike <code>load</code>, <code>module-load</code> doesn’t record the module in <code>load-history</code>, doesn’t print any messages, and doesn’t protect against recursive loads. Most users should therefore use <code>load</code>, <code>load-file</code>, <code>load-library</code>, or <code>require</code> instead of <code>module-load</code>. </p>
</dd>
</dl> <p>Loadable modules in Emacs are enabled by using the <kbd>--with-modules</kbd> option at configure time. </p>
<hr><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/Dynamic-Modules.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Dynamic-Modules.html</a>
</p>
</div>
|
