Skip to content

[WasmFS] Make the Node backend optional for web builds #26608

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kleisauke merged 8 commits into from
Apr 4, 2026
+30 −5
Merged

[WasmFS] Make the Node backend optional for web builds #26608

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
26eaedc
[WasmFS] Make the Node backend optional for web builds
kleisauke Mar 24, 2026
d30f7de
Incorporate feedback
kleisauke Apr 2, 2026
eea0053
Adjust error message
kleisauke Apr 2, 2026
4143136
Remove unnecessary `eval()`
kleisauke Apr 2, 2026
4b86c1c
Avoid empty `main()`
kleisauke Apr 2, 2026
a2ab145
Incorporate feedback
kleisauke Apr 2, 2026
112bd63
Cherry-pick from PR #26609
kleisauke Apr 2, 2026
d0c6c63
Remove superfluous test
kleisauke Apr 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 30 additions & 5 deletions src/lib/libwasmfs_node.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@
* SPDX-License-Identifier: MIT
*/
Copy link
Copy Markdown
Collaborator

@sbc100 sbc100 Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about simply not allowing this file to be included at all it !ENVIRONMENT_MAY_BE_NODE?

Copy link
Copy Markdown
Collaborator Author

@kleisauke kleisauke Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That would lead to linker failures. For example, if I remove all these stubs and run ./test/runner other.test_wasmfs_nodefs_stubs, I see:

Details 
wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_fstat_size
wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_stat_size
wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_open
wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_open
wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_close
wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_close
wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_read
wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_write
wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_ftruncate
wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_truncate
wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_get_mode
wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_insert_file
wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_insert_directory
wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_symlink
wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_rename
wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_unlink
wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_rmdir
wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_readdir
wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_readlink
...

I also thought about moving these stubs to native code and using weak linkage (like how wasmfs_create_root_dir() is handled), but this seemed easier.

Copy link
Copy Markdown
Collaborator

@sbc100 sbc100 Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair enough. I guess we should abort/assert in debug builds there though.


addToLibrary({
$wasmfsNodeIsWindows: !!process.platform.match(/^win/),
var wasmFSNodeLibrary = {
$wasmfsNodeIsWindows: "!!process.platform.match(/^win/)",
Copy link
Copy Markdown
Collaborator Author

@kleisauke kleisauke Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a small drive-by fix. Previously, this would emit (when building on Linux):

var wasmfsNodeIsWindows = false;

in the JS output, which breaks when deploying these binaries on Windows.

As possible follow-up, we could also do:

Suggested change
$wasmfsNodeIsWindows: "!!process.platform.match(/^win/)",
$wasmfsNodeIsWindows: "!!globalThis.process?.platform.match(/^win/)",

This would allow a -sENVIRONMENT=node,web build to work on both Node.js and the web, using the same pattern as in other.test_wasmfs_nodefs_stubs, i.e.:

#include <emscripten/emscripten.h>
#include <emscripten/wasmfs.h>

EM_JS(bool, is_node, (), { return ENVIRONMENT_IS_NODE; });

backend_t wasmfs_create_root_dir() {
  return is_node() ? wasmfs_create_node_backend("")
                   : wasmfs_create_memory_backend();
}

Copy link
Copy Markdown
Collaborator Author

@kleisauke kleisauke Apr 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... PR #26624 addresses this.


$wasmfsNodeConvertNodeCode__deps: ['$ERRNO_CODES'],
$wasmfsNodeConvertNodeCode: (e) => {
Expand All @@ -29,8 +29,8 @@ addToLibrary({
$wasmfsNodeFixStat__deps: ['$wasmfsNodeIsWindows'],
$wasmfsNodeFixStat: (stat) => {
if (wasmfsNodeIsWindows) {
// Node.js on Windows never represents permission bit 'x', so
// propagate read bits to execute bits
// Windows does not report the 'x' permission bit, so propagate read
// bits to execute bits.
stat.mode |= (stat.mode & {{{ cDefs.S_IRUGO }}}) >> 2;
}
return stat;
Expand Down Expand Up @@ -222,5 +222,30 @@ addToLibrary({
// implicitly return 0
});
},
};

#if !ENVIRONMENT_MAY_BE_NODE
function makeStub(x, library) {
if (isJsOnlySymbol(x) || isDecorator(x)) {
return;
}

var t = library[x];
if (typeof t == 'string') return;
t = t.toString();

delete library[x + '__i53abi'];
delete library[x + '__deps'];
library[x] = modifyJSFunction(t, (args, body) => {
return `(${args}) => {\n` +
(ASSERTIONS ? "abort('attempt to call Node.js backend function without ENVIRONMENT_MAY_BE_NODE');\n" : '') +
'}';
});
}

for (const name of Object.keys(wasmFSNodeLibrary)) {
makeStub(name, wasmFSNodeLibrary);
}
#endif

});
addToLibrary(wasmFSNodeLibrary);
Loading