emacs-diffs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Emacs-diffs] master e7caf9c 1/2: * src/emacs-module.c: Add instructions


From: Philipp Stephani
Subject: [Emacs-diffs] master e7caf9c 1/2: * src/emacs-module.c: Add instructions how to change the module API
Date: Thu, 18 Apr 2019 17:19:44 -0400 (EDT)

branch: master
commit e7caf9c744118910163ec452a05a5b90d6398755
Author: Philipp Stephani <address@hidden>
Commit: Philipp Stephani <address@hidden>

    * src/emacs-module.c: Add instructions how to change the module API
---
 src/emacs-module.c | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/src/emacs-module.c b/src/emacs-module.c
index 09a768e..fd033e8 100644
--- a/src/emacs-module.c
+++ b/src/emacs-module.c
@@ -17,6 +17,54 @@ GNU General Public License for more details.
 You should have received a copy of the GNU General Public License
 along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.  */
 
+/*
+The public module API is defined in the header emacs-module.h.  The
+configure script generates emacs-module.h from emacs-module.h.in and
+the version-specific environment fragments in module-env-*.h.
+
+If you want to change the module API, please abide to the following
+rules:
+
+- Don't remove publicly documented declarations from the headers.
+
+- Don't remove, reorder, or rename structure fields, as such changes
+  break ABI compatibility.
+
+- Don't change the types of structure fields.
+
+- Add structure fields only at the end of structures.
+
+- For every Emacs major version there is a new fragment file
+  module-env-VER.h.  Add functions solely at the end of the fragment
+  file for the next (not yet released) major version of Emacs.  For
+  example, if the current Emacs release is 26.2, add functions only to
+  emacs-env-27.h.
+
+- emacs-module.h should only depend on standard C headers.  In
+  particular, don't include config.h or lisp.h from emacs-module.h.
+
+- Prefix all names in emacs-module.h with "emacs_" or "EMACS_".
+
+To add a new module function, proceed as follows:
+
+1. Add a new function pointer field at the end of the emacs-env-*.h
+   file for the next major version of Emacs.
+
+2. Run config.status or configure to regenerate emacs-module.h.
+
+3. Create a corresponding implementation function in this file.  See
+   "Implementation of runtime and environment functions" below for
+   further rules.
+
+4. Assign the new field in the initialize_environment function.
+
+5. Add a test function that calls your new function to
+   test/data/emacs-module/mod-test.c.  Add a unit test that invokes
+   your new test function to test/src/emacs-module-tests.el.
+
+6. Document your new function in the manual and in etc/NEWS.
+*/
+
 #include <config.h>
 
 #include "emacs-module.h"



reply via email to

[Prev in Thread] Current Thread [Next in Thread]