Dynamic Linking questions

[John Dallman]

I've read <https://emscripten.org/docs/compiling/Dynamic-Linking.html>, but I'm used to native code linking, and I have questions. 

I'm porting a large library written in C and C++ to Emscripten, along with its test harness. I can build them as a statically linked program, putting it into one big .js file via SINGLE_FILE, and it runs. There are various problems to solve, but it runs in Node.js and passes quite a few tests. 

I am not producing a web application. The library is intended to be used in web applications, written by organisations that license this (commercial, closed-source) library. Up to now, I've been assuming that I need to ship the library in archive library form, because when this project was first scoped, about two years ago, modules couldn't call modules directly, only via JavaScript. Creating a JavaScript binding for this library would be a huge task, and I'm not attempting it at present. 

Today, I checked the dynamic linking page, and it looks as if modules can now call modules directly, without going through JavaScript. First of all, is that correct?

If that is true, I clearly need to build my library as a Side Module and my test harness as a Main Module, linked against the Side Module, for load-time dynamic linking. The page says that Side Modules can't be linked against system libraries, but presumably they can use system libraries? It's just that the Main Module must be linked against all system libraries that any Side Modules use? My Side Module definitely requires the C and C++ run-time libraries.

If that's all correct, how do I tell my Main Module where to find the Side Module when I run the program in Node.js? Is there an equivalent of $LD_LIBRARY_PATH? Or does it just have to be in the same directory? 

How does a web application get access to the Side Module? I'm not doing this, but I will inevitably be asked about it.

Thanks in advance,

John Dallman

[Sam Clegg]

Hi John, 

Replies to your questions inline below.

On Fri, May 22, 2026 at 9:19 AM John Dallman <jgdats...@gmail.com> wrote:

I've read <https://emscripten.org/docs/compiling/Dynamic-Linking.html>, but I'm used to native code linking, and I have questions. 

I'm porting a large library written in C and C++ to Emscripten, along with its test harness. I can build them as a statically linked program, putting it into one big .js file via SINGLE_FILE, and it runs. There are various problems to solve, but it runs in Node.js and passes quite a few tests. 

Note that `SINGLE_FILE` is kind of orthogonal to dynamic linking.    All that `SINGLE_FILE` does is embed the Wasm binary inside the JS as a binary string.  I would not recommend using this setting unless shipping the separate `.wasm` file is prohibitively difficult for some reason (for some folks just hosting a second file is a real pain, for example).

I am not producing a web application. The library is intended to be used in web applications, written by organisations that license this (commercial, closed-source) library. Up to now, I've been assuming that I need to ship the library in archive library form, because when this project was first scoped, about two years ago, modules couldn't call modules directly, only via JavaScript. Creating a JavaScript binding for this library would be a huge task, and I'm not attempting it at present. 

Today, I checked the dynamic linking page, and it looks as if modules can now call modules directly, without going through JavaScript. First of all, is that correct?

Yes, we have supported side modules this way for a while now.   In fact we are about to transition the behavior of the `-shared` flag to produce side modules (see my recent PSA to this list)

However, I would still recommend against it if a static library works for your use case.  Static linking is always more performant (even on native platforms) and allows for more optimization.  For example, when you statically link a library `wasm-opt` can optimize it along with your main program.  

If that is true, I clearly need to build my library as a Side Module and my test harness as a Main Module, linked against the Side Module, for load-time dynamic linking. The page says that Side Modules can't be linked against system libraries, but presumably they can use system libraries? It's just that the Main Module must be linked against all system libraries that any Side Modules use? My Side Module definitely requires the C and C++ run-time libraries.

Yes, side modules can reference system libraries, but the system libraries will get linked into the main module.

 

If that's all correct, how do I tell my Main Module where to find the Side Module when I run the program in Node.js? Is there an equivalent of $LD_LIBRARY_PATH? Or does it just have to be in the same directory? 

This depends a little on how you build your program, and it seems to be an area where we lack some documentation.

The dynamic library loading code can load side modules both from the VFS and from the real node FS.   In the case of `NODERAWFS` these will be same.

If you are loading via the VFS then you can set `LD_LIBRARY_PATH` using `ENV['LD_LIBRARY_PATH']` in JS (See test_ld_library_path in test_other.py).

Otherwise, the dynamic library loading code will fall back to the `readBinary` utility which will just call `FS.readFileSync(..)` under node and `fetch(..)` on the web.

How does a web application get access to the Side Module? I'm not doing this, but I will inevitably be asked about it.

Thanks in advance,

John Dallman

--
You received this message because you are subscribed to the Google Groups "emscripten-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to emscripten-disc...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/emscripten-discuss/CAH1xqgnnVfxnBydT3L8cR%2B%2Breigy%3D6aTRThWRFLCvy%3D75wVfeQ%40mail.gmail.com.