As part of my intention to completely revamp the perlxs.pod and
perlxstut.pod documentation, here are a few items for discussion.
--------
1) Whether to make XSUB signatures ANSI by default in perlxs, perlxstut.
Most existing XS code, and all the docs, use the older "K&R" style of XSUB
declaration, which mirrors the old K&R way of declaring C functions:
int
add(x, y)
int x
int y
CODE:
...
For the last 24 years, XS has also supported (via analogy with ANSI C)
"ANSI" style XS declarations:
int
add(int x, int y)
CODE:
...
But no-one uses this newer style because it's not used much in the current
doc examples.
I propose making the emphasis of the docs, and most of the examples,
switch to ANSI.
AFAIK, the new syntax allows you to do just about everything you can with
the old syntax, except include on-the-fly typemapping, which overrides the
default typemap, e.g.:
int
add(x, y)
int x
int y = do_weird_int_munging(SvIV(ST[1]))
CODE:
But since typemaps can now be defined inline within the .xs file via the
TYPEMAP:: <<EOF
mechanism, that seems less of an issue.
The only slightly messy thing about the new syntax is that you have
to have the whole signature on one line, or use \ to split the lines up:
int add(int x, \
int y)
The perlxs.pod text will still describe the old syntax, while
perlxstut.pod won't, apart from a brief mention that it exists (and refer
therm to perlxs.pod), to help people understand older XS code in the wild.
And of course the parser will continue to support the old syntax in the
decades to come.
-------
2) What should the earliest perl and xsubpp version be that the docs
should mention? E.g. remove any mentions of workarounds for 5.005 issues,
or "introduced in 5.003alpha7" type text?
This affects people who are writing new XS code with the intention that is
still capable of being installed on old perl installations. here, the
(modern) docs are telling them "don't use feature X if you want your XS
code to to run on 5.005 platforms" (or whatever).
And relatedly, what should be the earliest format version of XS file that
the current xsubpp should support? Currently the latest Extutils::ParseXS
and xsubpp script can (in principle) be installed on 5.6.0 perl. In
addtion, the current parser is capable of recognising older XS code and
injkect workarounds for things that have changed in the meantime.
Should we continue including various hacks and workarounds in the parser
to handle ancient .xs files? Assuming there are any such hacks - I'm not
too sure. But if we formally declare that 5.6.0 (for example) is the
minimum, then I can remove any such hack I might come across. Similalry,
what is the oldest perl we should support the current Extutils::ParseXS
running on?
For all of these, I'm leaning towards 5.8.0.
-------
3) Whether to replace the rpcb_gettime() example used a million times in
perlxs.pod with some other example library function, since this function
is no longer common, and won't work out of the box on my linux system (I'd
have to install non-default libraries and header functions).
I.e. unless someone has any strong attachment to it, I'll use something
else, or maybe use an hypothetical function rather than real one.
-------
4) Whether to make h2xs inject "PROTOTYPES: FALSE" into the .xs file when
creating a new skeleton distribution.
By default, xsubpp doesn't generate perl prototypes for the XSUBs that get
inserted into the perl namespace. (It will if the .xs file includes
"PROTOTYPES: TRUE" near the top.)
But the XS parser, xsubpp, will generate a warning if PROTOTYPES isn't
specified one way or another.
These days we generally regard adding a function prototype to be a
mistake, unless someone is explicitly trying to emulate a perl-builtin
(e.g. using '&' as part of a prototype for a mymap() function).
So I propose that h2xs be made to add "PROTOTYPES: FALSE" into the
skeleton .xs file that it generates, since this will be the useful default
99% of the time. (That keyword has been available since 1995).
-------
5) Whether to make h2xs inject '#define PERL_REENTRANT' into the .xs file
when creating a new skeleton distribution. (Possibly only if the version
arg passed to h2xs is >= 5.16)?
This macro has been available since 5.16.0, and I assume it is a NOOP on
earlier perls. It sounds like setting it by default is probably a Good
Thing, rather than having someone write their XS code, *then* find out
later it has a race condition under threads, *then* find the section in
perlxs which recommends setting it. I don't know whether there are any
downsides to setting by default.
--
Never do today what you can put off till tomorrow.
perlxstut.pod documentation, here are a few items for discussion.
--------
1) Whether to make XSUB signatures ANSI by default in perlxs, perlxstut.
Most existing XS code, and all the docs, use the older "K&R" style of XSUB
declaration, which mirrors the old K&R way of declaring C functions:
int
add(x, y)
int x
int y
CODE:
...
For the last 24 years, XS has also supported (via analogy with ANSI C)
"ANSI" style XS declarations:
int
add(int x, int y)
CODE:
...
But no-one uses this newer style because it's not used much in the current
doc examples.
I propose making the emphasis of the docs, and most of the examples,
switch to ANSI.
AFAIK, the new syntax allows you to do just about everything you can with
the old syntax, except include on-the-fly typemapping, which overrides the
default typemap, e.g.:
int
add(x, y)
int x
int y = do_weird_int_munging(SvIV(ST[1]))
CODE:
But since typemaps can now be defined inline within the .xs file via the
TYPEMAP:: <<EOF
mechanism, that seems less of an issue.
The only slightly messy thing about the new syntax is that you have
to have the whole signature on one line, or use \ to split the lines up:
int add(int x, \
int y)
The perlxs.pod text will still describe the old syntax, while
perlxstut.pod won't, apart from a brief mention that it exists (and refer
therm to perlxs.pod), to help people understand older XS code in the wild.
And of course the parser will continue to support the old syntax in the
decades to come.
-------
2) What should the earliest perl and xsubpp version be that the docs
should mention? E.g. remove any mentions of workarounds for 5.005 issues,
or "introduced in 5.003alpha7" type text?
This affects people who are writing new XS code with the intention that is
still capable of being installed on old perl installations. here, the
(modern) docs are telling them "don't use feature X if you want your XS
code to to run on 5.005 platforms" (or whatever).
And relatedly, what should be the earliest format version of XS file that
the current xsubpp should support? Currently the latest Extutils::ParseXS
and xsubpp script can (in principle) be installed on 5.6.0 perl. In
addtion, the current parser is capable of recognising older XS code and
injkect workarounds for things that have changed in the meantime.
Should we continue including various hacks and workarounds in the parser
to handle ancient .xs files? Assuming there are any such hacks - I'm not
too sure. But if we formally declare that 5.6.0 (for example) is the
minimum, then I can remove any such hack I might come across. Similalry,
what is the oldest perl we should support the current Extutils::ParseXS
running on?
For all of these, I'm leaning towards 5.8.0.
-------
3) Whether to replace the rpcb_gettime() example used a million times in
perlxs.pod with some other example library function, since this function
is no longer common, and won't work out of the box on my linux system (I'd
have to install non-default libraries and header functions).
I.e. unless someone has any strong attachment to it, I'll use something
else, or maybe use an hypothetical function rather than real one.
-------
4) Whether to make h2xs inject "PROTOTYPES: FALSE" into the .xs file when
creating a new skeleton distribution.
By default, xsubpp doesn't generate perl prototypes for the XSUBs that get
inserted into the perl namespace. (It will if the .xs file includes
"PROTOTYPES: TRUE" near the top.)
But the XS parser, xsubpp, will generate a warning if PROTOTYPES isn't
specified one way or another.
These days we generally regard adding a function prototype to be a
mistake, unless someone is explicitly trying to emulate a perl-builtin
(e.g. using '&' as part of a prototype for a mymap() function).
So I propose that h2xs be made to add "PROTOTYPES: FALSE" into the
skeleton .xs file that it generates, since this will be the useful default
99% of the time. (That keyword has been available since 1995).
-------
5) Whether to make h2xs inject '#define PERL_REENTRANT' into the .xs file
when creating a new skeleton distribution. (Possibly only if the version
arg passed to h2xs is >= 5.16)?
This macro has been available since 5.16.0, and I assume it is a NOOP on
earlier perls. It sounds like setting it by default is probably a Good
Thing, rather than having someone write their XS code, *then* find out
later it has a race condition under threads, *then* find the section in
perlxs which recommends setting it. I don't know whether there are any
downsides to setting by default.
--
Never do today what you can put off till tomorrow.