You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: site/source/docs/tools_reference/emcc.rst
+30-14Lines changed: 30 additions & 14 deletions
Original file line number
Diff line number
Diff line change
@@ -286,28 +286,44 @@ Options that are modified or new in *emcc* are listed below:
286
286
287
287
``--embed-file <file>``
288
288
[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.
290
292
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*.
292
295
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.
294
298
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`.
296
301
297
302
.. _emcc-preload-file:
298
303
299
304
``--preload-file <name>``
300
305
[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.
0 commit comments