DAVEM TPF Grant#3 January, February 2024 report

[Dave Mitchell]

(this report covers two months)

This is my monthly report on work done during Jan,Feb 2024 covered by my
TPF perl core maintenance grant.


I spent the last two months mainly on two goals.

1) Understanding XS better so that I can then decide how to update the XS
ecosystem to better support a reference-counted stack; as an example,
automatically removing the need to call XSUBs via a wrapper in some
circumstances.

Doing this led me down a rabbit hole of realising how awful our current XS
documentation is. Just about every section I read resulted in confusion,
followed by time out to experiment and/or to look at the ParseXS src code
to try to understand what the documentation was trying to tell me. It's
also very out of date: telling us of exciting "new" features introduced 25
years ago.

The net result of this is that I now have about 1000 lines of notes on
"things to fix in the XS docs". I intend sometime soon to completely
revamp perlxs.pod and perlxstut.pod, based on these notes. Which is a bit
of sidetrack from getting XS working better under PERL_RC_STACK builds.
And doing PERL_RC_STACK was itself initially a sidetrack from doing more
work on perl signatures. Such is often the way when working on perl.

2) General small tasks to help get blead into shape for the 5.40 release,
such as analysing and reducing smoke failures, fixing bugs, and fixing any
Deparse regressions that have crept in over the last year.

SUMMARY:
0:38 #21822: BBC: Blead Breaks Variable::Magic
1:20 #21876: BBC: 5.39.7 breaks GONZUS/Cache-utLRU-0.002000.tar.gz
3:21 #21969: clone-with-stack.t crash
2:17 fix Test -deparse failures
1:35 fix minitest failures
3:39 make __LINE__ etc Deparse batter
1:57 make stack reference counted
30:30 make stack reference counted - XS
19:46 process p5p mailbox
1:28 reduce build stderr noise
8:33 reduce smoke failures
------
75:04 TOTAL (HH::MM)

[G.W. Haywood]

Hi there,

Post by Dave Mitchell
(this report covers two months)

I'd been wondering... :)

Post by Dave Mitchell
... rabbit hole of realising how awful our current XS documentation is.

This isn't a rabbit hole. This is good stuff.

Post by Dave Mitchell
... exciting "new" features introduced 25 years ago.

Quite so. It's embarrassing.

Post by Dave Mitchell
... I now have about 1000 lines of notes on "things to fix in the XS
docs". I intend sometime soon to completely revamp perlxs.pod and
perlxstut.pod, based on these notes.

Good man. It desperately needs to be done.

Post by Dave Mitchell
Which is a bit of sidetrack from getting XS working better ...

But it's more important, if you want the work to mean anything in the
longer term. If the documentation is ***@p then after struggling with
it for a few minutes people will just walk away. I've done that many
times with open source software. The main reason I'm still around is
because there's something called the Camel Book, but now the distance
between the Camel Book and reality is increasing and soon all that we
will have for reference will be online documentation. It needs to be
at least as good as the Camel Book was (and I'd be happy to pick nits
with The Book all day - it's far from perfect, but it's on my desk).
Frankly I'm not a fan of online documentation, but if it's bad online
documentation I have a lot less patience with it than I do with paper
because on my paper copy I can write stuff and put those sticky notes
all over the place to use for example as bookmarks. There are dozens
of them in my copy of the Camel Book.

Thank you for your continued excellent efforts.

[p***@tux.freedom.nl]

Post by Dave Mitchell
(this report covers two months)
This is my monthly report on work done during Jan,Feb 2024 covered by my
TPF perl core maintenance grant.
I spent the last two months mainly on two goals.

I can feel the frustration, but in the end, this might be one of the
best net results I have read in your reports. Many will be happy with
the updated docs, including me

THANK YOU!
(also for all the other awesome work)

Post by Dave Mitchell
1) Understanding XS better so that I can then decide how to update the XS
ecosystem to better support a reference-counted stack; as an example,
automatically removing the need to call XSUBs via a wrapper in some
circumstances.
Doing this led me down a rabbit hole of realising how awful our current XS
documentation is. Just about every section I read resulted in confusion,
followed by time out to experiment and/or to look at the ParseXS src code
to try to understand what the documentation was trying to tell me. It's
also very out of date: telling us of exciting "new" features introduced 25
years ago.
The net result of this is that I now have about 1000 lines of notes on
"things to fix in the XS docs". I intend sometime soon to completely
revamp perlxs.pod and perlxstut.pod, based on these notes. Which is a bit
of sidetrack from getting XS working better under PERL_RC_STACK builds.
And doing PERL_RC_STACK was itself initially a sidetrack from doing more
work on perl signatures. Such is often the way when working on perl.
2) General small tasks to help get blead into shape for the 5.40 release,
such as analysing and reducing smoke failures, fixing bugs, and fixing any
Deparse regressions that have crept in over the last year.
0:38 #21822: BBC: Blead Breaks Variable::Magic
1:20 #21876: BBC: 5.39.7 breaks GONZUS/Cache-utLRU-0.002000.tar.gz
3:21 #21969: clone-with-stack.t crash
2:17 fix Test -deparse failures
1:35 fix minitest failures
3:39 make __LINE__ etc Deparse batter
1:57 make stack reference counted
30:30 make stack reference counted - XS
19:46 process p5p mailbox
1:28 reduce build stderr noise
8:33 reduce smoke failures
------
75:04 TOTAL (HH::MM)