WASM Automatic Demo Generator Proof of Concept

[ambiguousname]

Rough implementation of the process described in https://docs.google.com/document/d/1xRTmK0YtOfuAe7ClN6kqDaHyv5HpdIRIYQW6Zc_KKFU/edit?usp=sharing

Proof of concept is live at https://ambiguous.name/diplomat/

[sffc]

Notes from 2024-06-20

Design doc: https://docs.google.com/document/d/1xRTmK0YtOfuAe7ClN6kqDaHyv5HpdIRIYQW6Zc_KKFU/edit#heading=h.b6hfjuxzqkmm

• ? - Not opposed to demo-gen part of the JS backend add it as an extra flag. Diplomat could take more flags. It seems like most people doing demogen are going to have to first to jsgen.
• @sffc - The RenderInfo artifacts are very separate from the JS artifacts.
• ? - Code should be modular
• ? - Really like the design so far
• @robertbastian - What's the status of JS2?
• @ambiguousname - It's working pretty well and I've filled in some of the TODOs as I've been working on the demogen.
• @Manishearth - My original thought was that things that want demos would be marked, but this goes the other way (all writeables get generated and things can get hidden). But having demo::hide or demo::show is easy to do. This would be a point in favor of a separate backend.
• @ambiguousname - Yeah that would make things more flexible.
• @Manishearth - How are you picking a constructor?
• @ambiguousname - For structs it's easy. For opaques I'm piggy-backing off the constructor attribute. I also have a demo default constructor attribute.
• @Manishearth - That is a good design.

[ambiguousname]

Big issue right now is that build-test and gen throw errors. Pretty sure this is related to my modifications to attrs.rs in the core module. I have some ideas for fixing gen, but build-test requires testing against snapshots that I'm not entirely sure how to work with. Any help would be appreciated!

[ambiguousname]

Ah, I've found the insta crate, so I will run tests and verify that the snapshots look okay, then add them as a change to review. Still doesn't solve the gen errors, unfortunately.

[ambiguousname]

Mixed syntax for arguments, terminusArgs, and ...args. Cleaning up would be helpful, so using the argument names would be better than terminusArgs[3], say.

[ambiguousname]

Move rendering.mjs into templates, call it diplomatDefaultRendering.mjs (maybe with the base .html and index.js file too, if index.html is not detected?) and copy it over every time it's run.

[ambiguousname]

Some self notes:

• I think it'd be good to allow generation even if certain errors (maybe just push warnings instead?) are present, so someone could quickly set up a demo and see how it works.
• Better warnings/error description would be good. Maybe showing the tree of dependencies, so people know where to look.

[ambiguousname]

Currently going through the pain of setting up a proof of concept demo in the ICU4X repo.

Based on how many things I'm having to move around to make this work, I think I'm in favor of Manish's idea to make the demo-gen part a flag on the JS2 backend. This would remove capabilities like #[diplomat::attr(demo_gen, disable]), but I think that's small potatoes compared to making sure this works out of the box after running it once.

Edit: especially because renames (and disables!) that apply to JS2, do NOT apply to demo-gen.

[sffc]

but "opt out if it can't be constructed" is also fine i guess.

We're close to the WASM generator working out of the box with no annotations or configurations, and I'd like to keep it that way. I think the heuristic of "opt in if we know how to make a demo for this function signature" is good.

[Manishearth]

We're close to the WASM generator working out of the box with no annotations or configurations, and I'd like to keep it that way. I think the heuristic of "opt in if we know how to make a demo for this function signature" is good.

I believe the current heuristic is opt-out, not opt-in. Which is fine, but will potentially cause friction if the backend also produces errors when it's unable to do something, and might make it harder for ICU4X devs to add new FFI. I'm fine with that shift, but it's an angle of complexity we should definitely consider: not every terminus is going to be renderable.

[ambiguousname]

(Potentially) Non-blocking Issues List:

• Because of the new HTML file system, I haven't had a lot of time to add back in things like style or even template customization. Not sure if this is blocking, but I definitely want to add this in before my time with GSoC is up.
• Attribute improvements

  • 521

  • Default values for parameters
  • Allow selection of pre-set values for strings
  • Better organized termini output, instead of a long chain of .apply.
  • Error generation
  • I think it'd be good to allow generation even if certain errors (maybe just push warnings instead?) are present, so someone could quickly set up a demo and see how it works.
  • Better warnings/error description would be good. Maybe showing the tree of dependencies, so people know where to look.
• Config/Command Line Options
  • Options to set termini to automagically run or be opt-in
• Parameter naming conventions (see https://github.com/rust-diplomat/diplomat/pull/500#discussion_r1680141206)
• Check for parameter name collision (allows us to actually show parameter names in the function definition, and show where each parameter name is going)
• Re-designing ParamInfo, maybe to be clearer whether or not it's an external parameter or one that will be used inside a function.
  • See https://github.com/rust-diplomat/diplomat/pull/500#discussion_r1680130187

[Manishearth]

Fine to do all fixes in a followup.