gh-126187 Add emscripten.py script to automate emscripten build

[hoodmane]

This is modeled heavily on Tools/wasm/wasi.py. I tested it manually, hopefully we can soon use it as the basis for an Emscripten build bot.

There are a few hacks to work around problems. I prioritized adding a script that works as soon as possible without changing other files over making it non-hacky. I will clean it up in followup.

cc @freakboy3742.

• Issue: Provide a script to create a complete emscripten build #126187

[brettcannon]

@freakboy3742 can you add yourself to CODEOWNERS for Tools/wasm?

[mdboom]

Just tested this locally and it WFM [tm].

We should probably also update the instructions in Tools/wasm/README.md, which still point to the old script for building with emscripten.

[bedevere-app]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[freakboy3742]

@freakboy3742 can you add yourself to CODEOWNERS for Tools/wasm?

Done in #126210.

[freakboy3742]

The script itself looks great; a couple of minor formatting things that are likely the result of automated tooling.

As noted in another review, this needs at least some documentation for how to use it. The Tools/wasm/README.md contains a big section that would now seem to be largely redundant; so I'm inclined to suggest making that cleanup (or, at least, starting that cleanup) part of this PR.

The other question (which is a "how can we make @brettcannon's life easier" question). Do we want to - or even, can we - migrate the Emscripten-specific stuff into the Tools/wasm/emscripten folder? AIUI, the complicating factor here is that there is enough WASI tooling that is dependent on the Tools/wasm location, so moving that stuff to Tools/wasm/wasi isn't an option - so maybe a depth-based reorg isn't possible and keeping everything in Tools/wasm is fine. Any thoughts, @brettcannon?

[hoodmane]

Do we want to - or even, can we - migrate the Emscripten-specific stuff into the Tools/wasm/emscripten folder?

I believe we can. My thought was to put emscripten.py in Tools/wasm/emscripten and try to move everything else Emscripten-specific into the folder. Open to other approaches.

[brettcannon]

the complicating factor here is that there is enough WASI tooling that is dependent on the Tools/wasm location, so moving that stuff to Tools/wasm/wasi isn't an option

I've been thinking about it and if we are okay leaving Tools/wasm/wasi.py there for a while (like 5 releases), we can make a Tools/wasm/wasi/ directory and I can change wasi.py to call into the code in that directory (where I would probably drop a __main__.py into so it can be executed). Then I can have Tools/wasm/wasi.py raise a warning to direct people to update their stuff.

Does that sound like a reasonable plan?

[hoodmane]

So in that case, I should put all new Emscripten files including this one under the emscripten subfolder?

If there's a __main__.py file, does that mean you expect people to invoke it like python -m Tools.wasm.wasi? If you are in the directory, python -m . doesn't work, so you would have to say python __main__.py? Unless I'm misunderstanding, I'd say that python Tools/wasm/wasi.py and having the helper files in the wasi subdirectory makes more sense to me personally. But if there is a way to set it up so that the cli usage isn't too weird it sounds fine.

[freakboy3742]

So in that case, I should put all new Emscripten files including this one under the emscripten subfolder?

If there's a __main__.py file, does that mean you expect people to invoke it like python -m Tools.wasm.wasi? If you are in the directory, python -m . doesn't work, so you would have to say python __main__.py? Unless I'm misunderstanding, I'd say that python Tools/wasm/wasi.py and having the helper files in the wasi subdirectory makes more sense to me personally. But if there is a way to set it up so that the cli usage isn't too weird it sounds fine.

Whether the entry point is spelled python -m tools.wasm.wasi, python Tools/wasm/wasi.py, or something else entirely bother me. It's a script that will be used by such a small group of people that as long as it's documented, and the end-user ergonomics don't completely suck, I'm not sure it matters much.

My primary concern is getting separation between WASI- and Emscripten-specific code so that we can have confidence that a change to one target isn't going to impact the other (and, from a basic operational perspective, that CODEOWNERS notifications are accurately addressed).

[freakboy3742]

...and realising that I didn't actually answer the specific question - yes, I would argue for putting this script into an emscripten subfolder.

[brettcannon]

If there's a __main__.py file, does that mean you expect people to invoke it like python -m Tools.wasm.wasi?

Nope, I expect python Tools/wasm/wasi (you can point Python at a directory that has a __main__.py).

[hoodmane]

I updated the readme to reflect the changes. There's more readme updates I want to make but it's enough mixed up with changes I've left to future PRs that I think it's better to include with that later work.

[mdboom]

Thanks for the README changes. I see that this also closes #126201 now, which is great.

[hoodmane]

Thanks for the grammar fixes @mdboom.

[freakboy3742]

One Q about the docs, and one bug caused by the directory change.

[freakboy3742]

Any reason to nominate 3.1.68 specifically, rather than latest? I'm a little wary of putting a "magic number" into documentation unless that number is a minimum (like 3.1.42 above) or a pinned version of some significance.

[hoodmane]

Okay, I'll put latest for now and when we add actual CI I'll switch it to the specific version used in CI.

[freakboy3742]

Out of interest - how stable/backwards compatible is "latest"? Is the emscripten version analogous to the manylinux tag/macOS dev version for compatibility purposes? Or is this a situation where we'll pick a specific emscripten version for all versions of a Python release (i.e., all 3.14.x releases are Emscripten 3.1.68)?

[hoodmane]

If we care about abi compatibility the safe way to go is to fix a version.

[bedevere-app]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[hoodmane]

Okay I have made the requested changes; please review again. Thanks for the review @freakboy3742.

[bedevere-app]

Thanks for making the requested changes!

@freakboy3742, @mdboom: please review the changes made to this pull request.

[hoodmane]

Huh interesting that the bot rerequested review from @mdboom even though his review status was already approved.