Re: IMPORTANT: Macros in top-level .h files are no longer by default visible outside core

On 12/11/25 05:21, Eric Herman wrote:
> 
> On 2025-12-10 23:48, Karen Etheridge wrote:
>>
>>     ... which went into blead on Dec 10 2025 (v5.43.5-56-g92dcf59a90),
>>     meaning these changes will become visible in development release
>>     perl-5.43.6 scheduled for Dec 20.
>>
>>
>> Ah, I love the smell of BBC reports in the morning.. just in time for 
>> Christmas! :)
> 
> Indeed! :D
> 
> But keep your eyes peeled, as they may slip by us as "UNKNOWN" and not 
> "FAIL", as described here:
> 
> https://github.com/Perl/perl5/issues/23918
> 

That commit isn't going to cause any BBCs.

Let me explain how it works.  For your code to use Perl, it needs to

  #include "perl.h"

The change I made is just before perl.h returns, it #undefs all the 
symbols we don't want your code to see.

There is an algorithm to examine the perl source to decide which things 
to #undef.  But there also is a list of symbols that are exempt from 
this #undeffing.  That list was set in that commit so that everything 
the algorithm identified to #undef was placed in the list, so that 
nothing actually got #undefed, so there is no change in what is 
available to modules.

The main goal is to use the algorithm for future symbols, so that we 
don't break anything, but now are finally in charge of our destiny, as 
it were.  Flaws in the algorithm will be identified for new stuff, that 
no one is using as of now.

And it already has had a positive effect.  I have a WIP in which I am 
adding a quick little macro.  This commit caused that macro to not be 
seen by XS code that called an existing macro that had been changed to 
call the new one, so that code failed to compile.  That encouraged me to 
document the new macro in perlintern (a quick one-liner was all that was 
needed) and then the algorithm recognized the new macro and everything 
compiles.  So, we got an entry in perlintern that I otherwise would not 
have bothered with, but which took me less than 5 extra minutes to do.

A subsidiary goal is to remove from public view macros that really 
shouldn't be exposed.  Or to rename the ones that could easily conflict 
with names someone else is likely to select.  This is where BBC's can 
arise.  That pull request had a couple of commits along those lines. 
But I chose them to be ones that it is very unlikely someone else would 
be using.  We'll see.

It would be good for the project to whittle the exemption list down from 
its > 3000 current entries.  But we can choose what and when to do that. 
  As we get closer to the next dot 0 release date, we might defer all 
work on it to the beginning of the next yearly cycle.  Or if we make a 
lot of mistakes, and have to do a bunch of reverts, we might decide to 
skip any more whittling forever.

But in a clean project, that list would be empty.  Every item on it 
represents some sort of failure, one could argue.  The failure could be 
my new algorithm misidentifying something being visible that isn't, or 
failing to find documentation that exists.  Indeed there are cases where 
it is doing that.  But most of the entries on that list are legitimate; 
they are symbols that we haven't documented and are cluttering up your 
code's namespace.

This new mechanism, somewhat paradoxically, gives freedom, and imposes 
discipline.  The freedom comes in that I can create any old symbol in a 
header file without fear of its name inadvertently conflicting with some 
current code, unless that symbol needs to be visible to such code.  The 
discipline is that I now have to take steps to announce this new symbol 
so that it can be used by the outside world.  That announcement should 
come in the form of a bit of documentation.  I wish we had had something 
like this a long time ago.  I've been working in the core for a long 
time now, and I still frequently stumble upon some useful macro whose 
existence I had not known about because no one had bothered to document it.