Re: epicsExportShared symbols

["Johnson, Andrew N. via Core-talk" <core-talk at aps.anl.gov>]

Hi Mark,

The _API pattern is probably simpler overall, but it does need a separate header file for each DLL. The makeAPIheader.pl script explains how to use it, just run it with a -h flag for instructions.

Since you’re looking tor this to work with older versions of Base though I suggest you run the makeAPIheader.pl script by hand from Base-7.0.4 to create each *API.h file but then add the output file to your repo in the appropriate Makefile and directory. You should not set the API_HEADER or *_API variables in that Makefile though as the help text suggests.

The other part is that you need to add some rules to the end of the Makefile where the library gets built, which I think for asyn would be this:

$(LIB_PREFIX)asyn$(LIB_SUFFIX): USR_CPPFLAGS += -DBUILDING_asyn_API

ifeq ($(SHARED_LIBRARIES),YES)

  $(SHRLIB_PREFIX)asyn$(SHRLIB_SUFFIX): USR_CPPFLAGS += -DBUILDING_asyn_API

endif

I’m not sure if the LIB_PREFIX line is needed or not, but it won’t do any harm. If you were building a loadable library you’d need to add another line as well, but that’s only for creating plugins for other tools or languages.

HTH,

- Andrew

On Aug 11, 2020, at 11:27 AM, Michael Davidsaver <mdavidsaver at gmail.com> wrote:

On 8/11/20 9:06 AM, Mark Rivers wrote:

I note that in the comments at the beginning of shareLib.h in base 7.0.4 says that this construct is deprecated:

*     #ifdef epicsExportSharedSymbols
*     #   define interfacePDQ_epicsExportSharedSymbols
*     #   undef epicsExportSharedSymbols
*     #endif
*
*     #include "epicsTypes.h"
*     #include "epicsTime.h"
*
*     #ifdef interfacePDQ_epicsExportSharedSymbols
*     #   define epicsExportSharedSymbols
*     #   include "shareLib.h"
*     #endif
*
*     epicsShareFunc int myExtFunc ( int arg );
*     epicsShareExtern int myExtVar;
*     class epicsShareClass myClass {};mechanism being used in pvAccess, 

However, that construct is still used in pvAccess, pvDatabase, normativeTypes, and pvaClient.

It seems to me that this construct has an advantage over the one that is preferred in shareLib.h.  

Let's say I add a new dependency on EPICS base to myClass.h, for example epicsMutex.h.  It seems to me that with the preferred mechanism I must modify all .cpp files that include myClass.h to first include epicsMutex.h before defining epicsExportSharedSymbols and including myClass.h.  Otherwise myClass.h will end up exporting epicsMutex functions.  With the deprecated mechanism this is not necessary, and my .cpp files don't even need to include epicsMutex.h at all.

Am I missing something?

The undef epicsExportSharedSymbols pattern can work, if you're consistent.
Unfortunately, working as I do primarily on Linux, where there is no need
to be consistent, it is easy for ordering issues to slip in.  And I find
sorting them out to be quite tedious.

If you prefer the *_API pattern, then you don't need to worry about these
sort of header ordering issues.  This entire class of potential problems
is avoided.

eg. I started this way with my new PVXS module, and have had a much easier
time in porting to Windows.  No mysterious missing symbols showing up in
my appveyor builds.

Mark

-----Original Message-----
From: Michael Davidsaver <mdavidsaver at gmail.com> 
Sent: Tuesday, August 11, 2020 9:29 AM
To: Mark Rivers <rivers at cars.uchicago.edu>; Johnson, Andrew N. <anj at anl.gov>
Cc: core-talk at aps.anl.gov
Subject: Re: epicsExportShared symbols

On 8/11/20 6:18 AM, Mark Rivers via Core-talk wrote:

Hi Andrew,


I am trying to figure out the best way to clean up my code (asyn, areaDetector, etc.) to handle the __declspec DLL_EXPORT/IMPORT stuff.


I posted a comment to this thread in ADCore about it just now:

https://github.com/areaDetector/ADCore/issues/455#issuecomment-6719337
86


It looks like EPICS base 7.0.4 has 2 ways of doing it, for example using LIBCOM_API/LIBCA_API, or the more traditional epicsShareFunc and epicsExportSharedSymbols (e.g. in pvAccess).


I did a "git grep LIBCOM_API" and I cannot actually figure out where LIBCOM_API is defined and how that mechanism works.  Can you explain?


Does the LIBCA_API mechanism rely on anything in base 7, or can it be used with older versions of base?

Since the _API macros are my initiative, I'll answer this one.
For a support module, you might be better to start looking at the pva2pva module, which is where I tried the idea before changing Base.

https://github.com/epics-base/pva2pva/blob/master/pdbApp/pv/qsrv.h#L21-L37

With Base 7.0.4, this sort of header is generated by makeAPIheader.pl to avoid repetition. This did involve some Makefile changes to account for dependency issues with use of a generated header by basically every object file.

https://github.com/epics-base/epics-base/blob/7.0/src/tools/makeAPIheader.pl

-- 

Complexity comes for free, simplicity you have to work for.