Restructure the CLI

[saulecabrera]

This proposal suggests a restructuring of Javy's CLI interface to:

• Enhance flexibility in specifying code generation options and JavaScript engine features.
• Provide semantically meaningful command and sub-command names where applicable.

Command Flexibility

Javy currently offers a wide range of configuration options that control the JavaScript language features available to the generated code. However, there are limitations:

• There is currently no way to specify these options directly from the CLI.
• Other code-generation options, such as name section generation and optimization options, cannot be specified through the CLI. These options are crucial for profiling Javy-generated modules using tools like wasmprof. Currently, users must manually update these options, which is not ideal.
• The current default settings are not well-suited to all use cases, as highlighted in issue #628.

Semantically Meaningful Commands, Sub-Commands and Options

The CLI currently features two main commands: compile and emit-provider. The compile command does not accurately reflect its actions and could be better named to represent actual AOT compilation of JavaScript, a feature we plan to explore in the future.

Proposal

The high-level proposal includes:

• Deprecating the compile command in favor of a new command, tentatively named build. Avoid introducing breaking changes or new features through the compile command.
• Enhance the build command with meaningful options to control JavaScript and code generation features as described above.
• Updating the compile command to emit a deprecation notice, indicating that it will be deprecated in the next major release of the CLI.
  • The ideal timeline for transitioning from issuing a deprecation notice to actual deprecation is not clear. I propose to discuss this issue on our Zulip stream and make a decision based on the feedback received.

CLI Interface

The proposal suggests, according to the bullet points above, to have the new build command look like:

$ javy build --help

Builds a Wasm module from a JS source
Usage: javy build <OPTIONS> <JS>

Arguments:
  <JS> The JavaScript source to be used as input for building the WebAssembly module.

Options:

-J, --js <KEY[=VAL[,..]]> JavaScript runtime options.
-D, --debug <KEY[=VAL[,..]]> Debug options.
-C, --codegen <KEY[=VAL[,..]]> Code generation options (the current `-d` and `wit` options)
-o, --output The path of the Wasm module.

For example, in order to control the name section generation, one could do:

javy build -D generate-name-section=true -o index.wasm index.js

The suggested CLI layout, takes inspiration from Wasmtime's CLI layout, which, I think offers multiple benefits, notably:

• Ability to have option groups, that make it easier to share such groups across commands where applicable (e.g., it might make sense to share the -D group, across the build and emit-provider commands, for cases in which the user wants to control walrus/wasm-opt options.
• Reduced option verbosity. I can think of at least one alternative way of presenting command options, by using enable-<group>-<option> and disable-<group>-<option>. Aside from the verbosity, with this approach, we need to introduce at least two options per group (assuming each option allows at least enabling or disabling).

Proposed order of operations

• Introduce the new build command, which will initially behave similar to the current compile command.
• Introduce a deprecation notice under the current compile command.
• Land CLI: Allow Input from stdin and Output to stdout #701
• Release version 3.1.0 of the CLI
• Introduce the -J options group
• Introduce the -D options group
• Introduce the -C options group
• Release version 4 of the CLI with the deprecated compile command. (After having collected feedback / agreed on the deprecation timeline)

[jeffcharles]

A few questions to start:

1. Where does the current -d flag fit in on the new interface?
2. Is it fair to say the difference between the -J and -D groups are the -D options have more to do with the content of the Wasm that's created and the -J group of options have to do with intrinsics that are made available?
3. Is the idea that the -J option group will impact the provider that's produced when running emit-provider?

[saulecabrera]

1. Updated the OP; I'm currently thinking under a -C, --codegen group.
2. I intend the -D group to control debug options around code generation. Alternatively, merging the -D options under the -C group could also work. For -J your interpretation is correct.
3. It could, however, I consider that change to be out-of-scope for this proposal.

[saulecabrera]

It could, however, I consider that change to be out-of-scope for this proposal.

More explicitly for this proposal, I'm intending to validate that the option groups specified through -J are in agreement with the JS options enabled by default in the provider when -C dynamic=true is specified.

[jeffcharles]

1. Updated the OP; I'm currently thinking under a -C, --codegen group.

👍

2. I intend the -D group to control debug options around code generation. Alternatively, merging the -D options under the -C group could also work. For -J your interpretation is correct.

Merging them would help to avoid unproductive discussions about when a new codegen-related flag is actually a debug flag or the opposite.

3. [...] I'm intending to validate that the option groups specified through -J are in agreement with the JS options enabled by default in the provider when -C dynamic=true is specified.

That makes sense for now.

[konradkoschel]

Hi Saúl,

I have one question (or feature request) regarding the CLI refactoring. As the Javy-CLI npm package was recently deprecated, would it be possible to release the javy-cli crate on crates.io similar to the javy crate itself?

Ideally, the crate would also include a lib.rs to be consumable as a library. I think this would be comparably simple to implement.

Technically, as a fully-fledged replacement for the npm package, a new wrapper using napi.rs could be created, where the workaround (downloading the binary from Github and executing it in a child-process) is no longer needed. I see the point that this does introduce a lot more implementation efforts for sure though.

Would love to hear your opinion on these suggestions 😀

I'd be open to support this also.