Skip to content

Update / clarify docs for JS library usage #24380

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
merged 1 commit into from
May 20, 2025
Merged

Update / clarify docs for JS library usage #24380

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
30 changes: 14 additions & 16 deletions site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -362,20 +362,18 @@ Implement a C API in JavaScript
It is possible to implement a C API in JavaScript! This is the approach
used in many of Emscripten's libraries, like SDL1 and OpenGL.

You can use it to write your own APIs to call from C/C++. To do this
you define the interface, decorating with ``extern`` to mark the methods
in the API as external symbols. You then implement the symbols in
JavaScript by simply adding their definition to `library.js`_ (by
default). When compiling the C code, the compiler looks in the JavaScript
libraries for relevant external symbols.

By default, the implementation is added to **library.js** (and this is
where you'll find parts of Emscripten's *libc*). You can put
the JavaScript implementation in your own library file and add it using
the :ref:`emcc option <emcc-js-library>` ``--js-library``. See
`test_jslib`_ in **test/test_other.py** for a complete working
example, including the syntax you should use inside the JavaScript library
file.
You can use it to write your own APIs to call from C/C++. To do this you define
the interface, decorating with ``extern`` to mark the methods in the API as
external symbols. You can them implement the symbols in JavaScript by simply
adding their definition to one of the `core JS library`_ files. Undefined
native symbols will be resolved by looking for them in JavaScript library files.

The `core JS library`_ files are where you will find Emscripten internals. For
example, parts of Emscripten's *libc* are implemented there. You can also put
the JavaScript implementation in your own library file and add it using the
:ref:`emcc option <emcc-js-library>` ``--js-library``. See `test_jslib`_ in
**test/test_other.py** for a complete working example, including the syntax you
should use inside the JavaScript library file.

As a simple example, consider the case where you have some C code like this:

Expand Down Expand Up @@ -843,8 +841,8 @@ on Emscripten. If you would like to port existing Node-API addon to WebAssembly
or compile the same binding code to both Node.js native addon and WebAssembly,
you can give it a try. See `Emnapi documentation`_ for more details.

.. _library.js: https://github.com/emscripten-core/emscripten/blob/main/src/library.js
.. _test_jslib: https://github.com/emscripten-core/emscripten/blob/1.29.12/tests/test_core.py#L5043
.. _core JS library: https://github.com/emscripten-core/emscripten/blob/main/src/lib/
.. _test_jslib: https://github.com/emscripten-core/emscripten/blob/4.0.9/test/test_core.py#L6261
.. _tools/system_libs.py: https://github.com/emscripten-core/emscripten/blob/main/tools/system_libs.py
.. _library_\*.js: https://github.com/emscripten-core/emscripten/tree/main/src
.. _test_add_function in test/test_core.py: https://github.com/emscripten-core/emscripten/blob/1.29.12/tests/test_core.py#L6237
Expand Down