Improved `EM_JS` formatting

[SingleAccretion]

EM_JS is a very useful feature for including JS-library-like code in object files (which can later be put into archives and linked fully transparently). However, it suffers from a usability issue: it is by default formatted as one large line:

; input
EM_JS(int, JSAdd2, (int x, int y), {
    console.log(`In JSAdd2(${x}, ${y})`);
    return x + y;
});

; output
function JSAdd2(x,y) { console.log(`In JSAdd2(${x}, ${y})`); return x + y; }

Which makes larger functions very hard to debug / read in generated code.

I was thinking the situation could be improved; some possibilities:

1. Run an auto-formatter on these functions after the fact. This could be complex.
2. Add a new macro variation that accepts string literals instead of a token list.

I am not sure 1 is viable. 2 though seems like a simple enough change; it can be hacked together today by using the implementation macro _EM_JS (and indeed works as one would expect):

EM_JS_STR(int, JSAdd, (int x, int y), R"({
    console.log(`In JSAdd(${x}, ${y})`);
    return x + y;
})");

[hoodmane]

Is there a reason not to apply a formatter on the emcc linker output? This is what I always do.

[SingleAccretion]

Is there a reason not to apply a formatter on the emcc linker output? This is what I always do.

The default output is good enough. It's generated code, so generally you wouldn't expect to need to involve additional tools to post-process it beyond what's required for correctness. And in our case we're a "framework" using Emscripten; bundling an additional JS formatter wouldn't pass the value add bar.

[sbc100]

I agree that using some kind of formatter makes the most sense here. I normally just do clang-format -i out.js if I want this.

Running the whole of the generated JS code through a formatter automatically seems a little excessive to work around this issue since it does seem simple enough to do post-link.

[SingleAccretion]

Running the whole of the generated JS code through a formatter automatically seems a little excessive to work around this issue

Agreed.

since it does seem simple enough to do post-link.

I do want to emphasize though that it is "not that simple" in the toolchain case. Just as it doesn't make sense to add a formatter just for this to Emscripten, it doesn't make sense to add a formatter just for this to our SDK which depends on Emscripten. The end result being that we have to choose between:

1. Suboptimally formatted output by default.
2. Having more files that need to be explicitly linked and moved around the build system.

Do you think we can add the EM_JS_STR API from 2? I will close the issue if the consensus is that's not really worth it either.

[sbc100]

You might also want to consider using JS library files --js-library=libfoo.js or -lfoo.js. These do not suffer from the formatting issue.

I get that adding a formatter along with a formatting is step is more complexity on your end, but we do have to push back against adding more tooling and complexity in emscripten. As you know emscripten is already very complex and has a lot of sub-tools complexity which is hard to manage. Adding more tools and complexity under the hood is something we will always tend to be conservative on.

It not inconceivable we could do this, especially if the following conditions could be met:

1. Make it the default, for debug builds, avoiding adding a new setting.
2. Use a tool that is already shipping with emscripten (Do we already have something in our node_modules that can do this?.. maybe clang-format actually?)
3. Have it only apply to EM_JS code so that users without EM_JS don't pay any cost.

[SingleAccretion]

We are in consensus that adding a formatter solution is not a good solution (as expected to a certain point - I am not sure 1 is viable).

Do we have consensus on 2, i. e. on exposing a version of EM_JS that'd take a string literal instead of __VA_ARGS__?

[sbc100]

Adding another variant of EM_JS also seems like a more complexity, but if there are enough folks who think its a good idea its certainly possible. It would mean running our EM_JS tests in two different modes.

I assume there would upsides and downsides to using string literals? It would make make code formatters / parsers / highlighters no longer work in the C/C++ sources I assume? Would it only work in C++ and not in C?

I wonder if there is some way for you to define the macro variant downstream in your code? Over time, if enough folks start doing the same we could consider upstreaming it?

[SingleAccretion]

It would mean running our EM_JS tests in two different modes.

I don't think it would require that level of testing... The implementation would be:

#define EM_JS_STR(ret, name, params, body) _EM_JS(ret, name, name, params, body)

It would make make code formatters / parsers / highlighters no longer work in the C/C++ sources I assume?

Indeed. It would still be a big improvement I think (the downside of "undebuggable" is larger than "unhighlightable").

Would it only work in C++ and not in C?

Well, you'd still be able to use it in C, it just wouldn't look very nice (inline assembly has the same problem):

EM_JS_STR(int, JSAdd, (int x, int y), "({\n"
"    console.log(`In JSAdd(${x}, ${y})`);\n"
"    return x + y;\n"
"})\n");

I wonder if there is some way for you to define the macro variant downstream in your code?

AFAIK it's not possible to strip quotes using macro magic. So the only option for such an implementation would be to use _EM_JS, which wouldn't be acceptable.