Re: Making the libguile API explicit

[Dirk Herrmann]

On Tue, 5 Jun 2001, Martin Grabmueller wrote:

> For these two reason, I propose that we make the API more explicit by
> creating a new CPP macro
> 
>   SCM_API
> 
> which is to be written in front of each function prototype in the
> headers.  It will be defined as follows:
> 
> #if __GUILE_EXPORT__
> # define SCM_API __declspec (dllexport)
> #elif __GUILE_IMPORT__
> # define SCM_API __declspec (dllimport)
> #else
> # define SCM_API
> #endif
> 
> Example (in the header file):
> 
> SCM_API extern SCM scm_acons (SCM w, SCM x, SCM y); 
> 
> This definition will serve the two purposes described above:
> 
> 1. Users can check whether functions are defined with SCM_API in the
>    headers, and if they are, they can use them.
> 
> 2. Windows compilers can create proper export lists for Windows.

I wonder whether it makes sense to combine these two purposes in _one_
macro.  In other words, I suspect there are situations where you would
like to have definitions exported to the DLL, but still don't want them to
be part of the API.  Think, for example, of shared libraries that are part
of the guile core (and thus are allowed to use internal functions):  For
these you need to be able to export definitions that are considered
'internal'.  Further, your SCM_API trick only applies to functions, it
does not work for macros.  Further, it adds redundancy, since we have
decided that (in the long term) every function or macro that does not have
a SCM_I_ or scm_i_ prefix belongs to the API.

IMO the better approach is to 

* First, detect non-API stuff in the header files.

* Second, if possible, put non-API stuff into the corresponding .c files
  and make it static.

* Third, rename the remaining non-API stuff using the SCM_I_ and scm_i_
  prefixes.

Note that the first part is the most difficult, since it requires us to
take _decisions_ :-)  The rest is basically mechanical stuff, not much
more complicated than your SCM_API idea.

What I like about your suggestion, however, is the idea that we have a way
to mark stuff that has been decided to be positively part of the
API.  But, IMO this should rather be indicated by a comment like /* API */
which has the advantage that it also works for macros, type declarations
and so on.

With respect to the possibility to make the headers windows aware:  I
don't know anything about development on windows, so I cant't comment on
it except for the point that we should treat different issues
separately.  I. e. don't mix windows DLL macro magic with decisions about
the API.

Best regards,
Dirk Herrmann