Remove the "preview" status from the loaded object feature

Add an ABI version both to the header file and passed to the setup
function.  Unfortunately this itself is an ABI break and I couldn't
find a good way to avoid it.

* NEWS: Announce the ABI is not a preview and the incompatibility.
* doc/make.texi: Remove the preview warnings for object loading.
Document the new ABI version argument.
* src/gnumake.h (GMK_ABI_VERSION): Set the ABI version to 1.
Add comments documenting the format of the setup function.
* src/load.c (setup_func_t): Rename from load_func_t.
(load_file): Pass the ABI version to the setup function.
* tests/scripts/features/load: Rework the setup function.
* tests/scripts/features/loadapi: Ditto.

3 files changed, 24 insertions, 11 deletions

diff --git a/src/gnumake.h b/src/gnumake.h
index b437db75..3ebe6621 100644
--- a/src/gnumake.h
+++ b/src/gnumake.h
@@ -1,5 +1,4 @@
 /* External interfaces usable by dynamic objects loaded into GNU Make.
-   --THIS API IS A "TECHNOLOGY PREVIEW" ONLY.  IT IS NOT A STABLE INTERFACE--
 
 Copyright (C) 2013-2023 Free Software Foundation, Inc.
 This file is part of GNU Make.
@@ -19,6 +18,8 @@ this program.  If not, see <https://www.gnu.org/licenses/>.  */
 #ifndef _GNUMAKE_H_
 #define _GNUMAKE_H_
 
+#define GMK_ABI_VERSION 1
+
 /* Specify the location of elements read from makefiles.  */
 typedef struct
   {
@@ -28,6 +29,14 @@ typedef struct
 
 typedef char *(*gmk_func_ptr)(const char *nm, unsigned int argc, char **argv);
 
+/* When an object is loaded by GNU Make, a setup method will be invoked.
+   The name of the method is either derived from the filename of the object,
+   or specified explicitly in the makefile.  It has the signature:
+
+     int <setup_fn> (unsigned int abi_version, const gmk_floc *flocp);
+
+   The abi_version will be set to GMK_ABI_VERSION.  */
+
 #ifdef _WIN32
 # ifdef GMK_BUILDING_MAKE
 #  define GMK_EXPORT  __declspec(dllexport)
@@ -38,7 +47,7 @@ typedef char *(*gmk_func_ptr)(const char *nm, unsigned int argc, char **argv);
 # define GMK_EXPORT
 #endif
 
-/* Free memory returned by the gmk_expand() function.  */
+/* Free memory returned by the gmk_expand() and gmk_free() functions.  */
 GMK_EXPORT void gmk_free (char *str);
 
 /* Allocate memory in GNU Make's context.  */
diff --git a/src/load.c b/src/load.c
index 91200dfa..519ec010 100644
--- a/src/load.c
+++ b/src/load.c
@@ -44,12 +44,14 @@ struct load_list
 
 static struct load_list *loaded_syms = NULL;
 
-static load_func_t
+typedef int (*setup_func_t)(unsigned int abi, const floc *flocp);
+
+static setup_func_t
 load_object (const floc *flocp, int noerror, const char *ldname,
              const char *symname)
 {
   static void *global_dl = NULL;
-  load_func_t symp;
+  setup_func_t symp;
 
   if (! global_dl)
     {
@@ -61,7 +63,7 @@ load_object (const floc *flocp, int noerror, const char *ldname,
         }
     }
 
-  symp = (load_func_t) dlsym (global_dl, symname);
+  symp = (setup_func_t) dlsym (global_dl, symname);
   if (! symp)
     {
       struct load_list *new;
@@ -93,13 +95,13 @@ load_object (const floc *flocp, int noerror, const char *ldname,
       DB (DB_VERBOSE, (_("Loaded shared object %s\n"), ldname));
 
       /* Assert that the GPL license symbol is defined.  */
-      symp = (load_func_t) dlsym (dlp, "plugin_is_GPL_compatible");
+      symp = (setup_func_t) dlsym (dlp, "plugin_is_GPL_compatible");
       if (! symp)
         OS (fatal, flocp,
              _("loaded object %s is not declared to be GPL compatible"),
              ldname);
 
-      symp = (load_func_t) dlsym (dlp, symname);
+      symp = (setup_func_t) dlsym (dlp, symname);
       if (! symp)
         {
           const char *err = dlerror ();
@@ -129,7 +131,7 @@ load_file (const floc *flocp, struct file *file, int noerror)
   char *symname = NULL;
   const char *fp;
   int r;
-  load_func_t symp;
+  setup_func_t symp;
 
   /* Break the input into an object file name and a symbol name.  If no symbol
      name was provided, compute one from the object file name.  */
@@ -210,8 +212,11 @@ load_file (const floc *flocp, struct file *file, int noerror)
   if (! symp)
     return 0;
 
-  /* Invoke the symbol.  */
-  r = (*symp) (flocp);
+  /* Invoke the setup function.  */
+  {
+    unsigned int abi = GMK_ABI_VERSION;
+    r = (*symp) (abi, flocp);
+  }
 
   /* If the load didn't fail, add the file to the .LOADED variable.  */
   if (r)
diff --git a/src/makeint.h b/src/makeint.h
index f34ec361..ce5c8452 100644
--- a/src/makeint.h
+++ b/src/makeint.h
@@ -672,7 +672,6 @@ const char *strcache_add_len (const char *str, size_t len);
 int guile_gmake_setup (const floc *flocp);
 
 /* Loadable object support.  Sets to the strcached name of the loaded file.  */
-typedef int (*load_func_t)(const floc *flocp);
 int load_file (const floc *flocp, struct file *file, int noerror);
 int unload_file (const char *name);