My understanding has always been: m_pd.h is public and generally shouldn't change without some sort of compatibility coverage. Anything other .h is private. I wrote d_soundfile.h and s_net.h as private headers, but they could be included in m_pd.h to make them public for example. We could add commenting marking them as such.
On Aug 21, 2021, at 5:03 AM, pd-dev-request@lists.iem.at wrote:
Well, I've never been able to articulate a clear and complete policy... Roughly speaking, I'm maintaining source and binary compatibility for anything that uses the public API (m_pd.h) and trying not to break things that use private APIs (g_vanas.h, s_stuff.h and, privater still, m_imp.h"). Meanwhile there's a profusion of ".h" files I didn't write (d_soundfile.h, g_all_guis.h, etc) that I've never formed a policy for.
-------- Dan Wilcox @danomatika http://twitter.com/danomatika danomatika.com http://danomatika.com/ robotcowboy.com http://robotcowboy.com/
My understanding has always been: m_pd.h is public and generally shouldn't change without some sort of compatibility coverage. Anything other .h is private.
That's the theory. On the other hand, many functions/variables in "g_all_guis.h", "s_stuff.h" and "m_imp.h" are marked as "EXTERN" (which on Windows resolves to a DLL import/export!). If those functions are really private, why are they EXTERN?
Another problem is that Pd by default exports all symbols, so people can easily use functions that are not explicitely exported or even declared in a header (by providing their own forward declaration).
It would help if we would only explicitly export functions/variables that are meant to be used by externals or libpd clients and hide everything else. (See https://github.com/pure-data/pure-data/issues/569). We can still have different policies for different header files ("m_pd.h" is the stable API and everything else is "use at your own risk").
As a side note: libpd actually depends on the private API because some essential functions, like sys_pollgui() resp. sys_microsleep(), are not part of "m_pd.h". I guess we should think which functions are necessary for libpd, so we can stabilize them and move them to "m_pd.h".
Christof
On 21.08.2021 12:55, Dan Wilcox wrote:
My understanding has always been: m_pd.h is public and generally shouldn't change without some sort of compatibility coverage. Anything other .h is private. I wrote d_soundfile.h and s_net.h as private headers, but they could be included in m_pd.h to make them public for example. We could add commenting marking them as such.
On Aug 21, 2021, at 5:03 AM, pd-dev-request@lists.iem.at mailto:pd-dev-request@lists.iem.at wrote:
Well, I've never been able to articulate a clear and complete policy... Roughly speaking, I'm maintaining source and binary compatibility for anything that uses the public API (m_pd.h) and trying not to break things that use private APIs (g_vanas.h, s_stuff.h and, privater still, m_imp.h"). Â Meanwhile there's a profusion of ".h" files I didn't write (d_soundfile.h, g_all_guis.h, etc) that I've never formed a policy for.
Dan Wilcox @danomatika http://twitter.com/danomatika danomatika.com http://danomatika.com robotcowboy.com http://robotcowboy.com
Pd-dev mailing list Pd-dev@lists.iem.at https://lists.puredata.info/listinfo/pd-dev
On Sat, Aug 21, 2021 at 01:32:10PM +0200, Christof Ressi wrote:
My understanding has always been: m_pd.h is public and generally shouldn't change without some sort of compatibility coverage. Anything other .h is private.
That's the theory. On the other hand, many functions/variables in "g_all_guis.h", "s_stuff.h" and "m_imp.h" are marked as "EXTERN" (which on Windows resolves to a DLL import/export!). If those functions are really private, why are they EXTERN?
So that you can write stuff that uses them, if you need to, with the understanding that your code might have to be revised in the future.
Another problem is that Pd by default exports all symbols, so people can easily use functions that are not explicitely exported or even declared in a header (by providing their own forward declaration).
It would help if we would only explicitly export functions/variables that are meant to be used by externals or libpd clients and hide everything else. (See https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_pure-2Ddata_... ). We can still have different policies for different header files ("m_pd.h" is the stable API and everything else is "use at your own risk").
As a side note: libpd actually depends on the private API because some essential functions, like sys_pollgui() resp. sys_microsleep(), are not part of "m_pd.h". I guess we should think which functions are necessary for libpd, so we can stabilize them and move them to "m_pd.h".
Yep. I believe libpd ships with a fixed version of Pd (0.51 ATM). The z_ files are now also distributed as part of Pd so that the libpd "c" bindings are now part of vanilla (and indeed I had to modify them). I believe the libpd maintainers can switch to using Pd's z_ files now so that they don't have any more dependencies outside m_pd.h.
cheers M
Christof
On 21.08.2021 12:55, Dan Wilcox wrote:
My understanding has always been: m_pd.h is public and generally shouldn't change without some sort of compatibility coverage. Anything other .h is private. I wrote d_soundfile.h and s_net.h as private headers, but they could be included in m_pd.h to make them public for example. We could add commenting marking them as such.
On Aug 21, 2021, at 5:03 AM, pd-dev-request@lists.iem.at mailto:pd-dev-request@lists.iem.at wrote:
Well, I've never been able to articulate a clear and complete policy... Roughly speaking, I'm maintaining source and binary compatibility for anything that uses the public API (m_pd.h) and trying not to break things that use private APIs (g_vanas.h, s_stuff.h and, privater still, m_imp.h"). Â Meanwhile there's a profusion of ".h" files I didn't write (d_soundfile.h, g_all_guis.h, etc) that I've never formed a policy for.
Dan Wilcox @danomatika <https://urldefense.proofpoint.com/v2/url?u=http-3A__twitter.com_danomatika&a... > danomatika.com <https://urldefense.proofpoint.com/v2/url?u=http-3A__danomatika.com&d=DwI... > robotcowboy.com <https://urldefense.proofpoint.com/v2/url?u=http-3A__robotcowboy.com&d=Dw... >
Pd-dev mailing list Pd-dev@lists.iem.at https://urldefense.proofpoint.com/v2/url?u=https-3A__lists.puredata.info_lis...
Pd-dev mailing list Pd-dev@lists.iem.at https://urldefense.proofpoint.com/v2/url?u=https-3A__lists.puredata.info_lis...
-
Christof Ressi -
Dan Wilcox -
Miller Puckette