develooper Front page | perl.perl5.porters | Postings from January 2012

XS Typemap documentation and related changes

Thread Next
Steffen Mueller
January 29, 2012 23:33
XS Typemap documentation and related changes
Message ID:
Dear porters,

Before the big feature freeze, I plan to merge (well, 
rebase-rebase-push) a moderately large set of changes to the XS and 
typemap documentation. I set out to document all undocumented and test 
all untested core typemaps a while ago and the aforementioned changeset 
is the result of that effort. Here's what I got:

- Documented and tested several more typemaps.

- Found two typemaps that apparently aren't used anywhere in core or on 
CPAN. Their purpose is undecipherable. I want to remove them from the 
core typemap. More on that below.

- Moved typemap related documentation from perlxs.pod to a new document, 
perlxstypemap.pod, which goes into much more detail and contains a list 
of all core typemaps with their purpose (except for those that I haven't 
managed to cover yet). Very importantly, the documentation contains a 
list of Perl variables that are useful for interpolation into typemaps, 
courtesy of Tony Cook.

At the same time, I continuously applied changes to 
dist/ExtUtils-ParseXS in blead to add better facilities for typemap 
reuse. This means that it's now rather easy to share typemaps between 
CPAN modules. I've wanted to do this for some time now, but my plan to 
rid us of some of the WTF typemaps above has made that a necessity. 
Here's the plan for getting rid of them:

- I release ExtUtils::Typemaps::Excommunicated to the CPAN that contains 
T_DATAUNIT and T_CALLBACK (the latter does not do what you think it does).

- In the SEVERELY unlikely event that any code depends on them, the 
author can do any of the following to work around the removal:

=> Include the two lines of code verbatim in their typemap...

=> Add this to their XS:

   INCLUDE_COMMAND: $^X -MExtUtils::Typemaps::Cmd \
                    -e "print embeddable_typemap(q{Excommunicated})"

I see no good way to have a proper deprecation cycle for these typemaps 
that isn't at least as invasive (adding a mandatory warning to the 
generated code would be as obnoxious, IMO). Let me say again: Not found 
on CPAN. Bizarre code that seems to have served a very specific purpose 
lost in the midst of time.

This changeset is now a smoke-me branch as 
smoke-me/smueller-typemapdocs7. Please speak up if you oppose to any of 
the above.


Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About