From 3858b7949fdf5af8dd94cefc5a2684ad285e2cdf Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 21 Nov 2015 12:49:57 +0200 Subject: [PATCH] Improve documentation of dynamic modules * src/fns.c (Frequire): Doc fix to include the dynamic module support. * src/lread.c (Fload, Vload_suffixes): Doc fixes to include the dynamic module support. (Fload): Treat the module suffix the same as '*.el' and '*.elc' wrt the MUST-SUFFIX argument. * etc/NEWS: Expand documentation of dynamically loaded modules. --- etc/NEWS | 40 +++++++++++++++++++++++++++++++++------- src/alloc.c | 2 +- src/fns.c | 5 +++-- src/lread.c | 22 ++++++++++++---------- 4 files changed, 49 insertions(+), 20 deletions(-) diff --git a/etc/NEWS b/etc/NEWS index 8ed8133beae..dce02c31e59 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -305,13 +305,39 @@ header. which specifies an alternative printing method which is faster when few or no entries have changed. -** Emacs can now load shared/dynamic libraries (modules) that expose a -C interface. Such modules can provide additional functions or -otherwise interact with Emacs just like Lisp code. Modules have to -export a function `emacs_module_init' and conform to the API laid out -in emacs-module.h. Modules are disabled by default and need to be -enabled using the --with-modules configure flag. They are -experimental and subject to change. +** Emacs can now load shared/dynamic libraries (modules). +A dynamic Emacs module is a shared library that provides additional +functionality for use in Emacs Lisp programs, just like a package +written in Emacs Lisp would. The functions `load' and `require' were +extended to load such modules, as they do with Emacs Lisp packages. + +A module should export a C-callable function named +`emacs_module_init', which Emacs will call as part of the call to +`load' or `require' which loads the module. It should also export a +symbol named `plugin_is_GPL_compatible' to indicate that its code is +released under the GPL or compatible license; Emacs will refuse to +load modules that don't export such a symbol. + +If a module needs to call Emacs functions, it should do so through the +API defined and documented in the header file `emacs-module.h'. Note +that any module that provides Lisp-callable functions will have to use +Emacs functions such as `fset' and `funcall', in order to register its +functions with the Emacs Lisp interpreter. + +Modules can create `user-ptr' 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 +"finalizers" -- 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. A new +predicate `user-ptr-p' returns non-nil if its argument is a `usr-ptr' +object. + +Loadable modules in Emacs are an experimental feature, and subject to +change in future releases. For that reason, their support is disabled +by default, and must be enabled by using the `--with-modules' option +at configure time. * Editing Changes in Emacs 25.1 diff --git a/src/alloc.c b/src/alloc.c index 53f974533a8..ad3f5235480 100644 --- a/src/alloc.c +++ b/src/alloc.c @@ -3712,7 +3712,7 @@ make_event_array (ptrdiff_t nargs, Lisp_Object *args) } #ifdef HAVE_MODULES -/* Create a new module user ptr object. */ +/* Create a new module user ptr object. */ Lisp_Object make_user_ptr (void (*finalizer) (void*), void *p) { diff --git a/src/fns.c b/src/fns.c index 029ac6a83bb..824d96980a0 100644 --- a/src/fns.c +++ b/src/fns.c @@ -2764,8 +2764,9 @@ DEFUN ("require", Frequire, Srequire, 1, 3, 0, If FEATURE is not a member of the list `features', then the feature is not loaded; so load the file FILENAME. If FILENAME is omitted, the printname of FEATURE is used as the file name, -and `load' will try to load this name appended with the suffix `.elc' or -`.el', in that order. The name without appended suffix will not be used. +and `load' will try to load this name appended with the suffix `.elc', +`.el', or the system-dependent suffix for dynamic module files, in that +order. The name without appended suffix will not be used. See `get-load-suffixes' for the complete list of suffixes. If the optional third argument NOERROR is non-nil, then return nil if the file is not found instead of signaling an error. diff --git a/src/lread.c b/src/lread.c index 43100d9f699..bbff21d01d7 100644 --- a/src/lread.c +++ b/src/lread.c @@ -987,7 +987,8 @@ suffix_p (Lisp_Object string, const char *suffix) DEFUN ("load", Fload, Sload, 1, 5, 0, doc: /* Execute a file of Lisp code named FILE. -First try FILE with `.elc' appended, then try with `.el', +First try FILE with `.elc' appended, then try with `.el', then try +with a system-dependent suffix of dynamic modules (see `load-suffixes'), then try FILE unmodified (the exact suffixes in the exact order are determined by `load-suffixes'). Environment variable references in FILE are replaced with their values by calling `substitute-in-file-name'. @@ -999,10 +1000,10 @@ Print messages at start and end of loading unless optional third arg NOMESSAGE is non-nil (but `force-load-messages' overrides that). If optional fourth arg NOSUFFIX is non-nil, don't try adding -suffixes `.elc' or `.el' to the specified name FILE. +suffixes to the specified name FILE. If optional fifth arg MUST-SUFFIX is non-nil, insist on -the suffix `.elc' or `.el'; don't accept just FILE unless -it ends in one of those suffixes or includes a directory name. +the suffix `.elc' or `.el' or the module suffix; don't accept just +FILE unless it ends in one of those suffixes or includes a directory name. If NOSUFFIX is nil, then if a file could not be found, try looking for a different representation of the file by adding non-empty suffixes to @@ -1084,7 +1085,9 @@ Return t if the file exists and loads successfully. */) if (! NILP (must_suffix)) { /* Don't insist on adding a suffix if FILE already ends with one. */ - if (suffix_p (file, ".el") || suffix_p (file, ".elc")) + if (suffix_p (file, ".el") + || suffix_p (file, ".elc") + || suffix_p (file, MODULES_SUFFIX)) must_suffix = Qnil; /* Don't insist on adding a suffix if the argument includes a directory name. */ @@ -1158,9 +1161,7 @@ Return t if the file exists and loads successfully. */) #ifdef HAVE_MODULES if (suffix_p (found, MODULES_SUFFIX)) - { - return Fmodule_load (found); - } + return Fmodule_load (found); #endif /* Check if we're stuck in a recursive load cycle. @@ -4498,10 +4499,11 @@ programs that process this list should tolerate directories both with and without trailing slashes. */); DEFVAR_LISP ("load-suffixes", Vload_suffixes, - doc: /* List of suffixes for (compiled or source) Emacs Lisp files. + doc: /* List of suffixes for Emacs Lisp files and dynamic modules. +This list includes suffixes for both compiled and source Emacs Lisp files. This list should not include the empty string. `load' and related functions try to append these suffixes, in order, -to the specified file name if a Lisp suffix is allowed or required. */); +to the specified file name if a suffix is allowed or required. */); #ifdef HAVE_MODULES Vload_suffixes = list3 (build_pure_c_string (".elc"), build_pure_c_string (".el"), -- 2.39.5