Skip to content

Format and cleanup site/source/docs/api_reference/advanced-apis.rst. NFC #16523

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
Mar 24, 2022
+38 −22
Merged

Format and cleanup site/source/docs/api_reference/advanced-apis.rst. NFC #16523

Show file tree
Hide file tree
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
49 changes: 32 additions & 17 deletions site/source/docs/api_reference/advanced-apis.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,10 @@
Advanced APIs
=============

This section lists APIs that are not suitable for general use, but which may be useful to developers in some circumstances. These include APIs that are difficult or complicated to use, or which are intended primarily for developers working on the Emscripten core.
This section lists APIs that are not suitable for general use, but which may be
useful to developers in some circumstances. These include APIs that are
difficult or complicated to use, or which are intended primarily for developers
working on the Emscripten core.

.. contents:: Table of Contents
:local:
Expand All @@ -14,42 +17,51 @@ This section lists APIs that are not suitable for general use, but which may be
.. _settings-js:

settings.js
============

`settings.js <https://github.com/emscripten-core/emscripten/blob/main/src/settings.js>`_ contains default values and options used in various places by the compiler.
===========

.. Warning :: Many **settings.js** options are highly brittle - certain combinations of options, and combinations of certain options used with some source code, can cause Emscripten to fail badly. This is intended for use by "advanced users", and possibly even only people developing Emscripten itself.
`settings.js`_ contains default values and options used in various places by the
compiler.

.. Warning:: Many **settings.js** options are highly brittle - certain
combinations of options, and combinations of certain options used with some
source code, can cause Emscripten to fail badly. This is intended for use by
"advanced users", and possibly even only people developing Emscripten itself.

The options in **settings.js** are normally set as command line parameters to *emcc*: ::
The options in **settings.js** are normally set as command line parameters to
*emcc*::

emcc -s OPT=VALUE


While it is possible to edit **settings.js** manually, this is *highly discouraged*. In general **settings.js** defines low-level options that should not be modified. Note also that the compiler changes some options depending on other settings. For example, ``ASSERTIONS`` is enabled by default, but disabled in optimized builds (``-O1+``).

The small number of options that developers may have cause to change should be modified when the *emcc* tool is invoked. For example, ``EXPORTED_FUNCTIONS``: ::

./emcc tests/hello_function.cpp -o function.html -s EXPORTED_FUNCTIONS=_int_sqrt

While it is possible to edit **settings.js** manually, this is *highly
discouraged*. In general **settings.js** defines low-level options that should
not be modified. Note also that the compiler changes some options depending on
other settings. For example, ``ASSERTIONS`` is enabled by default, but disabled
in optimized builds (``-O1+``).

preamble.js
===========

The following advanced APIs are documented in `preamble.js <https://github.com/emscripten-core/emscripten/blob/main/src/preamble.js>`_.
The following advanced APIs are documented in `preamble.js`_.

.. js:function:: allocate(slab, allocator)

This is marked as *internal* because it is difficult to use (it has been optimized for multiple syntaxes to save space in generated code). Normally developers should instead allocate memory using ``_malloc()``, initialize it with :js:func:`setValue`, etc., but this function may be useful for advanced developers in certain cases.
This is marked as *internal* because it is difficult to use (it has been
optimized for multiple syntaxes to save space in generated code). Normally
developers should instead allocate memory using ``_malloc()``, initialize it
with :js:func:`setValue`, etc., but this function may be useful for advanced
developers in certain cases.

:param slab: An array of data, or a number. If a number, then the size of the block to allocate, in *bytes*.
:param slab: An array of data, or a number. If a number, then the size of the
block to allocate, in *bytes*.
:param allocator: How to allocate memory, see ALLOC_*


Advanced File System API
========================

:ref:`Filesystem-API` covers the public API that will be relevant to most developers. The following functions are only needed for advanced use-cases (for example, writing a new local file system) or legacy file system compatibility.
:ref:`Filesystem-API` covers the public API that will be relevant to most
developers. The following functions are only needed for advanced use-cases (for
example, writing a new local file system) or legacy file system compatibility.

.. js:function::
FS.hashName(parentid, name)
Expand Down Expand Up @@ -106,3 +118,6 @@ There are also a small number of additional :ref:`flag modes <fs-read-and-write-
- ``xw+``
- ``xa``
- ``xa+``

.. _settings.js: https://github.com/emscripten-core/emscripten/blob/main/src/settings.js
.. _preamble.js: https://github.com/emscripten-core/emscripten/blob/main/src/preamble.js
11 changes: 6 additions & 5 deletions site/source/docs/api_reference/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@
API Reference
=============

This section lists Emscripten's public API, organised by header file. At a very high level it consists of:
This section lists Emscripten's public API, organised by header file. At a very
high level it consists of:

- :ref:`emscripten-h`:
APIs for integrating with the browser environment.
Expand All @@ -25,13 +26,15 @@ This section lists Emscripten's public API, organised by header file. At a very
Enables writing multithreaded programs using a web-like API.

- :ref:`Module`:
Global JavaScript object that can be used to control code execution and access exported methods.
Global JavaScript object that can be used to control code execution and access
exported methods.

- :ref:`val-h`:
Embind API to support transliteration of JavaScript code to C++.

- :ref:`bind-h`:
Embind API for binding C++ functions and classes so that they can be called from JavaScript in a natural way.
Embind API for binding C++ functions and classes so that they can be called
from JavaScript in a natural way.

- :ref:`trace-h`:
A tracing API for doing memory usage analysis.
Expand All @@ -58,5 +61,3 @@ This section lists Emscripten's public API, organised by header file. At a very
fiber.h
wasm_workers
advanced-apis