Skip to content

Commit 9f9aed2

Browse files
authored
Update --help text for --embed-file/--preload-file. NFC (#18297)
1 parent 2d75aa8 commit 9f9aed2

File tree

2 files changed

+34
-19
lines changed

2 files changed

+34
-19
lines changed

docs/emcc.txt

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -312,8 +312,8 @@ Options that are modified or new in *emcc* are listed below:
312312

313313
"--embed-file <file>"
314314
[link] Specify a file (with path) to embed inside the generated
315-
JavaScript. The path is relative to the current directory at
316-
compile time. If a directory is passed here, its entire contents
315+
WebAssembly module. The path is relative to the current directory
316+
at compile time. If a directory is passed here, its entire contents
317317
will be embedded.
318318

319319
For example, if the command includes "--embed-file dir/file.dat",
@@ -322,9 +322,8 @@ Options that are modified or new in *emcc* are listed below:
322322

323323
Note:
324324

325-
Embedding files is much less efficient than preloading them. You
326-
should only use it for small files, in small numbers. Instead use
327-
"--preload-file", which emits efficient binary data.
325+
Embedding files is generally more efficient than preloading as it
326+
avoids copying the file data at runtime.
328327

329328
For more information about the "--embed-file" options, see
330329
Packaging Files.

site/source/docs/tools_reference/emcc.rst

Lines changed: 30 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -286,28 +286,44 @@ Options that are modified or new in *emcc* are listed below:
286286

287287
``--embed-file <file>``
288288
[link]
289-
Specify a file (with path) to embed inside the generated JavaScript. The path is relative to the current directory at compile time. If a directory is passed here, its entire contents will be embedded.
289+
Specify a file (with path) to embed inside the generated WebAssembly module.
290+
The path is relative to the current directory at compile time. If a directory
291+
is passed here, its entire contents will be embedded.
290292

291-
For example, if the command includes ``--embed-file dir/file.dat``, then ``dir/file.dat`` must exist relative to the directory where you run *emcc*.
293+
For example, if the command includes ``--embed-file dir/file.dat``, then
294+
``dir/file.dat`` must exist relative to the directory where you run *emcc*.
292295

293-
.. note:: Embedding files is much less efficient than :ref:`preloading <emcc-preload-file>` them. You should only use it for small files, in small numbers. Instead use ``--preload-file``, which emits efficient binary data.
296+
.. note:: Embedding files is generally more efficient than :ref:`preloading
297+
<emcc-preload-file>` as it avoids copying the file data at runtime.
294298

295-
For more information about the ``--embed-file`` options, see :ref:`packaging-files`.
299+
For more information about the ``--embed-file`` options, see
300+
:ref:`packaging-files`.
296301

297302
.. _emcc-preload-file:
298303

299304
``--preload-file <name>``
300305
[link]
301-
Specify a file to preload before running the compiled code asynchronously. The path is relative to the current directory at compile time. If a directory is passed here, its entire contents will be embedded.
302-
303-
Preloaded files are stored in **filename.data**, where **filename.html** is the main file you are compiling to. To run your code, you will need both the **.html** and the **.data**.
304-
305-
.. note:: This option is similar to :ref:`--embed-file <emcc-embed-file>`, except that it is only relevant when generating HTML (it uses asynchronous binary :term:`XHRs <XHR>`), or JavaScript that will be used in a web page.
306-
307-
*emcc* runs `tools/file_packager <https://github.com/emscripten-core/emscripten/blob/main/tools/file_packager.py>`_ to do the actual packaging of embedded and preloaded files. You can run the file packager yourself if you want (see :ref:`packaging-files-file-packager`). You should then put the output of the file packager in an emcc ``--pre-js``, so that it executes before your main compiled code.
308-
309-
For more information about the ``--preload-file`` options, see :ref:`packaging-files`.
310-
306+
Specify a file to preload before running the compiled code asynchronously. The
307+
path is relative to the current directory at compile time. If a directory is
308+
passed here, its entire contents will be embedded.
309+
310+
Preloaded files are stored in **filename.data**, where **filename.html** is
311+
the main file you are compiling to. To run your code, you will need both the
312+
**.html** and the **.data**.
313+
314+
.. note:: This option is similar to :ref:`--embed-file <emcc-embed-file>`,
315+
except that it is only relevant when generating HTML (it uses asynchronous
316+
binary :term:`XHRs <XHR>`), or JavaScript that will be used in a web page.
317+
318+
*emcc* runs `tools/file_packager
319+
<https://github.com/emscripten-core/emscripten/blob/main/tools/file_packager.py>`_
320+
to do the actual packaging of embedded and preloaded files. You can run the
321+
file packager yourself if you want (see :ref:`packaging-files-file-packager`).
322+
You should then put the output of the file packager in an emcc ``--pre-js``,
323+
so that it executes before your main compiled code.
324+
325+
For more information about the ``--preload-file`` options, see
326+
:ref:`packaging-files`.
311327

312328
.. _emcc-exclude-file:
313329

0 commit comments

Comments
 (0)