WASM examples in the manual

Mailing Lists php.doc
1

Hi,

Some time ago, we added a WASM runner to the manual, to run examples.
All examples have it added. However, not all of them work.

I've been investigating examples and running them with WASM. First how
to build a new WASM file (GitHub - derickr/php-wasm-builder: A Dockerfile and shim to enable running PHP as WASM binary),
and to see how we can add extensions.

Extensions all need to be compiled separately as static libraries.

I've done that for the XML extensions
and mbstring, which increases the WASM PHP binary from 2.7 to 8.5MB.

Secondly, I have created a script that extracts all the
examples and runs them through a separate WASM binary (that I can use
with node) to see if the examples:

a. run (think syntax errors);
b. hang;
c. are missing extensions.

There are going to be a lot of them where having WASM enabled for them
don't make a lot of sense. Especially for category "c". And the category
"b" ones just sit there eat CPU cycles.

Now my question is, should we specifically mark examples (using
<programlisting role="php" annotations="interactive">) or rather mark
them as not runnable (think <programlisting role="php"
annotations="no-wasm">. I am thinking rather the former than the latter,
as there will be so many that won't run (due to missing extensions,
mostly).

I'm inclined to make this opt-in (by havin to add the 'annotations'
attribute. What do you think?

I do have a patch for this coming up, and also one to upgrade the WASM
PHP version from 8.4.0-dev to 8.4.3.

cheers,
Derick

--
https://derickrethans.nl | https://xdebug.org | https://dram.io

Author of Xdebug. Like it? Consider supporting me: Xdebug: Support

mastodon: @derickr@phpc.social @xdebug@phpc.social

2

Hi,

On Tue, Feb 11, 2025 at 7:06 AM Derick Rethans <derick@php.net> wrote:

There are going to be a lot of them where having WASM enabled for them
don't make a lot of sense. Especially for category "c". And the category
"b" ones just sit there eat CPU cycles.

For code examples that run fast or fail fast, I think running them at
each configure.php would have no impact (see below). This leaves the
case of slow ones. Only these I think is necessary to preserve in a
"database" related file, say `wasm-slow.json`, git tracked and side by
side with the runner, to avoid unnecessary slow build times.

The runner, modeled as an stand alone step on configure.php (see, for
example, how script/file-entities.php can be run outside
configure.php), with a option to test all code examples and regenerate
`wasm-slow.json`, may be sufficient.

I'm also planning [1] to move all "PhD stuff" and otherwise
non-building or non-validating related code to run after validation,
and to put all file generations of PhD related files behind a --no-phd
option, so there is no impact for manual editors and translators.

Now my question is, should we specifically mark examples (using
<programlisting role="php" annotations="interactive">) or rather mark
them as not runnable (think <programlisting role="php"
annotations="no-wasm">. I am thinking rather the former than the latter,
as there will be so many that won't run (due to missing extensions,
mostly).

Marking only as annotations="no-wasm", both for slow ones and
extension related ones is the way to go.

But these marikings would be placed only in generated `manual.xml`
files, specifically `doc-base/temp/manual.xml`, and not in individual
source files. This will avoid generating cascading changes on all
translations, and will keep this information, that is specific to WASM
runner version/compilation as an PhD detail, mostly unrelated to what
version is documented in manual sources.

I'm inclined to make this opt-in (by havin to add the 'annotations'
attribute. What do you think?

On `doc-base/temp/manual.xml` generated file, yes. As it will need
changes both in configure.php and PhD, this would also help in movingo
all generated files into `doc-base/temp`, so the PHP manual building
truly becomes idempotent. See "Idempotent" and "Performance/tools" on
the link below.

Best regards,
André L F S Bacci

[1] Manual infra-estructure · Issue #199 · php/doc-base · GitHub

3

On Wed, Feb 12, 2025, at 12:33 PM, André L F S Bacci wrote:

Now my question is, should we specifically mark examples (using
<programlisting role="php" annotations="interactive">) or rather mark
them as not runnable (think <programlisting role="php"
annotations="no-wasm">. I am thinking rather the former than the latter,
as there will be so many that won't run (due to missing extensions,
mostly).

Marking only as annotations="no-wasm", both for slow ones and
extension related ones is the way to go.

But these marikings would be placed only in generated `manual.xml`
files, specifically `doc-base/temp/manual.xml`, and not in individual
source files. This will avoid generating cascading changes on all
translations, and will keep this information, that is specific to WASM
runner version/compilation as an PhD detail, mostly unrelated to what
version is documented in manual sources.

I would strongly recommend at least allowing the value to be specified in the original source, even if defaults are provided in a separate file to ease the job for translators on existing blocks. Going forward, it makes far more sense to let the page author just specify that flag on the code block itself, regardless of whether it's opt-in or opt-out. The only reason to separate it is to minimize jitter for translators, which is fine, but a backward-looking requirement. New pages shouldn't need to deal with that.

--Larry Garfield

4

On 12 February 2025 21:38:12 GMT, Larry Garfield <larry@garfieldtech.com> wrote:

On Wed, Feb 12, 2025, at 12:33 PM, André L F S Bacci wrote:

Now my question is, should we specifically mark examples (using
<programlisting role="php" annotations="interactive">) or rather mark
them as not runnable (think <programlisting role="php"
annotations="no-wasm">. I am thinking rather the former than the latter,
as there will be so many that won't run (due to missing extensions,
mostly).

Marking only as annotations="no-wasm", both for slow ones and
extension related ones is the way to go.

But these marikings would be placed only in generated `manual.xml`
files, specifically `doc-base/temp/manual.xml`, and not in individual
source files. This will avoid generating cascading changes on all
translations, and will keep this information, that is specific to WASM
runner version/compilation as an PhD detail, mostly unrelated to what
version is documented in manual sources.

I would strongly recommend at least allowing the value to be specified in the original source, even if defaults are provided in a separate file to ease the job for translators on existing blocks. Going forward, it makes far more sense to let the page author just specify that flag on the code block itself, regardless of whether it's opt-in or opt-out. The only reason to separate it is to minimize jitter for translators, which is fine, but a backward-looking requirement. New pages shouldn't need to deal with that.

--Larry Garfield

Gina had a good idea on the foundation's slack, and that's likely the approach I'll be taking:

----
Gina Peter Banyard:
Then I would prefer having interactive=yes at a book level and then add some interactive=no at example levels. Changing 1000+ files is not really something I'm in favour of

Derick Rethans:
But yeah, doing it on book level, with overrides makes sense. I'll have a look (later this week
----

This also makes it easier for adding new extensions to run examples for, if we manage to (and decide to) enable more extensions in wasm.

cheers
Derick