Need a quick C++ class object example?

[roschler]

I just spent several hours going through different paths in the documentation that talk about different ways to build and call code. Unfortunately I find myself confused as to what is the quickest path for me to actually get my C++ module working with Node.js.

I installed EmScripten and Binaryen without trouble and they both work. I then use emcc to compile my self-contained C++ module and header file and I get out two files: a.out.js and a.out.wasm. But I can't seem to get from here to something I can use.

First I tried the code from this page after changing the wasm file path to my actual path and changing the exports to those in my C++ code:

https://nodejs.org/en/learn/getting-started/nodejs-with-webassembly

// Assume add.wasm file exists that contains a single function adding 2 provided arguments
const fs = require('node:fs');

const wasmBuffer = fs.readFileSync('/path/to/add.wasm');
WebAssembly.instantiate(wasmBuffer).then(wasmModule => {
  // Exported function live under instance.exports
  const { add } = wasmModule.instance.exports;
  const sum = add(5, 6);
  console.log(sum); // Outputs: 11
});

But that resulted in an error complaining that imports were not defined.

Then I tried running and tracing the a.out.js file with node.exe. It runs fine, but when I traced deep into the code, the result Module/instance did not show the C++ class from my C++ file at all. All I saw were what looked to be a lot of C++ library function stubs/proxy-calls for C++ library functions that I assume the wasm module can use.

So what is the simplest path for me to be able to create one of the C++ class objects from Node.js code (not browser)?

• Do I need to list the class and each of its public methods and data members in the EXPORTED_fUNCTIONS argument to emcc?

• Or do I use an EMBINDINGS declaration in my C++ file to do the same? If so, should I put that declaration in my "h" or "cpp" file and is there a way to use it so I can still compile the code in my IDE (CLion) without the CLang-Tidy throwing an error on it? When I tried that approach the compiler showed errors like these:

// Binding code
EMSCRIPTEN_BINDINGS(SoftFold) {
        class_<SoftFold>("SoftFold")
                .constructor()

------------ SNIP ------------------                

emcc soft-fold.cpp                
In file included from soft-fold.cpp:5:
.\soft-fold.h:553:1: error: unknown type name 'EMSCRIPTEN_BINDINGS'
  553 | EMSCRIPTEN_BINDINGS(SoftFold) {
      | ^

I also do not know what the correct string is to use for the opt level declaration EMSCRIPTEN_BINDINGS(SoftFold). Do I just repeat the class name?

• Or do I use the a.out.js file in some manner that I don't understand yet?

As I said, I could really use a tutorial or brief instructions that show me how to use emcc and any necessary EmScriptem idioms to create my wasm module, and then another brief text on how to call it.

[sbc100]

Firstly, yes, you should always use the a.out,js runner. You don't need to read or understand that file, since its auto-generated. Trying to load the Wasm file directly will, as you have discovered, require you to implement tot of imports

In terms of interacting with the C/C++ code there is really no difference bettween how you do it under node and in the browser. There are several methods you can use: https://emscripten.org/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.html

For simple C call I recommend just using call/cwrap, or just calling the exports directly.

For more complex C++ interactions you should use embind. The EMSCRIPTEN_BINDINGS block belongs in the C++ file and not the header file. Since EMSCRIPTEN_BINDINGS is a C macro its might not look nice in your IDE (although it should really if your IDE undersntands C macros, which it really should).

[roschler]

Thanks. I'm still in need of details.

"Firstly, yes, you should always use the a.out,js runner."

How? I can't seem to find a sample that uses that file and then creates a class object from the module it loads and calls methods on it. My app is a Node.js app so I need to do something that file more than just include it in my project. The problem with the terse example given in the quick tutorial is that it does not create any class objects or call any methods on such objects. It just assumes everything is in the C++ main() method that is invoked via the run() call in a.out.js.

"For simple C call I recommend just using call/cwrap, or just calling the exports directly."

Again, I could really use a brief example that connects your general instruction to embind and the a.out.js file.

"For more complex C++ interactions you should use embind. The EMSCRIPTEN_BINDINGS block belongs in the C++ file and not the header file. Since EMSCRIPTEN_BINDINGS is a C macro its might not look nice in your IDE (although it should really if your IDE undersntands C macros, which it really should)."

That does look like the way to go, but as I said when I run emcc I get those errors, even after moving the embind declaration out of the h file and into the bottom of the cpp file.

[roschler]

Ok, the main problem stemmed from me needing to add the EmScripten include directory directly to my build. Thanks. I also needed to use the following options on my emcc command line:

-s WASM=1 --bind -sMODULARIZE -sEXPORTED_RUNTIME_METHODS=ccall

This allowed me to straighten out some really difficult issues when using the CJS generated wasm loader file in an ES6 project, and in using the resulting ClassHandle object I got back from creating an instance of my main class using the instance object returned from the Module promise.

One other thing. I would make the need to call the delete() method on any class object created off of an wasm class much more prominent and ubiquitous. I would also add a tutorial note telling people not to expect to see the class method names and public properties in the JavaScript debugger.

DOC NOTES

The problem is for a newbie is that the EmScripten docs are somewhat overwhelming and given the polymorphic nature of much of this powerful library (e.g. - Module is a function when require'd when you don't use "-sMODULARIZE" but is a promisified function when you do, etc.) you can find yourself doing parallel breadth first search operation through the docs, not sure what is the right path for you to take and then confused by what appears to be contradicting instructions, when the reality is that you are just seeing the correct instructions for different usage modes.

I hope I don't seem ungrateful. EmScriptem and Binaryen together are a tremendous body of work and have given me the ability to use C++ code from my JavaScript apps, an amazing feat. Thank you for your effort.

[sbc100]

The simplest way to setup emscripten with cmake is to use emcmake when you run cmake. See https://emscripten.org/docs/compiling/Building-Projects.html#integrating-with-a-build-system for more information.

The mingw32 includes files should never been includes when building with emscripten and will be incompatible.