├── .gitignore ├── .nojekyll ├── .well-known └── atproto-did ├── CNAME ├── README.md ├── _images ├── FileSystemArchitecture.png └── device-orientation-axes.png ├── _sources ├── docs │ ├── api_reference │ │ ├── Filesystem-API.rst.txt │ │ ├── Filesystem-API.txt │ │ ├── advanced-apis.rst.txt │ │ ├── advanced-apis.txt │ │ ├── bind.h.rst.txt │ │ ├── bind.h.txt │ │ ├── console.h.rst.txt │ │ ├── emscripten.h.rst.txt │ │ ├── emscripten.h.txt │ │ ├── fetch.rst.txt │ │ ├── fetch.txt │ │ ├── fiber.h.rst.txt │ │ ├── html5.h.rst.txt │ │ ├── html5.h.txt │ │ ├── index.rst.txt │ │ ├── index.txt │ │ ├── module.rst.txt │ │ ├── module.txt │ │ ├── preamble.js.rst.txt │ │ ├── preamble.js.txt │ │ ├── proxying.h.rst.txt │ │ ├── stack.h.rst.txt │ │ ├── trace.h.rst.txt │ │ ├── trace.h.txt │ │ ├── val.h.rst.txt │ │ ├── val.h.txt │ │ ├── vr.h.rst.txt │ │ ├── vr.h.txt │ │ ├── wasm_audio_worklets.rst.txt │ │ └── wasm_workers.rst.txt │ ├── building_from_source │ │ ├── LLVM-Backend.rst.txt │ │ ├── building_emscripten_from_source_on_linux.rst.txt │ │ ├── building_emscripten_from_source_on_mac_os_x.rst.txt │ │ ├── building_emscripten_from_source_on_windows.rst.txt │ │ ├── building_emscripten_from_source_using_the_sdk.rst.txt │ │ ├── building_fastcomp_manually_from_source.rst.txt │ │ ├── configuring_emscripten_settings.rst.txt │ │ ├── configuring_emscripten_settings.txt │ │ ├── index.rst.txt │ │ ├── index.txt │ │ ├── toolchain_what_is_needed.rst.txt │ │ ├── toolchain_what_is_needed.txt │ │ ├── verify_emscripten_environment.rst.txt │ │ └── verify_emscripten_environment.txt │ ├── compiling │ │ ├── Building-Projects.rst.txt │ │ ├── Building-Projects.txt │ │ ├── Contrib-Ports.rst.txt │ │ ├── Deploying-Pages.rst.txt │ │ ├── Deploying-Pages.txt │ │ ├── Dynamic-Linking.rst.txt │ │ ├── GitLab.rst.txt │ │ ├── GitLab.txt │ │ ├── Modularized-Output.rst.txt │ │ ├── Running-html-files-with-emrun.rst.txt │ │ ├── Running-html-files-with-emrun.txt │ │ ├── Travis.rst.txt │ │ ├── Travis.txt │ │ ├── WebAssembly.rst.txt │ │ ├── WebAssembly.txt │ │ ├── index.rst.txt │ │ └── index.txt │ ├── contributing │ │ ├── AUTHORS.rst.txt │ │ ├── AUTHORS.txt │ │ ├── contributing.rst.txt │ │ ├── contributing.txt │ │ ├── developers_guide.rst.txt │ │ ├── developers_guide.txt │ │ ├── index.rst.txt │ │ └── index.txt │ ├── debugging │ │ ├── Sanitizers.rst.txt │ │ └── Sanitizers.txt │ ├── getting_started │ │ ├── FAQ.rst.txt │ │ ├── FAQ.txt │ │ ├── Tutorial.rst.txt │ │ ├── Tutorial.txt │ │ ├── bug_reports.rst.txt │ │ ├── bug_reports.txt │ │ ├── downloads.rst.txt │ │ ├── downloads.txt │ │ ├── index.rst.txt │ │ ├── index.txt │ │ ├── test-suite.rst.txt │ │ └── test-suite.txt │ ├── index.rst.txt │ ├── index.txt │ ├── introducing_emscripten │ │ ├── Talks-and-Publications.rst.txt │ │ ├── Talks-and-Publications.txt │ │ ├── about_emscripten.rst.txt │ │ ├── about_emscripten.txt │ │ ├── community.rst.txt │ │ ├── community.txt │ │ ├── emscripten_license.rst.txt │ │ ├── emscripten_license.txt │ │ ├── index.rst.txt │ │ ├── index.txt │ │ ├── release_notes.rst.txt │ │ └── release_notes.txt │ ├── optimizing │ │ ├── Module-Splitting.rst.txt │ │ ├── Optimizing-Code.rst.txt │ │ ├── Optimizing-Code.txt │ │ ├── Optimizing-WebGL.rst.txt │ │ ├── Optimizing-WebGL.txt │ │ ├── Profiling-Toolchain.rst.txt │ │ └── Profiling-Toolchain.txt │ ├── porting │ │ ├── Audio.rst.txt │ │ ├── Audio.txt │ │ ├── Debugging.rst.txt │ │ ├── Debugging.txt │ │ ├── asyncify.rst.txt │ │ ├── asyncify.txt │ │ ├── connecting_cpp_and_javascript │ │ │ ├── Interacting-with-code.rst.txt │ │ │ ├── Interacting-with-code.txt │ │ │ ├── WebIDL-Binder.rst.txt │ │ │ ├── WebIDL-Binder.txt │ │ │ ├── embind.rst.txt │ │ │ ├── embind.txt │ │ │ ├── index.rst.txt │ │ │ └── index.txt │ │ ├── emscripten-runtime-environment.rst.txt │ │ ├── emscripten-runtime-environment.txt │ │ ├── emterpreter.rst.txt │ │ ├── emterpreter.txt │ │ ├── exceptions.rst.txt │ │ ├── files │ │ │ ├── Synchronous-Virtual-XHR-Backed-File-System-Usage.rst.txt │ │ │ ├── Synchronous-Virtual-XHR-Backed-File-System-Usage.txt │ │ │ ├── file_systems_overview.rst.txt │ │ │ ├── file_systems_overview.txt │ │ │ ├── index.rst.txt │ │ │ ├── index.txt │ │ │ ├── packaging_files.rst.txt │ │ │ └── packaging_files.txt │ │ ├── guidelines │ │ │ ├── api_limitations.rst.txt │ │ │ ├── api_limitations.txt │ │ │ ├── browser_limitations.rst.txt │ │ │ ├── browser_limitations.txt │ │ │ ├── function_pointer_issues.rst.txt │ │ │ ├── function_pointer_issues.txt │ │ │ ├── index.rst.txt │ │ │ ├── index.txt │ │ │ ├── portability_guidelines.rst.txt │ │ │ └── portability_guidelines.txt │ │ ├── index.rst.txt │ │ ├── index.txt │ │ ├── multimedia_and_graphics │ │ │ ├── EGL-Support-in-Emscripten.rst.txt │ │ │ ├── EGL-Support-in-Emscripten.txt │ │ │ ├── OpenGL-support.rst.txt │ │ │ ├── OpenGL-support.txt │ │ │ ├── index.rst.txt │ │ │ └── index.txt │ │ ├── networking.rst.txt │ │ ├── pthreads.rst.txt │ │ ├── pthreads.txt │ │ ├── setjmp-longjmp.rst.txt │ │ ├── simd.rst.txt │ │ └── simd.txt │ ├── site │ │ ├── about.rst.txt │ │ ├── about.txt │ │ ├── glossary.rst.txt │ │ ├── glossary.txt │ │ ├── index.rst.txt │ │ └── index.txt │ └── tools_reference │ │ ├── emcc.rst.txt │ │ ├── emcc.txt │ │ ├── emcmdprompt.rst.txt │ │ ├── emcmdprompt.txt │ │ ├── emsdk.rst.txt │ │ ├── emsdk.txt │ │ ├── index.rst.txt │ │ ├── index.txt │ │ └── settings_reference.rst.txt ├── index.rst.txt └── index.txt ├── _static ├── Emscripten_logo_full.png ├── _sphinx_javascript_frameworks_compat.js ├── ajax-loader.gif ├── basic.css ├── comment-bright.png ├── comment-close.png ├── comment.png ├── css │ ├── badge_only.css │ ├── fonts │ │ ├── Roboto-Slab-Bold.woff │ │ ├── Roboto-Slab-Bold.woff2 │ │ ├── Roboto-Slab-Regular.woff │ │ ├── Roboto-Slab-Regular.woff2 │ │ ├── fontawesome-webfont.eot │ │ ├── fontawesome-webfont.svg │ │ ├── fontawesome-webfont.ttf │ │ ├── fontawesome-webfont.woff │ │ ├── fontawesome-webfont.woff2 │ │ ├── lato-bold-italic.woff │ │ ├── lato-bold-italic.woff2 │ │ ├── lato-bold.woff │ │ ├── lato-bold.woff2 │ │ ├── lato-normal-italic.woff │ │ ├── lato-normal-italic.woff2 │ │ ├── lato-normal.woff │ │ └── lato-normal.woff2 │ └── theme.css ├── doctools.js ├── documentation_options.js ├── down-pressed.png ├── down.png ├── emscripten.ico ├── file.png ├── fonts │ ├── fontawesome-webfont.eot │ ├── fontawesome-webfont.svg │ ├── fontawesome-webfont.ttf │ └── fontawesome-webfont.woff ├── jquery-1.11.1.js ├── jquery-3.4.1.js ├── jquery.js ├── js │ └── theme.js ├── language_data.js ├── minus.png ├── plus.png ├── pygments.css ├── searchtools.js ├── sphinx_highlight.js ├── underscore-1.3.1.js ├── underscore.js ├── up-pressed.png ├── up.png └── websupport.js ├── docs ├── api_reference │ ├── Filesystem-API.html │ ├── advanced-apis.html │ ├── bind.h.html │ ├── console.h.html │ ├── emscripten.h.html │ ├── fetch.html │ ├── fiber.h.html │ ├── html5.h.html │ ├── index.html │ ├── module.html │ ├── preamble.js.html │ ├── proxying.h.html │ ├── stack.h.html │ ├── trace.h.html │ ├── val.h.html │ ├── wasm_audio_worklets.html │ └── wasm_workers.html ├── building_from_source │ ├── configuring_emscripten_settings.html │ ├── index.html │ ├── toolchain_what_is_needed.html │ └── verify_emscripten_environment.html ├── compiling │ ├── Building-Projects.html │ ├── Contrib-Ports.html │ ├── Deploying-Pages.html │ ├── Dynamic-Linking.html │ ├── GitLab.html │ ├── Modularized-Output.html │ ├── Running-html-files-with-emrun.html │ ├── Travis.html │ ├── WebAssembly.html │ └── index.html ├── contributing │ ├── AUTHORS.html │ ├── contributing.html │ ├── developers_guide.html │ └── index.html ├── debugging │ └── Sanitizers.html ├── getting_started │ ├── FAQ.html │ ├── Tutorial.html │ ├── bug_reports.html │ ├── downloads.html │ ├── index.html │ └── test-suite.html ├── index.html ├── introducing_emscripten │ ├── Talks-and-Publications.html │ ├── about_emscripten.html │ ├── community.html │ ├── emscripten_license.html │ ├── index.html │ └── release_notes.html ├── optimizing │ ├── Module-Splitting.html │ ├── Optimizing-Code.html │ ├── Optimizing-WebGL.html │ └── Profiling-Toolchain.html ├── porting │ ├── Audio.html │ ├── Debugging.html │ ├── asyncify.html │ ├── connecting_cpp_and_javascript │ │ ├── Interacting-with-code.html │ │ ├── WebIDL-Binder.html │ │ ├── embind.html │ │ └── index.html │ ├── emscripten-runtime-environment.html │ ├── exceptions.html │ ├── files │ │ ├── Synchronous-Virtual-XHR-Backed-File-System-Usage.html │ │ ├── file_systems_overview.html │ │ ├── index.html │ │ └── packaging_files.html │ ├── guidelines │ │ ├── api_limitations.html │ │ ├── browser_limitations.html │ │ ├── function_pointer_issues.html │ │ ├── index.html │ │ └── portability_guidelines.html │ ├── index.html │ ├── multimedia_and_graphics │ │ ├── EGL-Support-in-Emscripten.html │ │ ├── OpenGL-support.html │ │ └── index.html │ ├── networking.html │ ├── pthreads.html │ ├── setjmp-longjmp.html │ └── simd.html ├── site │ ├── about.html │ ├── glossary.html │ └── index.html └── tools_reference │ ├── emcc.html │ ├── emcmdprompt.html │ ├── emsdk.html │ ├── index.html │ └── settings_reference.html ├── favicon.ico ├── genindex.html ├── index.html ├── objects.inv ├── old-CNAME ├── search.html └── searchindex.js /.gitignore: -------------------------------------------------------------------------------- 1 | *~ 2 | 3 | -------------------------------------------------------------------------------- /.nojekyll: -------------------------------------------------------------------------------- 1 | "Stop Jekyll from running on our Sphinx output" 2 | -------------------------------------------------------------------------------- /.well-known/atproto-did: -------------------------------------------------------------------------------- 1 | did:plc:ynytall76qraih77z4gfwomw 2 | -------------------------------------------------------------------------------- /CNAME: -------------------------------------------------------------------------------- 1 | emscripten.org -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | How to build: 3 | 4 | 1. In the emscripten repo, go to site/ 5 | 2. Run make clean (to ensure old files are not present) 6 | 3. Run make html (you need sphinx installed) 7 | 4. Copy site/build/html into here 8 | 9 | (This repo is just for the gh-pages branch to host the site.) 10 | 11 | -------------------------------------------------------------------------------- /_images/FileSystemArchitecture.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_images/FileSystemArchitecture.png -------------------------------------------------------------------------------- /_images/device-orientation-axes.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_images/device-orientation-axes.png -------------------------------------------------------------------------------- /_sources/docs/api_reference/advanced-apis.rst.txt: -------------------------------------------------------------------------------- 1 | .. _api-reference-advanced-apis: 2 | 3 | ============= 4 | Advanced APIs 5 | ============= 6 | 7 | This section lists APIs that are not suitable for general use, but which may be 8 | useful to developers in some circumstances. These include APIs that are 9 | difficult or complicated to use, or which are intended primarily for developers 10 | working on the Emscripten core. 11 | 12 | .. contents:: Table of Contents 13 | :local: 14 | :depth: 1 15 | 16 | 17 | .. _settings-js: 18 | 19 | settings.js 20 | =========== 21 | 22 | `settings.js`_ contains default values and options used in various places by the 23 | compiler. 24 | 25 | .. Warning:: Many **settings.js** options are highly brittle - certain 26 | combinations of options, and combinations of certain options used with some 27 | source code, can cause Emscripten to fail badly. This is intended for use by 28 | "advanced users", and possibly even only people developing Emscripten itself. 29 | 30 | The options in **settings.js** are normally set as command line parameters to 31 | *emcc*:: 32 | 33 | emcc -sOPT=VALUE 34 | 35 | While it is possible to edit **settings.js** manually, this is *highly 36 | discouraged*. In general **settings.js** defines low-level options that should 37 | not be modified. Note also that the compiler changes some options depending on 38 | other settings. For example, ``ASSERTIONS`` is enabled by default, but disabled 39 | in optimized builds (``-O1+``). 40 | 41 | .. note:: 42 | For more information on what options can be used to configure Emscripten, read 43 | ``src/settings.js`` or visit 44 | `the emsettings page `_. 45 | 46 | 47 | preamble.js 48 | =========== 49 | 50 | The following advanced APIs are documented in `preamble.js`_. 51 | 52 | .. js:function:: allocate(slab, allocator) 53 | 54 | This is marked as *internal* because it is difficult to use (it has been 55 | optimized for multiple syntaxes to save space in generated code). Normally 56 | developers should instead allocate memory using ``_malloc()``, initialize it 57 | with :js:func:`setValue`, etc., but this function may be useful for advanced 58 | developers in certain cases. 59 | 60 | :param slab: An array of data, or a number. If a number, then the size of the 61 | block to allocate, in *bytes*. 62 | :param allocator: How to allocate memory, see ALLOC_* 63 | 64 | 65 | Advanced File System API 66 | ======================== 67 | 68 | :ref:`Filesystem-API` covers the public API that will be relevant to most 69 | developers. The following functions are only needed for advanced use-cases (for 70 | example, writing a new local file system) or legacy file system compatibility. 71 | 72 | .. js:function:: FS.hashName(parentid, name) 73 | .. js:function:: FS.hashAddNode(node) 74 | .. js:function:: FS.hashRemoveNode(node) 75 | .. js:function:: FS.lookupNode(parent, name) 76 | .. js:function:: FS.createNode(parent, name, mode, rdev) 77 | .. js:function:: FS.destroyNode(node) 78 | .. js:function:: FS.isRoot(node) 79 | .. js:function:: FS.isMountpoint(node) 80 | .. js:function:: FS.isFIFO(node) 81 | .. js:function:: FS.nextfd() 82 | .. js:function:: FS.getStream(fd) 83 | .. js:function:: FS.createStream(stream, fd) 84 | .. js:function:: FS.closeStream(fd) 85 | .. js:function:: FS.getStreamFromPtr(ptr) 86 | .. js:function:: FS.getPtrForStream(stream) 87 | .. js:function:: FS.major(dev) 88 | .. js:function:: FS.minor(dev) 89 | .. js:function:: FS.getDevice(dev) 90 | .. js:function:: FS.getMounts(mount) 91 | .. js:function:: FS.lookup(parent, name) 92 | .. js:function:: FS.mknod(path, mode, dev) 93 | .. js:function:: FS.create(path, mode) 94 | .. js:function:: FS.mmap(stream, buffer, offset, length, position, prot, flags) 95 | .. js:function:: FS.ioctl(stream, cmd, arg) 96 | .. js:function:: FS.staticInit() 97 | .. js:function:: FS.quit() 98 | .. js:function:: FS.indexedDB() 99 | .. js:function:: FS.DB_NAME() 100 | 101 | For advanced users only. 102 | 103 | .. js:function:: FS.getMode(canRead, canWrite) 104 | .. js:function:: FS.findObject(path, dontResolveLastLink) 105 | .. js:function:: FS.createPath(parent, path, canRead, canWrite) 106 | .. js:function:: FS.createFile(parent, name, properties, canRead, canWrite) 107 | .. js:function:: FS.createDataFile(parent, name, data, canRead, canWrite, canOwn) 108 | .. js:function:: FS.createDevice(parent, name, input, output) 109 | .. js:function:: FS.forceLoadFile(obj) 110 | 111 | Legacy v1 compatibility functions. 112 | 113 | 114 | There are also a small number of additional :ref:`flag modes `: 115 | 116 | - ``rs`` 117 | - ``xw`` 118 | - ``xw+`` 119 | - ``xa`` 120 | - ``xa+`` 121 | 122 | .. _settings.js: https://github.com/emscripten-core/emscripten/blob/main/src/settings.js 123 | .. _preamble.js: https://github.com/emscripten-core/emscripten/blob/main/src/preamble.js 124 | -------------------------------------------------------------------------------- /_sources/docs/api_reference/advanced-apis.txt: -------------------------------------------------------------------------------- 1 | .. _api-reference-advanced-apis: 2 | 3 | ============= 4 | Advanced APIs 5 | ============= 6 | 7 | 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. 8 | 9 | .. contents:: Table of Contents 10 | :local: 11 | :depth: 1 12 | 13 | 14 | .. _settings-js: 15 | 16 | settings.js 17 | ============ 18 | 19 | `settings.js `_ contains default values and options used in various places by the compiler. 20 | 21 | .. 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. 22 | 23 | 24 | The options in **settings.js** are normally set as command line parameters to *emcc*: :: 25 | 26 | emcc -s OPT=VALUE 27 | 28 | 29 | 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+``). 30 | 31 | 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``: :: 32 | 33 | ./emcc tests/hello_function.cpp -o function.html -s EXPORTED_FUNCTIONS="['_int_sqrt']" 34 | 35 | 36 | preamble.js 37 | =========== 38 | 39 | The following advanced APIs are documented in `preamble.js `_. 40 | 41 | .. js:function:: allocate(slab, types, allocator, ptr) 42 | 43 | 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. 44 | 45 | :param slab: An array of data, or a number. If a number, then the size of the block to allocate, in *bytes*. 46 | :param types: Either an array of types, one for each byte (or 0 if no type at that position), or a single type which is used for the entire block. This only matters if there is initial data - if ``slab`` is a number, then this value does not matter at all and is ignored. 47 | :param allocator: How to allocate memory, see ALLOC_* 48 | 49 | 50 | Advanced File System API 51 | ======================== 52 | 53 | :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. 54 | 55 | .. js:function:: FS.handleFSError(e) 56 | FS.hashName(parentid, name) 57 | FS.hashAddNode(node) 58 | FS.hashRemoveNode(node) 59 | FS.lookupNode(parent, name) 60 | FS.createNode(parent, name, mode, rdev) 61 | FS.destroyNode(node) 62 | FS.isRoot(node) 63 | FS.isMountpoint(node) 64 | FS.isFIFO(node) 65 | FS.nextfd(fd_start, fd_end) 66 | FS.getStream(fd) 67 | FS.createStream(stream, fd_start, fd_end) 68 | FS.closeStream(fd) 69 | FS.getStreamFromPtr(ptr) 70 | FS.getPtrForStream(stream) 71 | FS.major(dev) 72 | FS.minor(dev) 73 | FS.getDevice(dev) 74 | FS.getMounts(mount) 75 | FS.lookup(parent, name) 76 | FS.mknod(path, mode, dev) 77 | FS.create(path, mode) 78 | FS.readdir(path) 79 | FS.allocate(stream, offset, length) 80 | FS.mmap(stream, buffer, offset, length, position, prot, flags) 81 | FS.ioctl(stream, cmd, arg) 82 | FS.staticInit() 83 | FS.quit() 84 | FS.indexedDB() 85 | FS.DB_NAME() 86 | FS.saveFilesToDB(paths, onload, onerror) 87 | FS.loadFilesFromDB(paths, onload, onerror) 88 | 89 | For advanced users only. 90 | 91 | 92 | .. js:function:: FS.getMode(canRead, canWrite) 93 | FS.joinPath(parts, forceRelative) 94 | FS.absolutePath(relative, base) 95 | FS.standardizePath(path) 96 | FS.findObject(path, dontResolveLastLink) 97 | FS.createFolder(parent, name, canRead, canWrite) 98 | FS.createPath(parent, path, canRead, canWrite) 99 | FS.createFile(parent, name, properties, canRead, canWrite) 100 | FS.createDataFile(parent, name, data, canRead, canWrite, canOwn) 101 | FS.createDevice(parent, name, input, output) 102 | FS.createLink(parent, name, target, canRead, canWrite) 103 | FS.forceLoadFile(obj) 104 | 105 | Legacy v1 compatibility functions. 106 | 107 | 108 | There are also a small number of additional :ref:`flag modes `: 109 | 110 | - ``rs`` 111 | - ``xw`` 112 | - ``xw+`` 113 | - ``xa`` 114 | - ``xa+`` 115 | -------------------------------------------------------------------------------- /_sources/docs/api_reference/console.h.rst.txt: -------------------------------------------------------------------------------- 1 | .. _console-h: 2 | 3 | ========= 4 | console.h 5 | ========= 6 | 7 | Functions 8 | --------- 9 | 10 | .. c:function:: void emscripten_console_log(const char *utf8String) 11 | 12 | Prints a string using ``console.log()``. 13 | 14 | :param utf8String: A string encoded as UTF-8. 15 | 16 | 17 | .. c:function:: void emscripten_console_warn(const char *utf8String) 18 | 19 | Prints a string using ``console.warn()``. 20 | 21 | :param utf8String: A string encoded as UTF-8. 22 | 23 | 24 | .. c:function:: void emscripten_console_error(const char *utf8String) 25 | 26 | Prints a string using ``console.error()``. 27 | 28 | :param utf8String: A string encoded as UTF-8. 29 | 30 | 31 | .. c:function:: void emscripten_out(const char *utf8String) 32 | 33 | Prints a string using the `out()` JS function, which by default will write to 34 | the console (or stdout), but can be overridden by via the ``print`` attribute 35 | on the ``Module`` object. 36 | 37 | :param utf8String: A string encoded as UTF-8. 38 | 39 | 40 | .. c:function:: void emscripten_err(const char *utf8String) 41 | 42 | Prints a string using the `err()` JS function, which by default will write to 43 | the console (or stderr), but can be overridden by via the ``printErr`` 44 | attribute on the ``Module`` object. 45 | 46 | :param utf8String: A string encoded as UTF-8. 47 | 48 | 49 | .. c:function:: void emscripten_dbg(const char *utf8String) 50 | 51 | Prints the string using the `dbg()` JS function, which by will write to the 52 | console (or stdout). Just like the `dbg()` JS function this symbol is 53 | only available in debug builds (i.e. when linking with `-sASSERTIONS` or 54 | equivelently `-O0`). 55 | 56 | :param utf8String: A string encoded as UTF-8. 57 | -------------------------------------------------------------------------------- /_sources/docs/api_reference/index.rst.txt: -------------------------------------------------------------------------------- 1 | .. _api-reference-index: 2 | 3 | ============= 4 | API Reference 5 | ============= 6 | 7 | This section lists Emscripten's public API, organised by header file. At a very 8 | high level it consists of: 9 | 10 | - :ref:`emscripten-h`: 11 | APIs for integrating with the browser environment. 12 | 13 | - :ref:`html5-h`: 14 | Low level glue bindings for interfacing with HTML5 APIs from native code. 15 | 16 | - :ref:`console-h`: 17 | Functions to writing to the console and stdout/stderr. 18 | 19 | - :ref:`preamble-js`: 20 | APIs for working with compiled code from JavaScript. 21 | 22 | - :ref:`Filesystem-API` (**library_fs.js**): 23 | APIs for managing file systems and synchronous file operations. 24 | 25 | - :ref:`Fetch-API`: 26 | API for managing accesses to network XHR and IndexedDB. 27 | 28 | - :ref:`wasm workers section`: 29 | Enables writing multithreaded programs using a web-like API. 30 | 31 | - :ref:`wasm_audio_worklets`: 32 | Allows programs to implement audio processing nodes that run in a dedicated real-time audio processing thread context. 33 | 34 | - :ref:`Module`: 35 | Global JavaScript object that can be used to control code execution and access 36 | exported methods. 37 | 38 | - :ref:`val-h`: 39 | Embind API to support transliteration of JavaScript code to C++. 40 | 41 | - :ref:`bind-h`: 42 | Embind API for binding C++ functions and classes so that they can be called 43 | from JavaScript in a natural way. 44 | 45 | - :ref:`trace-h`: 46 | A tracing API for doing memory usage analysis. 47 | 48 | - :ref:`fiber-h`: 49 | API for working with Fibers (co-operative threads) 50 | 51 | - :ref:`proxying-h`: 52 | API for synchronously or asynchronously proxying work to a target pthread. 53 | 54 | - :ref:`stack-h`: 55 | Inspecting the WebAssembly data stack. 56 | 57 | - :ref:`api-reference-advanced-apis`: 58 | APIs for advanced users/core developers. 59 | 60 | 61 | .. toctree:: 62 | :hidden: 63 | 64 | emscripten.h 65 | html5.h 66 | console.h 67 | preamble.js 68 | Filesystem-API 69 | fetch 70 | module 71 | val.h 72 | bind.h 73 | trace.h 74 | fiber.h 75 | proxying.h 76 | stack.h 77 | wasm_workers 78 | wasm_audio_worklets 79 | advanced-apis 80 | -------------------------------------------------------------------------------- /_sources/docs/api_reference/index.txt: -------------------------------------------------------------------------------- 1 | .. _api-reference-index: 2 | 3 | ============= 4 | API Reference 5 | ============= 6 | 7 | This section lists Emscripten's public API, organised by header file. At a very high level it consists of: 8 | 9 | - :ref:`emscripten-h`: 10 | APIs for integrating with the browser environment. 11 | 12 | - :ref:`html5-h`: 13 | Low level glue bindings for interfacing with HTML5 APIs from native code. 14 | 15 | - :ref:`preamble-js`: 16 | APIs for working with compiled code from JavaScript. 17 | 18 | - :ref:`Filesystem-API` (**library_fs.js**): 19 | APIs for managing file systems and synchronous file operations. 20 | 21 | - :ref:`Fetch-API`: 22 | API for managing accesses to network XHR and IndexedDB. 23 | 24 | - :ref:`Module`: 25 | Global JavaScript object that can be used to control code execution and access exported methods. 26 | 27 | - :ref:`val-h`: 28 | Embind API to support transliteration of JavaScript code to C++. 29 | 30 | - :ref:`bind-h`: 31 | Embind API for binding C++ functions and classes so that they can be called from JavaScript in a natural way. 32 | 33 | - :ref:`trace-h`: 34 | A tracing API for doing memory usage analysis. 35 | 36 | - :ref:`vr-h`: 37 | API for using WebVR from native code. 38 | 39 | - :ref:`fiber-h`: 40 | API for working with Fibers (co-operative threads) 41 | 42 | - :ref:`api-reference-advanced-apis`: 43 | APIs for advanced users/core developers. 44 | 45 | 46 | .. toctree:: 47 | :hidden: 48 | 49 | emscripten.h 50 | html5.h 51 | preamble.js 52 | Filesystem-API 53 | fetch 54 | module 55 | val.h 56 | bind.h 57 | trace.h 58 | vr.h 59 | fiber.h 60 | advanced-apis 61 | 62 | 63 | -------------------------------------------------------------------------------- /_sources/docs/api_reference/stack.h.rst.txt: -------------------------------------------------------------------------------- 1 | .. _stack-h: 2 | 3 | ======= 4 | stack.h 5 | ======= 6 | 7 | The functions defined in `` allow inspecting 8 | information about the WebAssembly data stack (sometimes called the 9 | "user stack" or the "C stack"). This data stack is the data contained 10 | within the linear memory (as opposed to the trusted call stack that 11 | is managed by the VM, and which is not visible to the running program). 12 | 13 | .. c:function:: uintptr_t emscripten_stack_get_base(void) 14 | 15 | Returns the starting address of the stack. This is the address 16 | that the stack pointer would point to when no bytes are in use on the 17 | stack. 18 | 19 | .. c:function:: uintptr_t emscripten_stack_get_end(void) 20 | 21 | Returns the end address of the stack. This is the address that 22 | the stack pointer would point to when the whole stack is in use. (The 23 | address pointed to by the end is not part of the stack itself). Note 24 | that the stack grows down so the address returned by 25 | `emscripten_stack_get_end()` is smaller than 26 | :c:func:`emscripten_stack_get_base()`. 27 | 28 | .. c:function:: void emscripten_stack_set_limits(void* base, void* end) 29 | 30 | Sets the internal values reported by :c:func:`emscripten_stack_get_base()` 31 | and :c:func:`emscripten_stack_get_end()`. This should only be used by low 32 | level libraries such as asyncify fibers. 33 | 34 | .. c:function:: uintptr_t emscripten_stack_get_current(void) 35 | 36 | Returns the current stack pointer. 37 | 38 | .. c:function:: size_t emscripten_stack_get_free(void) 39 | 40 | Returns the number of free bytes left on the stack. This is required 41 | to be fast so that it can be called frequently. 42 | -------------------------------------------------------------------------------- /_sources/docs/building_from_source/LLVM-Backend.rst.txt: -------------------------------------------------------------------------------- 1 | .. _LLVM-Backend: 2 | 3 | ========================= 4 | LLVM Backend ("Fastcomp") 5 | ========================= 6 | 7 | This article introduces *Fastcomp*, Emscripten's LLVM + Clang implementation. It explains how you can obtain the tool, why it replaced the :ref:`original compiler core `, and how you can turn off *Fastcomp* if needed. There is also a :ref:`fastcomp-faq` at the very end for troubleshooting *Fastcomp* problems. 8 | 9 | 10 | Fastcomp overview 11 | ================= 12 | 13 | *Fastcomp* is the default compiler core for Emscripten. Implemented as an :term:`LLVM backend`, its role is to convert the LLVM Intermediate Representation (IR) created by :term:`Clang` (from C/C++) into JavaScript. 14 | 15 | *Fastcomp* has the following features: 16 | 17 | - It is tightly integrated with LLVM (as an LLVM-backend) 18 | - It has a core focus on **asm.js** code generation, which has been shown to give the best results. 19 | - When compared to the previous compiler it is much faster (often 4x faster or more), uses less memory, and produces better code. 20 | 21 | Fastcomp is maintained in two repositories: 22 | 23 | - https://github.com/emscripten-core/emscripten-fastcomp (LLVM) 24 | - https://github.com/emscripten-core/emscripten-fastcomp-clang (Clang) 25 | 26 | Getting Fastcomp 27 | ================ 28 | 29 | *Fastcomp* (Clang) is part of the :ref:`Emscripten SDK `, and the binaries are automatically provided during installation (except on Linux, where pre-built binaries are not supplied so the SDK builds them for you). 30 | 31 | If you need to build from source you can: 32 | 33 | - :ref:`Use the SDK ` (these instructions show how to build the whole of Emscripten, including *Fastcomp*). 34 | - :ref:`Build using a fully manual process `. 35 | 36 | .. warning:: The backend is still too new to be in the upstream LLVM repository. As such, builds from Linux distributions will **not** contain *Fastcomp*, and Emscripten will report an error if you try to use them. 37 | 38 | 39 | .. _original-compiler-core: 40 | 41 | Original compiler core (deprecated) 42 | =================================== 43 | 44 | The original compiler supported dozens of different code generation modes (no-typed arrays, typed arrays in various modes, **asm.js** vs. **non-asm.js**, etc.), many of which were not very efficient. Over time, the compiler became harder to maintain and was susceptible to unpredictable compiler slow-downs. 45 | 46 | *Fastcomp* was turned on by default in version 1.12.1. The original compiler is now "deprecated". 47 | 48 | .. note:: While it is possible to manually disable Fastcomp and build the original compiler from source, this is discouraged. 49 | 50 | 51 | Why did this change happen? 52 | --------------------------- 53 | 54 | As a result of the problems with the original compiler, we developed *Fastcomp*, which is a much better compiler: 55 | 56 | - It is much more streamlined than the original compiler. It focuses on **asm.js** code generation, which has been shown to give the best results. 57 | - It is much faster and has more predictable performance (often 4x faster or more). 58 | - It requires much less memory. 59 | - It generates better code because, as an LLVM backend, it integrates more tightly with LLVM. 60 | 61 | 62 | Are there downsides? 63 | -------------------- 64 | 65 | The main downside is that Emscripten can no longer use a stock build of LLVM, because we have made changes that must be built with LLVM. 66 | 67 | There are also a few features that were present in the original compiler that are not present in *Fastcomp* (see the next section). 68 | 69 | .. note:: We hope that the new Emscripten backend will eventually become part of the upstream LLVM, and hence become available in stock builds. 70 | 71 | Features not present in Fastcomp 72 | -------------------------------- 73 | 74 | Some features that were present in the original compiler that are not present in *Fastcomp* include: 75 | 76 | - Various deprecated **settings.js** options (``FORCE_ALIGNMENT``, ``HEAP_INIT``, etc.) You should receive a compile-time error if you use a setting which is not supported. 77 | - Linking of **asm.js** shared modules. This is not deprecated, but may need to be reconsidered. 78 | 79 | .. note:: Normal static linking as used by almost all projects works fine; it is just specifically the options ``MAIN_MODULE`` and ``SIDE_MODULE`` that do not work. 80 | 81 | 82 | How to disable Fastcomp 83 | ----------------------- 84 | 85 | Fastcomp is now the only supported compiler and the old compiler has been removed from emscripten. 86 | 87 | 88 | .. _fastcomp-faq: 89 | 90 | FAQ 91 | === 92 | 93 | I see ``WARNING: Linking two modules of different target triples`` [..] ``'asmjs-unknown-emscripten' and 'le32-unknown-nacl'``..? 94 | --------------------------------------------------------------------------------------------------------------------------------- 95 | 96 | You are linking together bitcode files compiled with the old compiler (or older versions of *Fastcomp*) with bitcode files from the new one. This may work in some cases but is dangerous and should be avoided. To fix it, just recompile all your bitcode with the new compiler. 97 | 98 | -------------------------------------------------------------------------------- /_sources/docs/building_from_source/building_emscripten_from_source_on_linux.rst.txt: -------------------------------------------------------------------------------- 1 | .. _building-emscripten-on-linux: 2 | 3 | ===================================== 4 | Manually Building Emscripten on Linux 5 | ===================================== 6 | 7 | This page contains basic instructions on how to manually build and configure Emscripten from source on a clean (Ubuntu 14.04.1 LTS 64bit) Linux box. 8 | 9 | .. note:: The instructions clone from the main Emscripten repository (https://github.com/emscripten-core/emscripten). :ref:`Contributors ` should instead clone from their own Emscripten fork, and submit changes as pull requests. 10 | 11 | .. tip:: You can also build Emscripten from source :ref:`using the SDK `. This is recommended if you need easily switch between SDK and source builds. 12 | 13 | What you'll need 14 | ================= 15 | 16 | The specific versions of tools that are needed are listed in the :ref:`Emscripten Toolchain Requirements `. 17 | 18 | 19 | Installing required tools 20 | ========================== 21 | 22 | These instructions explain how to install **all** the :ref:`required tools `. You can :ref:`test whether some of these are already installed ` on the platform and skip those steps. 23 | 24 | 1. Update the *system package manager* to ensure the package lists are up to date:: 25 | 26 | sudo apt-get update 27 | 28 | 29 | #. Install *Python* using the *system package manager*:: 30 | 31 | sudo apt-get install python2.7 32 | 33 | 34 | #. Install `node.js `_ using the *system package manager*:: 35 | 36 | sudo apt-get install nodejs 37 | 38 | 39 | #. Install *gcc* and *cmake* using the *system package manager*:: 40 | 41 | sudo apt-get install build-essential 42 | sudo apt-get install cmake 43 | 44 | 45 | #. Install *git* using the *system package manager*:: 46 | 47 | sudo apt-get install git-core 48 | 49 | #. Install *Java* using the *system package manager*:: 50 | 51 | sudo apt-get install default-jre 52 | 53 | #. Build :ref:`Fastcomp ` (LLVM + Clang) from source using :ref:`these instructions `. 54 | 55 | #. Clone the `emscripten-core/emscripten `_ repository from GitHub. This repository contains the main compiler tool for compiling C/C++ programs to JavaScript: 56 | 57 | - Create a directory (with no spaces in the name) to contain the clone. 58 | - Enter the following command into the terminal:: 59 | 60 | git clone https://github.com/emscripten-core/emscripten.git 61 | 62 | 63 | Configuring Emscripten settings 64 | =============================== 65 | 66 | Almost all the compiler settings used by Emscripten are defined in the :ref:`compiler configuration file (~/.emscripten) `, a user-specific file located in the user's home directory. 67 | 68 | Instructions for creating and manually configuring up this file are given in :ref:`configuring-emscripten-settings`. 69 | 70 | 71 | Validating the environment 72 | =============================== 73 | 74 | The best way to validate the environment is to build some code. Open the terminal in your *Emscripten* directory (where *emcc* is located) and enter: :: 75 | 76 | ./emcc tests/hello_world.cpp 77 | 78 | If this builds **a.out.js** in the current directory, and you don't see any build errors in the terminal, Emscripten is good to go! 79 | 80 | There are additional validation and troubleshooting instructions in the topic: :ref:`verifying-the-emscripten-environment`. 81 | 82 | 83 | 84 | -------------------------------------------------------------------------------- /_sources/docs/building_from_source/building_emscripten_from_source_on_mac_os_x.rst.txt: -------------------------------------------------------------------------------- 1 | .. _building-emscripten-on-macos-from-source: 2 | 3 | ===================================== 4 | Manually Building Emscripten on macOS 5 | ===================================== 6 | 7 | This page contains basic instructions on how to manually build and configure Emscripten from source on a clean macOS box (tested on macOS version 10.8.2). 8 | 9 | .. note:: The instructions clone from the main Emscripten repository (https://github.com/emscripten-core/emscripten). :ref:`Contributors ` should instead clone from their own Emscripten fork, and submit changes as pull requests. 10 | 11 | .. tip:: You can also build Emscripten from source :ref:`using the SDK `. This is recommended if you need easily switch between SDK and source builds. 12 | 13 | What you'll need 14 | ================ 15 | 16 | The specific versions of tools that are needed are listed in the :ref:`Emscripten Toolchain Requirements `. 17 | 18 | 19 | Installing required tools 20 | ========================= 21 | 22 | These instructions explain how to install **all** the :ref:`required tools `. You can :ref:`test whether some of these are already installed ` on the platform and skip those steps. 23 | 24 | #. Install the *Xcode Command Line Tools*. These include the toolchain to build :term:`Fastcomp`, and are a precondition for *git*. 25 | 26 | - Install Xcode from the `macOS App Store `_. 27 | - In **Xcode | Preferences | Downloads**, install *Command Line Tools*. 28 | 29 | #. Install *git*: 30 | 31 | - `Allow installation of unsigned packages `_, or installing the git package won't succeed. 32 | - Install Xcode and the Xcode Command Line Tools (should already have been done). This will provide *git* to the system PATH (see `this stackoverflow post `_). 33 | - Download and install git directly from http://git-scm.com/. 34 | 35 | #. Install *CMake* if you do not have it yet: 36 | 37 | - Download and install `CMake `_, and make sure it is available in PATH after installation. 38 | 39 | #. Install *node.js* from http://nodejs.org/ 40 | 41 | 42 | .. _getting-started-on-macos-install-python2: 43 | 44 | #. Build :ref:`Fastcomp ` (LLVM + Clang) from source using :ref:`these instructions `. 45 | 46 | #. Clone the `emscripten-core/emscripten `_ repository from GitHub. This repository contains the main compiler tool for compiling C/C++ programs to JavaScript: 47 | 48 | - Create a directory (with no spaces in the name) to contain the clone. 49 | - Enter the following command into the terminal: :: 50 | 51 | git clone https://github.com/emscripten-core/emscripten.git 52 | 53 | 54 | 55 | 56 | Configuring Emscripten settings 57 | =============================== 58 | 59 | Almost all the compiler settings used by Emscripten are defined in the :ref:`compiler configuration file (~/.emscripten) `, a user-specific file located in the user's home directory. 60 | 61 | Instructions for creating and manually configuring up this file are given in :ref:`configuring-emscripten-settings`. 62 | 63 | 64 | Validating the environment 65 | =============================== 66 | 67 | The best way to validate the environment is to build some code. Open the terminal in your *Emscripten* directory (where *emcc* is located) and enter: :: 68 | 69 | ./emcc tests/hello_world.cpp 70 | 71 | If this builds **a.out.js** in the current directory, and you don't see any build errors in the terminal, Emscripten is good to go! 72 | 73 | There are additional validation and troubleshooting instructions in the topic: :ref:`verifying-the-emscripten-environment`. 74 | 75 | 76 | 77 | 78 | 79 | -------------------------------------------------------------------------------- /_sources/docs/building_from_source/building_emscripten_from_source_on_windows.rst.txt: -------------------------------------------------------------------------------- 1 | .. _building-emscripten-on-windows-from-source: 2 | 3 | ======================================= 4 | Manually Building Emscripten on Windows 5 | ======================================= 6 | 7 | This page contains basic instructions on how to manually build and configure Emscripten from source on a clean Windows box. 8 | 9 | .. note:: The instructions clone from the main Emscripten repository (https://github.com/emscripten-core/emscripten). :ref:`Contributors ` should instead clone from their own Emscripten fork, and submit changes as pull requests. 10 | 11 | .. tip:: You can also build Emscripten from source :ref:`using the SDK `. This is recommended if you need to easily switch between SDK and source builds. 12 | 13 | 14 | What you'll need 15 | ================= 16 | 17 | The specific versions of tools that are needed are listed in the :ref:`Emscripten Toolchain Requirements `. 18 | 19 | .. note:: 64-bit versions of all needed dependencies are preferred, and may be required if you are building large projects. 20 | 21 | Installing required tools 22 | ========================== 23 | 24 | These instructions explain how to install **all** the :ref:`required tools `. You can :ref:`test whether some of these are already installed ` on the platform and skip those steps. 25 | 26 | 27 | #. Install `Python `_: 28 | 29 | - Python v2.7 is currently preferred, although experimental support for Python3 exists. 30 | - Add the path to the Python directory containing **Python.exe** to your PATH. 31 | 32 | - Paths are set by opening **System Settings | Advanced system properties**, clicking **Environment Variables** and selecting **PATH**. 33 | - Add the path to python, separated by semicolons: e.g. ``;C:/Python27/;`` or ``;C:/Python27/bin;`` (depending on the location of the exe). 34 | 35 | 36 | #. Install `node.js `_: 37 | 38 | - Version 8.9.1 or newer is needed. 39 | 40 | 41 | #. Install `Visual Studio 2017 `_. 42 | 43 | #. Install `cmake `_. 44 | 45 | #. Install `GitHub for Windows `_ (or any other git client). 46 | 47 | #. Install `Java `_ (Java is optional, you only need it for Closure Compiler minification). 48 | 49 | #. Build :ref:`Fastcomp ` (LLVM + Clang) from source using :ref:`these instructions `. 50 | 51 | #. Clone the `emscripten-core/emscripten `_ repository from GitHub. This repository contains the main compiler tool for compiling C/C++ programs to JavaScript: 52 | 53 | - Using *GitHub for Windows*: 54 | - Launch the *GitHub for Windows* client. Click **Skip Setup** if you don't have a GitHub account. 55 | - (optional) Select **Options** from the gear menu, and customize the default storage directory. Ensure the path has no spaces. 56 | - In your web browser, open https://github.com/emscripten-core/emscripten and press the **Clone in Windows** button. 57 | 58 | - Using the command line: 59 | - Create a directory (with no spaces in the name) to contain the clone. 60 | - Enter the following command into the terminal: :: 61 | 62 | git clone https://github.com/emscripten-core/emscripten.git 63 | 64 | 65 | 66 | 67 | Configuring Emscripten settings 68 | =============================== 69 | 70 | Almost all the compiler settings used by Emscripten are defined in the :ref:`compiler configuration file (.emscripten) `, a user-specific file located in the user's home directory. 71 | 72 | Instructions for creating and manually configuring this file are given in :ref:`configuring-emscripten-settings`. 73 | 74 | 75 | 76 | Validating the environment 77 | =============================== 78 | 79 | The best way to validate the environment is to build some code. Open the terminal in your *Emscripten* directory — the directory that contains *emcc* (if you installed using *GitHub for Windows* this will be **C:/Users/username/Documents/GitHub/emscripten**) and enter: :: 80 | 81 | ./emcc tests/hello_world.cpp 82 | 83 | If this builds **a.out.js** in the current directory, and you don't see any build errors in the terminal, Emscripten is good to go! 84 | 85 | There are additional validation and troubleshooting instructions in the topic :ref:`verifying-the-emscripten-environment`. 86 | 87 | 88 | 89 | -------------------------------------------------------------------------------- /_sources/docs/building_from_source/configuring_emscripten_settings.rst.txt: -------------------------------------------------------------------------------- 1 | .. _configuring-emscripten-settings: 2 | 3 | ================================================================== 4 | Configuring Emscripten Settings when Manually Building from Source 5 | ================================================================== 6 | 7 | Emscripten can be configured via a :ref:`compiler 8 | configuration file (.emscripten) `. These settings 9 | include paths to the tools (LLVM, Clang, Binaryen, etc.) and the compiler's 10 | temporary directory for intermediate build files. 11 | 12 | This configuration file is optional. By default, emscripten will search 13 | for the tools it needs in the ``PATH``. 14 | 15 | This article explains how to create and update the file when you are building 16 | Emscripten :ref:`manually ` from source. 17 | 18 | 19 | Creating the compiler configuration file 20 | ======================================== 21 | 22 | A settings file may be used when running :ref:`emcc ` (or any of the 23 | other Emscripten tools). You can run ``emcc`` with ``--generate-config`` 24 | in order to generate one in the default location. 25 | 26 | 1. Navigate to the directory where you cloned the Emscripten repository. 27 | 2. Enter the command: 28 | 29 | :: 30 | 31 | ./emcc --generate-config 32 | 33 | You should get a ``An Emscripten settings file has been generated at:`` 34 | message, along with the contents of the config file. 35 | 36 | When generating this file Emscripten will make its "best guess" at the correct 37 | locations for tools based on the current ``PATH``. 38 | 39 | In most cases it will be necessary to edit the generated file and modify 40 | least the ``LLVM_ROOT`` and ``BINARYEN_ROOT`` settings to point to the correct 41 | locations for your local LLVM and Binaryen installations. 42 | 43 | 44 | Locating the compiler configuration file (.emscripten) 45 | ====================================================== 46 | 47 | The settings file (``.emscripten``) is created by default within the emscripten 48 | directory (alongsize ``emcc`` itself). In cases where the emscripten directory 49 | is read-only the user's home directory will be used: 50 | 51 | - On Linux and macOS this file is named **~/.emscripten**, where ~ is the 52 | user's home directory. 53 | 54 | .. note:: Files with the "." prefix are hidden by default. You may need to change your view settings to find the file. 55 | 56 | - On Windows the file can be found at a path like: **C:/Users/yourusername_000/.emscripten**. 57 | 58 | 59 | Compiler configuration file-format 60 | ================================== 61 | 62 | .. note:: While the syntax is identical, the appearance of the default **.emscripten** file created by *emcc* is quite different than that created by :ref:`emsdk `. This is because *emsdk* manages multiple target environments, and where possible hard codes the locations of those tools when a new environment is activated. The default file, by contrast, is managed by the user — and is designed to make that task as easy as possible. 63 | 64 | The file simply assigns values to a number of *variables* representing the main 65 | tools used by Emscripten. For example, if your binaryen installation is in 66 | **C:\\tools\\binaryen\\**, then the file might contain the line: :: 67 | 68 | BINARYEN_ROOT = 'C:\\tools\\binaryen\\' 69 | 70 | You can find out the other variable names from the default *.emscripten* file or 71 | the :ref:`example here `. 72 | 73 | Editing the compiler configuration file 74 | ======================================= 75 | 76 | The compiler configuration file can be edited with the text editor of your 77 | choice. If you're building manually from source, you are most likely to have to 78 | update the variable ``LLVM_ROOT`` 79 | 80 | #. Edit the variable ``LLVM_ROOT`` to point to the directory where you built the 81 | LLVM binaries, such as: 82 | 83 | :: 84 | 85 | LLVM_ROOT = '/home/ubuntu/a-path/llvm/build/bin' 86 | 87 | .. note:: Use forward slashes! 88 | 89 | After setting those paths, run ``emcc`` again. It should again perform the sanity checks to test the specified paths. There are further validation tests available at :ref:`verifying-the-emscripten-environment`. 90 | -------------------------------------------------------------------------------- /_sources/docs/building_from_source/configuring_emscripten_settings.txt: -------------------------------------------------------------------------------- 1 | .. _configuring-emscripten-settings: 2 | 3 | ================================================================== 4 | Configuring Emscripten Settings when Manually Building from Source 5 | ================================================================== 6 | 7 | The compiler settings used by Emscripten are defined in the :ref:`compiler 8 | configuration file (.emscripten) `. These settings 9 | include paths to the tools (LLVM, Clang, Java, etc.) and the compiler's 10 | temporary directory for intermediate build files. 11 | 12 | This article explains how to create and update the file when you are building Emscripten :ref:`manually ` from source. 13 | 14 | 15 | Creating the compiler configuration file 16 | ======================================== 17 | 18 | The settings file is created the first time a user runs :ref:`emcc ` (or any of the other Emscripten tools): 19 | 20 | 1. Navigate to the directory where you cloned the Emscripten repository. 21 | 2. Enter the command: 22 | 23 | :: 24 | 25 | ./emcc --help 26 | 27 | You should get a ``Welcome to Emscripten!`` message. Behind the scenes, Emscripten generates a file called ``.emscripten`` in your home folder. 28 | 29 | 30 | Emscripten makes a "best guess" at the correct locations for tools and updates the file appropriately. Where possible it will look for "system" apps (like Python and Java). 31 | 32 | The file will probably not include the link to :term:`Fastcomp` (``LLVM_ROOT``) as a manual source build can create this anywhere. 33 | 34 | Locating the compiler configuration file (.emscripten) 35 | ======================================================= 36 | 37 | The settings file (``.emscripten``) is created by default within the emscripten directory: 38 | 39 | In cases where the emscripten directory is read-only the users home directoy 40 | will be used: 41 | 42 | - On Linux and macOS this file is named **~/.emscripten**, where ~ is the 43 | user's home directory. 44 | 45 | .. note:: Files with the "." prefix are hidden by default. You may need to change your view settings to find the file. 46 | 47 | - On Windows the file can be found at a path like: **C:/Users/yourusername_000/.emscripten**. 48 | 49 | 50 | Compiler configuration file-format 51 | ================================== 52 | 53 | .. note:: While the syntax is identical, the appearance of the default **.emscripten** file created by *emcc* is quite different than that created by :ref:`emsdk `. This is because *emsdk* manages multiple target environments, and where possible hard codes the locations of those tools when a new environment is activated. The default file, by contrast, is managed by the user — and is designed to make that task as easy as possible. 54 | 55 | The file simply assigns paths to a number of *variables* representing the main tools used by Emscripten. For example, if the user installed python to the **C:/Python27/** directory, then the file might have the line: :: 56 | 57 | PYTHON = 'C:\\Python38\\python.exe' 58 | 59 | 60 | The default *emcc* configuration file often gets the paths from environment variables if defined. If no variable is defined the system will also attempt to find "system executables". For example: :: 61 | 62 | PYTHON = os.path.expanduser(os.getenv('PYTHON', 'C:\\Python38\\python.exe')) 63 | 64 | You can find out the other variable names from the default *.emscripten* file or the :ref:`example here `. 65 | 66 | Editing the compiler configuration file 67 | ======================================= 68 | 69 | The compiler configuration file can be edited with the text editor of your choice. As stated above, most default settings are likely to be correct. If you're building manually from source, you are most likely to have to update the variable ``LLVM_ROOT`` (for :term:`Fastcomp`). 70 | 71 | 72 | #. Edit the variable ``LLVM_ROOT`` to point to the directory where you :ref:`built Fastcomp `. This path is likely to be something like **/build/Release/bin** or **/build/bin**, where ```` is the path to the directory where you cloned LLVM: 73 | 74 | :: 75 | 76 | LLVM_ROOT = os.path.expanduser(os.getenv('LLVM', '/home/ubuntu/a-path/emscripten-fastcomp/build/bin')) 77 | 78 | .. note:: Use forward slashes! 79 | 80 | .. comment .. The settings are now correct in the configuration file, but the paths and environment variables are not set in the command prompt/terminal. **HamishW** Follow up with Jukka on this. 81 | 82 | After setting those paths, run ``emcc`` again. It should again perform the sanity checks to test the specified paths. There are further validation tests available at :ref:`verifying-the-emscripten-environment`. 83 | -------------------------------------------------------------------------------- /_sources/docs/building_from_source/index.rst.txt: -------------------------------------------------------------------------------- 1 | .. _installing-from-source: 2 | 3 | =============================== 4 | Building Emscripten from Source 5 | =============================== 6 | 7 | Building Emscripten yourself is an alternative to getting binaries using the 8 | emsdk. 9 | 10 | Emscripten itself is written in Python and JavaScript so it does not need to be 11 | compiled. However, after checkout you will need to perform various steps 12 | before it can be used (e.g. ``npm install``). The ``bootstrap`` script in the 13 | top level of the repository takes care of running these steps and ``emcc`` will 14 | error out if it detects that ``bootstrap`` needs to be run. 15 | 16 | Emscripten comes with its own versions some C/C++ system libaries which ``emcc`` 17 | builds automatically as and when needed (in the emsdk builds, these are precompiled). 18 | You can also build them manually with the ``embuilder`` tool - see ``embuilder --help`` 19 | for more information. 20 | 21 | In addition to the main emscripten repository you will also need to checkout 22 | and build LLVM and Binaryen (as detailed below). After compiling these, you 23 | will need to edit your ``.emscripten`` file to point to their corresponding 24 | locations. 25 | 26 | Use the ``main`` branches of each of these repositories, or check the `Packaging 27 | `_ 28 | instructions to identify precise commits used in a specific release. 29 | 30 | 31 | Building LLVM 32 | ------------- 33 | 34 | Build LLVM from the `git repo `_. 35 | Include clang and wasm-ld (using something like ``-DLLVM_ENABLE_PROJECTS='lld;clang'``) and the Wasm backend (which is included by default; just don't disable it), following `that project's instructions `_. 36 | For example, something like this can work: 37 | 38 | :: 39 | 40 | mkdir build 41 | cd build/ 42 | cmake ../llvm -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS='lld;clang' -DLLVM_TARGETS_TO_BUILD="host;WebAssembly" -DLLVM_INCLUDE_EXAMPLES=OFF -DLLVM_INCLUDE_TESTS=OFF # -DLLVM_ENABLE_ASSERTIONS=ON 43 | cmake --build . 44 | 45 | Then set the environment variable ``EM_LLVM_ROOT`` to ``/build/bin`` (no need to install). 46 | 47 | If you need to match the emsdk releases of LLVM, `review the emscripten-release 48 | build and test scripts `_. 49 | Specifically `src/build.py `_. 50 | 51 | Please refer to the upstream docs for more detail. 52 | 53 | Building Binaryen 54 | ----------------- 55 | 56 | See the `Binaryen build instructions `_. 57 | 58 | .. toctree:: 59 | :maxdepth: 1 60 | 61 | toolchain_what_is_needed 62 | configuring_emscripten_settings 63 | verify_emscripten_environment 64 | 65 | -------------------------------------------------------------------------------- /_sources/docs/building_from_source/index.txt: -------------------------------------------------------------------------------- 1 | .. _installing-from-source: 2 | 3 | =============================== 4 | Building Emscripten from Source 5 | =============================== 6 | 7 | Building Emscripten yourself is an alternative to getting binaries using the emsdk. 8 | 9 | Emscripten's core codebase, which is in the main "emscripten" repo, does not need to be compiled (it uses Python for most of the scripting that glues together all the tools). What do need to be compiled are LLVM (which in particular provides clang and wasm-ld) and Binaryen. After compiling them, simply edit the ``.emscripten`` file to point to the right place for each of those tools (if the file doesn't exist yet, run ``emcc`` for the first time). 10 | 11 | Get the ``master`` branches, or check the `Packaging `_ instructions to identify precise commits in existing releases. 12 | 13 | 14 | Building LLVM 15 | ------------- 16 | 17 | For using the LLVM wasm backend (recommended), simply build normal upstream LLVM from the `monorepo `_. 18 | Include clang and wasm-ld (using something like ``-DLLVM_ENABLE_PROJECTS='lld;clang'``) and the wasm backend (which is included by default; just don't disable it), following `that project's instructions `_. 19 | For example, something like this can work: 20 | 21 | :: 22 | 23 | mkdir build 24 | cd build/ 25 | cmake ../llvm -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS='lld;clang' -DLLVM_TARGETS_TO_BUILD="host;WebAssembly" -DLLVM_INCLUDE_EXAMPLES=OFF -DLLVM_INCLUDE_TESTS=OFF 26 | cmake --build . 27 | 28 | Then point LLVM_ROOT in ``.emscripten`` to ``/build/bin`` (no need to install). 29 | 30 | Please refer to the upstream docs for more detail. 31 | 32 | For using the older fastcomp backend, see :ref:`the fastcomp docs `. 33 | 34 | Building Binaryen 35 | ----------------- 36 | 37 | See the `Binaryen build instructions `_. 38 | 39 | .. toctree:: 40 | :maxdepth: 1 41 | 42 | toolchain_what_is_needed 43 | building_fastcomp_manually_from_source 44 | configuring_emscripten_settings 45 | verify_emscripten_environment 46 | 47 | -------------------------------------------------------------------------------- /_sources/docs/building_from_source/toolchain_what_is_needed.rst.txt: -------------------------------------------------------------------------------- 1 | .. _emscripten-toolchain-top: 2 | 3 | ================================= 4 | Emscripten Toolchain Requirements 5 | ================================= 6 | 7 | The instructions below list the main tools and dependencies in an Emscripten environment, along with instructions on how to test which dependencies are installed. 8 | 9 | .. tip:: The :ref:`SDK ` provides the **easiest** and **most reliable** method for getting, using, updating and managing Emscripten environments. If you're using the SDK you won't *need* these instructions — they are provided for information only. 10 | 11 | The instructions below are useful if you're :ref:`manually ` building from source. 12 | 13 | .. _toolchain-what-you-need: 14 | 15 | What you'll need 16 | ================ 17 | 18 | .. _central-list-of-emscripten-tools-and-dependencies: 19 | 20 | Emscripten tools and dependencies 21 | --------------------------------- 22 | 23 | In general a complete Emscripten environment requires the following tools. First test to see if they are already installed using the :ref:`instructions below `. 24 | 25 | - :term:`Node.js` (0.8 or above; 0.10.17 or above to run websocket-using servers in node) 26 | - :term:`Python` (3.6 or above) 27 | - :term:`Java` (1.6.0_31 or later). Java is optional. It can be used to run the java version of term:`Closure Compiler`. 28 | - :term:`Git` client. Git is required if building tools from source. 29 | - :term:`LLVM` (LLVM, including clang and wasm-ld) 30 | - :term:`Binaryen` (Binaryen, including wasm-opt, wasm-emscripten-finalize, etc.) 31 | - The `Emscripten code `_, from GitHub 32 | 33 | .. note: 64-bit versions of all needed dependencies are preferred, and may be required if you are building large projects. 34 | 35 | .. note:: The `d8 shell `_ is also required if you want to run **100%** of the tests in the test suite (in particular, tests for extremely new features that are only present in d8 so far). Most developers will not need this, and should instead use *node.js*. 36 | 37 | .. _compiler-toolchain: 38 | 39 | Compiler toolchain 40 | ------------------ 41 | 42 | When building Emscripten from source code, whether "manually" or using the SDK, you will need a *compiler toolchain*: 43 | 44 | - Windows: Install `Visual Studio 2017 `_ and `cmake `_. 45 | 46 | .. note:: 47 | 48 | - SDK users can also install and activate the MinGW compiler toolchain in order to build their own projects: 49 | 50 | :: 51 | 52 | emsdk install mingw-4.6.2-32bit 53 | emsdk activate mingw-4.6.2-32bit 54 | 55 | 56 | - Linux: Install *gcc* and *cmake*: 57 | 58 | :: 59 | 60 | #Install gcc 61 | sudo apt-get install build-essential 62 | # Install cmake 63 | sudo apt-get install cmake 64 | 65 | - macOS: Install the *Xcode Command Line Tools*: 66 | 67 | - Install Xcode from the `macOS App Store `_. 68 | - In **Xcode | Preferences | Downloads**, install *Command Line Tools*. 69 | 70 | .. note:: Building LLVM and Clang from source can require a lot of memory and hard drive space. The specific requirements change from LLVM version to another, but you probably need at least 2GB of RAM, preferably 4GB or more. Debug builds or builds with assertions can require even more memory. 71 | 72 | .. _toolchain-test-which-dependencies-are-installed: 73 | 74 | Test which tools are installed 75 | ============================== 76 | 77 | Some of the tools are pre-installed on the various platforms (for example, Python is always available on Linux builds). 78 | 79 | You can check which tools are already present using the following commands: 80 | 81 | :: 82 | 83 | # Check for Python 84 | python --version 85 | 86 | # Check for node.js on Linux 87 | nodejs --version 88 | 89 | # Check for node.js on Windows 90 | node --version 91 | 92 | # Check for node.js on macOS 93 | node -v 94 | 95 | # Check for git 96 | git --version 97 | 98 | # Check for Java 99 | java -version 100 | 101 | # Check for gcc / g++ 102 | gcc --version 103 | g++ 104 | 105 | # Check for cmake 106 | cmake 107 | 108 | -------------------------------------------------------------------------------- /_sources/docs/building_from_source/toolchain_what_is_needed.txt: -------------------------------------------------------------------------------- 1 | .. _emscripten-toolchain-top: 2 | 3 | ================================= 4 | Emscripten Toolchain Requirements 5 | ================================= 6 | 7 | The instructions below list the main tools and dependencies in an Emscripten environment, along with instructions on how to test which dependencies are installed. 8 | 9 | .. tip:: The :ref:`SDK ` provides the **easiest** and **most reliable** method for getting, using, updating and managing Emscripten environments. If you're using the SDK you won't *need* these instructions — they are provided for information only. 10 | 11 | The instructions below are useful if you're :ref:`manually ` building from source. 12 | 13 | .. _toolchain-what-you-need: 14 | 15 | What you'll need 16 | ================ 17 | 18 | .. _central-list-of-emscripten-tools-and-dependencies: 19 | 20 | Emscripten tools and dependencies 21 | --------------------------------- 22 | 23 | In general a complete Emscripten environment requires the following tools. First test to see if they are already installed using the :ref:`instructions below `. 24 | 25 | - :term:`Node.js` (0.8 or above; 0.10.17 or above to run websocket-using servers in node): 26 | - :term:`Python` 2.7.12 or above, or Python 3.5 or above (Python 2.7.0 or newer may also work, but is known to have SSL related issues, https://github.com/emscripten-core/emscripten/issues/6275) 27 | - :term:`Java` (1.6.0_31 or later). Java is optional. It is required to use the :term:`Closure Compiler` (in order to minify your code). 28 | - :term:`Git` client. Git is required if building tools from source. 29 | - :term:`LLVM` (LLVM, including clang and wasm-ld) 30 | - :term:`Binaryen` (Binaryen, including wasm-opt, wasm-emscripten-finalize, etc.) 31 | - The `Emscripten code `_, from GitHub 32 | 33 | .. note: 64-bit versions of all needed dependencies are preferred, and may be required if you are building large projects. 34 | 35 | .. note:: The `Spidermonkey shell `_ is also required if you want to run **100%** of the tests in the test suite. Most developers will not need this, and should instead use *node.js*. 36 | 37 | .. _compiler-toolchain: 38 | 39 | Compiler toolchain 40 | ------------------ 41 | 42 | When building Emscripten from source code, whether "manually" or using the SDK, you will need a *compiler toolchain*: 43 | 44 | - Windows: Install `Visual Studio 2017 `_ and `cmake `_. 45 | 46 | .. note:: 47 | 48 | - SDK users can also install and activate the MinGW compiler toolchain in order to build their own projects: 49 | 50 | :: 51 | 52 | emsdk install mingw-4.6.2-32bit 53 | emsdk activate mingw-4.6.2-32bit 54 | 55 | 56 | - Linux: Install *gcc* and *cmake*: 57 | 58 | :: 59 | 60 | #Install gcc 61 | sudo apt-get install build-essential 62 | # Install cmake 63 | sudo apt-get install cmake 64 | 65 | - macOS: Install the *Xcode Command Line Tools*: 66 | 67 | - Install Xcode from the `macOS App Store `_. 68 | - In **Xcode | Preferences | Downloads**, install *Command Line Tools*. 69 | 70 | .. note:: Building LLVM and Clang from source can require a lot of memory and hard drive space. The specific requirements change from LLVM version to another, but you probably need at least 2GB of RAM, preferably 4GB or more. Debug builds or builds with assertions can require even more memory. 71 | 72 | .. _toolchain-test-which-dependencies-are-installed: 73 | 74 | Test which tools are installed 75 | ============================== 76 | 77 | Some of the tools are pre-installed on the various platforms (for example, Python is always available on Linux builds). 78 | 79 | You can check which tools are already present using the following commands: 80 | 81 | :: 82 | 83 | # Check for Python 84 | python --version 85 | 86 | # Check for node.js on Linux 87 | nodejs --version 88 | 89 | # Check for node.js on Windows 90 | node --version 91 | 92 | # Check for node.js on macOS 93 | node -v 94 | 95 | # Check for git 96 | git --version 97 | 98 | # Check for Java 99 | java -version 100 | 101 | # Check for gcc / g++ 102 | gcc --version 103 | g++ 104 | 105 | # Check for cmake 106 | cmake 107 | 108 | -------------------------------------------------------------------------------- /_sources/docs/building_from_source/verify_emscripten_environment.rst.txt: -------------------------------------------------------------------------------- 1 | .. _verifying-the-emscripten-environment: 2 | 3 | ================================================ 4 | Verifying the Emscripten Development Environment 5 | ================================================ 6 | 7 | After you've :ref:`installed the SDK ` or :ref:`built an Emscripten development environment from sources `, the compiler should just work! This section shows how to verify that the environment has been set up correctly, and how to troubleshoot installation problems when they do occur. 8 | 9 | 10 | Testing the environment 11 | ======================= 12 | 13 | Sanity tests 14 | ------------ 15 | 16 | The first step in verifying the environment is to run Emscripten with ``--check``. The option prints out information about the toolchain and runs some basic sanity tests to check that the required tools are available. 17 | 18 | Open a terminal in the directory in which you installed Emscripten (on Windows open the :ref:`Emscripten Command Prompt `). Then call the :ref:`Emscripten Compiler Frontend (emcc) ` as shown:: 19 | 20 | ./emcc --check 21 | 22 | .. note:: On Windows, invoke the tool with **emcc** instead of **./emcc**. 23 | 24 | For example, the following output reports that the correct version of clang 25 | could not be found: 26 | 27 | .. code-block:: none 28 | :emphasize-lines: 3 29 | 30 | emcc (Emscripten GCC-like replacement + linker emulating GNU ld) 1.21.0 31 | shared:INFO: (Emscripten: Running sanity checks) 32 | emcc: warning: LLVM version for clang executable "/usr/bin/clang" appears incorrect (seeing "16.0", expected "18") [-Wversion-check] 33 | 34 | At this point you need to :ref:`Install and activate ` any missing components. When everything is set up properly, ``emcc ---check`` should give no warnings, and if you just enter ``emcc`` (without any input files), it will give an error :: 35 | 36 | emcc: error: no input files 37 | 38 | 39 | Build a basic example 40 | --------------------- 41 | 42 | The next test is to actually build some code! On the command prompt navigate to the Emscripten directory for the current SDK and try to build the **hello_world.cpp** test code: 43 | 44 | :: 45 | 46 | cd emscripten/ 47 | ./emcc test/hello_world.cpp 48 | 49 | This command should complete without warnings and you should find the newly-compiled JavaScript file (**a.out.js**) in the current directory. 50 | 51 | If compiling succeeds, you're ready for the :ref:`Tutorial`. If not, check out the troubleshooting instructions below. 52 | 53 | 54 | Run the full test suite 55 | ------------------------ 56 | 57 | Emscripten has a comprehensive test suite which may be used to further validate all or parts of the toolchain. For more information, see :ref:`emscripten-test-suite`. 58 | 59 | 60 | .. _troubleshooting-emscripten-environment: 61 | 62 | Troubleshooting 63 | =============== 64 | 65 | First run ``./emcc --check`` and examine the output to find missing components. You can also try ``./emcc --clear-cache`` to empty the :ref:`compiler's internal cache ` and reset it to a known good state. 66 | 67 | 68 | .. _fixing-missing-components-emcc: 69 | 70 | Installing missing components 71 | ----------------------------- 72 | 73 | Missing tools can often be added using the :ref:`emsdk`. For example, to fix a warning that Java is missing, locate it in the repository, install it, and then set it as active:: 74 | 75 | #List all the components. Look for the missing component (in this case "java-7.45-64bit") 76 | ./emsdk list 77 | 78 | #Install the missing component 79 | ./emsdk install java-7.45-64bit 80 | 81 | #Set the component as active 82 | ./emsdk activate java-7.45-64bit 83 | 84 | If you're :ref:`building Emscripten manually from source `, see that link for information on how to obtain all dependencies. 85 | 86 | 87 | Other common problems 88 | --------------------- 89 | 90 | Other common problems to check for are: 91 | 92 | - Errors in the paths in :ref:`.emscripten `. These are less likely if you update the file using :ref:`emsdk `. 93 | - Using older versions of Node or JavaScript engines. Use the default versions for the SDK as listed with :ref:`emsdk list `. 94 | - Using older versions of LLVM. The correct versions come with the SDK, but if you're building the environment from source you should make sure to use the proper version of LLVM (which you can find using the `emscripten-releases DEPS file and history `_; other versions might work, especially close-by ones, but are not tested by us and so not guaranteed to work). 95 | 96 | If none of the above is helpful, then please :ref:`contact us ` for help. 97 | -------------------------------------------------------------------------------- /_sources/docs/building_from_source/verify_emscripten_environment.txt: -------------------------------------------------------------------------------- 1 | .. _verifying-the-emscripten-environment: 2 | 3 | ================================================ 4 | Verifying the Emscripten Development Environment 5 | ================================================ 6 | 7 | After you've :ref:`installed the SDK ` or :ref:`built an Emscripten development environment from sources `, the compiler should just work! This section shows how to verify that the environment has been set up correctly, and how to troubleshoot installation problems when they do occur. 8 | 9 | 10 | Testing the environment 11 | ======================= 12 | 13 | Sanity tests 14 | ------------ 15 | 16 | The first step in verifying the environment is to run Emscripten with the version command (``-v``). The command prints out information about the toolchain and runs some basic sanity tests to check that the required tools are available. 17 | 18 | Open a terminal in the directory in which you installed Emscripten (on Windows open the :ref:`Emscripten Command Prompt `). Then call the :ref:`Emscripten Compiler Frontend (emcc) ` as shown:: 19 | 20 | ./emcc -v 21 | 22 | .. note:: On Windows, invoke the tool with **emcc** instead of **./emcc**. 23 | 24 | For example, the following output reports an installation where Java is missing:: 25 | :emphasize-lines: 6 26 | 27 | emcc (Emscripten GCC-like replacement + linker emulating GNU ld ) 1.21.0 28 | clang version 3.3 29 | Target: x86_64-pc-win32 30 | Thread model: posix 31 | INFO root: (Emscripten: Running sanity checks) 32 | WARNING root: java does not seem to exist, required for closure compiler. -O2 and above will fail. You need to define JAVA in .emscripten 33 | 34 | At this point you need to :ref:`Install and activate ` any missing components. When everything is set up properly, ``emcc -v`` should give no warnings, and if you just enter ``emcc`` (without any input files), it will give an error :: 35 | 36 | emcc: error: no input files 37 | 38 | 39 | Build a basic example 40 | --------------------- 41 | 42 | The next test is to actually build some code! On the command prompt navigate to the Emscripten directory for the current SDK and try to build the **hello_world.cpp** test code: 43 | 44 | :: 45 | 46 | cd emscripten/ 47 | ./emcc tests/hello_world.cpp 48 | 49 | This command should complete without warnings and you should find the newly-compiled JavaScript file (**a.out.js**) in the current directory. 50 | 51 | If compiling succeeds, you're ready for the :ref:`Tutorial`. If not, check out the troubleshooting instructions below. 52 | 53 | 54 | Run the full test suite 55 | ------------------------ 56 | 57 | Emscripten has a comprehensive test suite which may be used to further validate all or parts of the toolchain. For more information, see :ref:`emscripten-test-suite`. 58 | 59 | 60 | .. _troubleshooting-emscripten-environment: 61 | 62 | Troubleshooting 63 | =============== 64 | 65 | First run ``./emcc -v`` and examine the output to find missing components. You can also try ``./emcc --clear-cache`` to empty the :ref:`compiler's internal cache ` and reset it to a known good state. 66 | 67 | 68 | .. _fixing-missing-components-emcc: 69 | 70 | Installing missing components 71 | ----------------------------- 72 | 73 | Missing tools can often be added using the :ref:`emsdk`. For example, to fix a warning that Java is missing, locate it in the repository, install it, and then set it as active:: 74 | 75 | #List all the components. Look for the missing component (in this case "java-7.45-64bit") 76 | ./emsdk list 77 | 78 | #Install the missing component 79 | ./emsdk install java-7.45-64bit 80 | 81 | #Set the component as active 82 | ./emsdk activate java-7.45-64bit 83 | 84 | If you're :ref:`building Emscripten manually from source `, see that link for information on how to obtain all dependencies. 85 | 86 | 87 | Other common problems 88 | --------------------- 89 | 90 | Other common problems to check for are: 91 | 92 | - Errors in the paths in :ref:`.emscripten `. These are less likely if you update the file using :ref:`emsdk `. 93 | - Using older versions of Node or JavaScript engines. Use the default versions for the SDK as listed with :ref:`emsdk list `. 94 | - Using older versions of LLVM. The correct versions come with the SDK, but if you're building the environment from source you should make sure to use the proper version of LLVM (which you can find using the `emscripten-releases DEPS file and history `_; other versions might work, especially close-by ones, but are not tested by us and so not guaranteed to work). 95 | 96 | If none of the above is helpful, then please :ref:`contact us ` for help. 97 | -------------------------------------------------------------------------------- /_sources/docs/compiling/Contrib-Ports.rst.txt: -------------------------------------------------------------------------------- 1 | .. _Contrib-Ports: 2 | 3 | ======================== 4 | Emscripten Contrib Ports 5 | ======================== 6 | 7 | Contrib ports are contributed by the wider community and 8 | supported on a "best effort" basis. Since they are not run as part 9 | of emscripten CI they are not always guaranteed to build or function. 10 | 11 | The following is the complete list of the contrib ports that are 12 | available in emscripten. In order to use a contrib port you use the 13 | ``--use-port=`` option (:ref:`emcc `). 14 | 15 | .. _contrib.glfw3: 16 | 17 | contrib.glfw3 18 | ============= 19 | 20 | This project is an Emscripten port of GLFW written in C++ for the 21 | web/webassembly platform. 22 | 23 | .. note:: 24 | Emscripten includes support for both GLFW 2 and 3 written in Javascript. 25 | These can be activated with the :ref:`settings ` ``-sUSE_GLFW=2`` 26 | and ``-sUSE_GLFW=3``. This non-official contribution, written in C++, 27 | provides a more extensive and up-to-date implementation of the GLFW 3 API 28 | than the built-in port. It is enabled with the option 29 | ``--use-port=contrib.glfw3``. 30 | 31 | `Project information `__ 32 | 33 | License: Apache 2.0 license 34 | 35 | .. _contrib.lua: 36 | 37 | contrib.lua 38 | =========== 39 | 40 | Lua is a powerful, efficient, lightweight, embeddable scripting language. 41 | 42 | Example usage: 43 | 44 | .. code-block:: text 45 | 46 | // main.c 47 | #include 48 | #include 49 | #include 50 | #include 51 | 52 | int main() { 53 | lua_State *L = luaL_newstate(); 54 | luaL_openlibs(L); 55 | if (luaL_dostring(L, "print('hello world')") != LUA_OK) { 56 | printf("Error running Lua code %s\n", lua_tostring(L, -1)); 57 | lua_pop(L, 1); 58 | } 59 | lua_close(L); 60 | return 0; 61 | } 62 | 63 | // compile with 64 | emcc --use-port=contrib.lua main.c -o /tmp/index.html 65 | 66 | 67 | `Project information `__ 68 | 69 | License: MIT License -------------------------------------------------------------------------------- /_sources/docs/compiling/GitLab.rst.txt: -------------------------------------------------------------------------------- 1 | .. _GitLab: 2 | 3 | ================================ 4 | Building and Deploying on GitLab 5 | ================================ 6 | 7 | `GitLab CI/CD `_ is a popular continuous integration service which offers free plans to everyone. Thanks to an `Alpine Linux package by Jakub Jirutka `_ installing emscripten in GitLab CI/CD is literally a one line task. 8 | 9 | A sample .gitlab-ci.yml 10 | ======================= 11 | 12 | .. code-block:: yaml 13 | 14 | image: alpine:3.9 15 | 16 | before_script: 17 | - apk add emscripten make --repository=http://dl-cdn.alpinelinux.org/alpine/edge/testing 18 | 19 | pages: 20 | script: 21 | - make 22 | artifacts: 23 | paths: 24 | - public 25 | only: 26 | - main 27 | 28 | Let's break it down: 29 | 30 | .. code-block:: yaml 31 | 32 | before_script: 33 | - apk add emscripten make --repository=http://dl-cdn.alpinelinux.org/alpine/edge/testing 34 | 35 | In the before_script stage we download the package from the Alpine Linux testing repository. 36 | 37 | This step also contains the command to add an additional build tool *make*. 38 | 39 | .. code-block:: yaml 40 | 41 | script: 42 | - make 43 | 44 | In the script stage we can now run the commands we want. In this sample we are using *make*, but you can call *emcc* directly if you prefer. 45 | 46 | For an example of this setup in practice, see `the Example Emscripten site using GitLab Pages `_. 47 | -------------------------------------------------------------------------------- /_sources/docs/compiling/GitLab.txt: -------------------------------------------------------------------------------- 1 | .. _GitLab: 2 | 3 | ================================ 4 | Building and Deploying on GitLab 5 | ================================ 6 | 7 | `GitLab CI/CD `_ is a popular continuous integration service which offers free plans to everyone. Thanks to an `Alpine Linux package by Jakub Jirutka `_ installing emscripten in GitLab CI/CD is literally a one line task. 8 | 9 | A sample .gitlab-ci.yml 10 | ======================= 11 | 12 | .. code-block:: yaml 13 | 14 | image: alpine:3.9 15 | 16 | before_script: 17 | - apk add emscripten make --repository=http://dl-cdn.alpinelinux.org/alpine/edge/testing 18 | 19 | pages: 20 | script: 21 | - make 22 | artifacts: 23 | paths: 24 | - public 25 | only: 26 | - master 27 | 28 | Let's break it down: 29 | 30 | .. code-block:: yaml 31 | 32 | before_script: 33 | - apk add emscripten make --repository=http://dl-cdn.alpinelinux.org/alpine/edge/testing 34 | 35 | In the before_script stage we download the package from the Alpine Linux testing repository. 36 | 37 | This step also contains the command to add an additional build tool *make*. 38 | 39 | .. code-block:: yaml 40 | 41 | script: 42 | - make 43 | 44 | In the script stage we can now run the commands we want. In this sample we are using *make*, but you can call *emcc* directly if you prefer. 45 | 46 | For an example of this setup in practice, see `the Example Emscripten site using GitLab Pages `_. 47 | -------------------------------------------------------------------------------- /_sources/docs/compiling/Travis.rst.txt: -------------------------------------------------------------------------------- 1 | .. _Travis: 2 | 3 | ============================== 4 | Building projects on Travis CI 5 | ============================== 6 | 7 | `Travis CI `_ is a popular continuous integration service which offers free plans for open source projects. Thanks to a `Docker image by trzeci `_ installing emscripten in Travis CI is essentially a one line task. 8 | 9 | A sample .travis.yml 10 | ==================== 11 | 12 | .. code-block:: yaml 13 | 14 | notifications: 15 | email: false 16 | 17 | language: node_js 18 | node_js: 19 | - node 20 | 21 | sudo: required 22 | 23 | services: 24 | - docker 25 | 26 | before_install: 27 | - docker run -dit --name emscripten -v $(pwd):/src trzeci/emscripten:sdk-incoming-64bit bash 28 | 29 | script: 30 | - docker exec -it emscripten make helloworld.js 31 | - make test 32 | 33 | Let's break it down: 34 | 35 | .. code-block:: yaml 36 | 37 | notifications: 38 | email: false 39 | 40 | language: node_js 41 | node_js: 42 | - node 43 | 44 | sudo: required 45 | 46 | services: 47 | - docker 48 | 49 | These lines set up the basic settings for the Travis container. Most people do not want email notifications, but feel free to leave out those lines if you do. 50 | 51 | ``language: node_js`` and ``node_js: - node`` tell Travis we are a Node.js project, and that we want the latest stable Node release. 52 | 53 | ``sudo: required`` and ``services: - docker`` are required to enable Docker in the Travis container. 54 | 55 | .. code-block:: yaml 56 | 57 | before_install: 58 | - docker run -dit --name emscripten -v $(pwd):/src trzeci/emscripten:sdk-incoming-64bit bash 59 | 60 | In the before_install stage we download the Docker image, create a container with that image, and then give it the name ``emscripten``. The ``-dit`` options tell Docker that we want the container to run *bash* in the background. 61 | 62 | This Docker image contains everything emscripten needs to run, as well as several additional build tools such as *make* and *cmake*. If you do not need them you can use the `emscripten-slim image `_ instead, which excludes them and will be downloaded and installed slightly quicker. The emscripten versions available are listed at `the Docker Hub `_. 63 | 64 | .. code-block:: yaml 65 | 66 | script: 67 | - docker exec -it emscripten make helloworld.js 68 | - make test 69 | 70 | In the script stage we can now run the commands we want, inside the Docker container we created earlier. In this sample we are using *make*, but you can call *emcc* directly if you prefer. 71 | 72 | The Docker container is set up to use the same directories as Travis, so the second line uses the same *Makefile*, and can also depend on the output of the Docker command. If your test suite needs a later version of Node than what is installed by *emsdk* (Node v4), you will need to run the tests outside of Docker as a normal Travis command. 73 | 74 | For an example of this setup in practice, see `the Travis page for emglken `_, which is also set up to use `Greenkeeper `_ for automatic testing of dependency updates. 75 | -------------------------------------------------------------------------------- /_sources/docs/compiling/Travis.txt: -------------------------------------------------------------------------------- 1 | .. _Travis: 2 | 3 | ============================== 4 | Building projects on Travis CI 5 | ============================== 6 | 7 | `Travis CI `_ is a popular continuous integration service which offers free plans for open source projects. Thanks to a `Docker image by trzeci `_ installing emscripten in Travis CI is essentially a one line task. 8 | 9 | A sample .travis.yml 10 | ==================== 11 | 12 | .. code-block:: yaml 13 | 14 | notifications: 15 | email: false 16 | 17 | language: node_js 18 | node_js: 19 | - node 20 | 21 | sudo: required 22 | 23 | services: 24 | - docker 25 | 26 | before_install: 27 | - docker run -dit --name emscripten -v $(pwd):/src trzeci/emscripten:sdk-incoming-64bit bash 28 | 29 | script: 30 | - docker exec -it emscripten make helloworld.js 31 | - make test 32 | 33 | Let's break it down: 34 | 35 | .. code-block:: yaml 36 | 37 | notifications: 38 | email: false 39 | 40 | language: node_js 41 | node_js: 42 | - node 43 | 44 | sudo: required 45 | 46 | services: 47 | - docker 48 | 49 | These lines set up the basic settings for the Travis container. Most people do not want email notifications, but feel free to leave out those lines if you do. 50 | 51 | ``language: node_js`` and ``node_js: - node`` tell Travis we are a Node.js project, and that we want the latest stable Node release. 52 | 53 | ``sudo: required`` and ``services: - docker`` are required to enable Docker in the Travis container. 54 | 55 | .. code-block:: yaml 56 | 57 | before_install: 58 | - docker run -dit --name emscripten -v $(pwd):/src trzeci/emscripten:sdk-incoming-64bit bash 59 | 60 | In the before_install stage we download the Docker image, create a container with that image, and then give it the name ``emscripten``. The ``-dit`` options tell Docker that we want the container to run *bash* in the background. 61 | 62 | This Docker image contains everything emscripten needs to run, as well as several additional build tools such as *make* and *cmake*. If you do not need them you can use the `emscripten-slim image `_ instead, which excludes them and will be downloaded and installed slightly quicker. The emscripten versions available are listed at `the Docker Hub `_. 63 | 64 | .. code-block:: yaml 65 | 66 | script: 67 | - docker exec -it emscripten make helloworld.js 68 | - make test 69 | 70 | In the script stage we can now run the commands we want, inside the Docker container we created earlier. In this sample we are using *make*, but you can call *emcc* directly if you prefer. 71 | 72 | The Docker container is set up to use the same directories as Travis, so the second line uses the same *Makefile*, and can also depend on the output of the Docker command. If your test suite needs a later version of Node than what is installed by *emsdk* (Node v4), you will need to run the tests outside of Docker as a normal Travis command. 73 | 74 | For an example of this setup in practice, see `the Travis page for emglken `_, which is also set up to use `Greenkeeper `_ for automatic testing of dependency updates. 75 | -------------------------------------------------------------------------------- /_sources/docs/compiling/index.rst.txt: -------------------------------------------------------------------------------- 1 | .. _compiling-and-running-projects-index: 2 | 3 | ============================== 4 | Compiling and Running Projects 5 | ============================== 6 | 7 | This section contains topics about building projects and running the output. 8 | 9 | - :ref:`Building-Projects` shows how to use :ref:`emccdoc` as a drop-in replacement for *gcc* in your existing project. 10 | - :ref:`WebAssembly` explains how Emscripten can be used to build WebAssembly files 11 | - :ref:`Running-html-files-with-emrun` explains how to use *emrun* to run generated HTML pages in a locally launched web server. 12 | - :ref:`Modularized-Output` covers the various options for generating modularized JS code. 13 | - :ref:`Deploying-Pages` covers topics related to hosting Emscripten compiled web pages on a CDN. 14 | - :ref:`GitLab` explains how to build and test projects on GitLab. 15 | - :ref:`Contrib-Ports` contains information about contrib ports. 16 | 17 | 18 | .. toctree:: 19 | :hidden: 20 | 21 | Building-Projects 22 | WebAssembly 23 | Modularized-Output 24 | Dynamic-Linking 25 | Running-html-files-with-emrun 26 | Deploying-Pages 27 | GitLab 28 | Contrib-Ports 29 | -------------------------------------------------------------------------------- /_sources/docs/compiling/index.txt: -------------------------------------------------------------------------------- 1 | .. _compiling-and-running-projects-index: 2 | 3 | ============================== 4 | Compiling and Running Projects 5 | ============================== 6 | 7 | This section contains topics about building projects and running the output. 8 | 9 | - :ref:`Building-Projects` shows how to use :ref:`emccdoc` as a drop-in replacement for *gcc* in your existing project. 10 | - :ref:`WebAssembly` explains how Emscripten can be used to build WebAssembly files 11 | - :ref:`Running-html-files-with-emrun` explains how to use *emrun* to run generated HTML pages in a locally launched web server. 12 | - :ref:`Travis` explains how to build and test projects on Travis CI. 13 | - :ref:`Deploying-Pages` covers topics related to hosting Emscripten compiled web pages on a CDN. 14 | - :ref:`GitLab` explains how to build and test projects on GitLab. 15 | 16 | 17 | .. toctree:: 18 | :hidden: 19 | 20 | Building-Projects 21 | WebAssembly 22 | Running-html-files-with-emrun 23 | Travis 24 | Deploying-Pages 25 | GitLab 26 | -------------------------------------------------------------------------------- /_sources/docs/contributing/AUTHORS.rst.txt: -------------------------------------------------------------------------------- 1 | .. _emscripten-authors: 2 | 3 | ======= 4 | AUTHORS 5 | ======= 6 | 7 | The `AUTHORS `_ file lists everyone who has contributed to Emscripten. 8 | It is optional for a contributor to add themselves to the `AUTHORS `_ file before :doc:`contributing `. 9 | 10 | The contributors for releases up to Emscripten |release| inclusive (|today|) are listed below. 11 | 12 | .. include:: ../../../../AUTHORS 13 | :literal: 14 | 15 | 16 | -------------------------------------------------------------------------------- /_sources/docs/contributing/AUTHORS.txt: -------------------------------------------------------------------------------- 1 | .. _emscripten-authors: 2 | 3 | ======= 4 | AUTHORS 5 | ======= 6 | 7 | The `AUTHORS `_ file lists everyone who has contributed to Emscripten. 8 | 9 | .. note :: Authors must add themselves to the `AUTHORS `_ file (**master** branch) before :doc:`contributing `. This act licenses their changes under the project’s :ref:`open source licenses (MIT/LLVM) `. Note that the developer retains copyright. 10 | 11 | The contributors for releases up to Emscripten |release| inclusive (|today|) are listed below. 12 | 13 | .. include:: ../../../../AUTHORS 14 | :literal: 15 | 16 | 17 | -------------------------------------------------------------------------------- /_sources/docs/contributing/contributing.rst.txt: -------------------------------------------------------------------------------- 1 | .. _contributing: 2 | 3 | ============ 4 | Contributing 5 | ============ 6 | 7 | Anyone can contribute to Emscripten — if you find it useful and want to help 8 | improve the project, follow the suggestions below. 9 | 10 | Feel free to file :ref:`bug reports `, :ref:`join the discussion 11 | ` and share your own ideas with the community! 12 | 13 | 14 | Getting started 15 | =============== 16 | 17 | A good starting point is to work on the `open issues on GitHub 18 | `_. Many issues 19 | can be resolved without an in-depth knowledge of compiler internals, and this is 20 | a great way to learn more about the project. 21 | 22 | .. tip:: We really appreciate your help. Every existing issue closed means more 23 | time for the core contributors to work on new features, optimizations and 24 | other enhancements. 25 | 26 | In addition to improving the toolchain, you can also :ref:`review and update 27 | this documentation `. 28 | 29 | 30 | Next steps 31 | ========== 32 | 33 | As a new contributor you should read the :ref:`Developer's-Guide`. You may also 34 | need to :ref:`install Emscripten from source ` and 35 | become familiar with :ref:`Debugging` and :ref:`Building-Projects`. 36 | 37 | Please :ref:`get in touch with the community ` to share your ideas and 38 | work out where you can make the most difference. 39 | -------------------------------------------------------------------------------- /_sources/docs/contributing/contributing.txt: -------------------------------------------------------------------------------- 1 | .. _contributing: 2 | 3 | ============ 4 | Contributing 5 | ============ 6 | 7 | Anyone can contribute to Emscripten — if you find it useful and want to help improve the project, follow the suggestions below. 8 | 9 | Feel free to file :ref:`bug reports `, :ref:`join the discussion ` and share your own ideas with the community! 10 | 11 | 12 | Getting started 13 | =============== 14 | 15 | A good starting point is to work on the `open issues on GitHub `_. Many issues can be resolved without an in-depth knowledge of compiler internals, and this is a great way to learn more about the project. 16 | 17 | .. tip:: We really appreciate your help. Every existing issue closed means more time for the core contributors to work on new features, optimizations and other enhancements. 18 | 19 | In addition to improving the toolchain, you can also :ref:`review and update this documentation `. 20 | 21 | 22 | Next steps 23 | ========== 24 | 25 | As a new contributor you should read the :ref:`Developer's-Guide`. You may also need to :ref:`install Emscripten from source ` and become familiar with :ref:`Debugging` and :ref:`Building-Projects`. 26 | 27 | Please :ref:`get in touch with the community ` to share your ideas and work out where you can make the most difference. 28 | 29 | 30 | 31 | -------------------------------------------------------------------------------- /_sources/docs/contributing/developers_guide.txt: -------------------------------------------------------------------------------- 1 | .. _Developer's-Guide: 2 | 3 | ================= 4 | Developer's Guide 5 | ================= 6 | 7 | This article provides information that is relevant to people who want to 8 | contribute to Emscripten. We welcome contributions from anyone that is 9 | interested in helping out! 10 | 11 | .. tip:: The information will be less relevant if you're just using Emscripten, but may still be of interest. 12 | 13 | .. _developers-guide-setting-up: 14 | 15 | Setting up 16 | ========== 17 | 18 | For contributing to core Emscripten code, such as ``emcc.py``, you don't need to 19 | build any binaries as ``emcc.py`` is in Python, and the core JS generation is 20 | in JavaScript. You do still need binaries for LLVM and Binaryen, which you can 21 | get using the emsdk: 22 | 23 | :: 24 | 25 | emsdk install tot-upstream 26 | emsdk activate tot-upstream 27 | 28 | That gets a "tip-of-tree" build of the very latest binaries. You can use those 29 | binaries with a checkout of the core Emscripten repository, simply by calling 30 | ``emcc.py`` from that checkout, and it will use the binaries from the emsdk. 31 | 32 | If you do want to contribute to LLVM or Binaryen, or to test modifications 33 | to them, you can 34 | :ref:`build them from source `. 35 | 36 | Repositories and branches of interest 37 | ===================================== 38 | 39 | The Emscripten main repository is https://github.com/emscripten-core/emscripten. 40 | 41 | Aside from the Emscripten repo, the other codebases of interest are LLVM 42 | and Binaryen, which Emscripten invokes, and 43 | :ref:`have their own repos `. 44 | 45 | .. _developers-guide-submitting-patches: 46 | 47 | Submitting patches 48 | ================== 49 | 50 | Patches should be submitted as *pull requests* to the **master** branch. 51 | 52 | .. note:: Before submitting your first patch, add yourself to the `AUTHORS `_ file. By doing so, you agree to license your code under the project's :ref:`open source licenses (MIT/LLVM) `. 53 | 54 | When submitting patches, please: 55 | 56 | - Make pull requests to **master**. 57 | - Add an automatic test if you add any new functionality or fix a bug. Search 58 | in ``tests/*.py`` for related tests, as often the simplest thing is to add to 59 | an existing one. If you're not sure how to test your code, feel free to ask 60 | for help. 61 | - We normally squash and merge PRs, which means the PR turns into a single 62 | commit on the target branch. Because of that, it's ok to have merge commits 63 | in the PR itself, as they get removed. Please put a good description for 64 | the final commit in the PR description, and we'll use it when squashing. 65 | 66 | Code reviews 67 | ============ 68 | 69 | One of the core developers will review a pull request before merging it. If 70 | several days pass without any comments on your PR, please comment in the PR 71 | which will ping them. (If that happens, sorry! Sometimes things get missed.) 72 | 73 | Compiler overview 74 | ================= 75 | 76 | The :ref:`Emscripten Compiler Frontend (emcc) ` is a python script that manages the entire compilation process: 77 | 78 | - **emcc** calls :term:`Clang` to compile C++ and ``wasm-ld`` to link it. It 79 | builds and integrates with the Emscripten system libraries, both the 80 | compiled ones and the ones implemented in JS. 81 | - **emcc** then calls `emscripten.py `_ 82 | which performs the final transformation to wasm (including invoking 83 | **wasm-emscripten-finalize** from Binaryen) and calls the JS compiler 84 | (see ``src/compiler.js`` and related files) which emits the JS. 85 | - If optimizing wasm, **emcc** will then call **wasm-opt**, run meta-dce, and 86 | other useful things. It will also run JS optimizations on the JS that is 87 | emitted alongside the wasm. 88 | 89 | Emscripten Test Suite 90 | ===================== 91 | 92 | Emscripten has a :ref:`comprehensive test suite `, which 93 | covers virtually all Emscripten functionality. These tests are run on CI 94 | automatically when you create a pull request, and they should all pass. If you 95 | run into trouble with a test failure you can't fix, please let the developers 96 | know. 97 | 98 | See also 99 | ======== 100 | 101 | - :ref:`Debugging` 102 | - :ref:`Building-Projects` 103 | 104 | 105 | -------------------------------------------------------------------------------- /_sources/docs/contributing/index.rst.txt: -------------------------------------------------------------------------------- 1 | .. _contributing-to-emscripten-index: 2 | 3 | ========================== 4 | Contributing to Emscripten 5 | ========================== 6 | 7 | This section contains articles that are relevant to anyone who wants to contribute to Emscripten and help improve the project. 8 | 9 | - :ref:`contributing` provides an introduction to contributing, along with a few ideas for how you can help. 10 | - The :ref:`Developer's-Guide` contains contributor-relevant information, covering compiler operation and submitting patches to the Emscripten repositories. 11 | - :ref:`emscripten-authors` is a partial list of Emscripten contributors, which used to be updated manually. The git log has the full list of all contributors, 12 | and for that reason it is not necessary to add to the AUTHORS file manually any more (but it is optional). 13 | 14 | .. toctree:: 15 | :hidden: 16 | 17 | contributing 18 | developers_guide 19 | AUTHORS 20 | 21 | 22 | 23 | -------------------------------------------------------------------------------- /_sources/docs/contributing/index.txt: -------------------------------------------------------------------------------- 1 | .. _contributing-to-emscripten-index: 2 | 3 | ========================== 4 | Contributing to Emscripten 5 | ========================== 6 | 7 | This section contains articles that are relevant to anyone who wants to contribute to Emscripten and help improve the project. 8 | 9 | - :ref:`contributing` provides an introduction to contributing, along with a few ideas for how you can help. 10 | - The :ref:`Developer's-Guide` contains contributor-relevant information, covering compiler operation and submitting patches to the Emscripten repositories. 11 | - :ref:`emscripten-authors` is a list of all Emscripten contributors. If you contribute you must accept the project’s :ref:`open source licenses (MIT/LLVM) ` and add yourself to the list! 12 | 13 | .. toctree:: 14 | :hidden: 15 | 16 | contributing 17 | developers_guide 18 | AUTHORS 19 | 20 | 21 | 22 | -------------------------------------------------------------------------------- /_sources/docs/getting_started/bug_reports.rst.txt: -------------------------------------------------------------------------------- 1 | .. _bug-reports: 2 | 3 | ============= 4 | Bug Reporting 5 | ============= 6 | 7 | All bugs should be filed in the GitHub `main 8 | `_ Emscripten repository `Issue 9 | Tracker `_. 10 | 11 | Please supply as much relevant information as possible, including: 12 | 13 | - Original source code. 14 | - Generated bitcode (**.bc**, **.o** or **.ll**) 15 | - Environment information — including *emcc* and *clang* versions (as reported by ``emcc -v``). 16 | - Error symptoms. 17 | - Proposed solutions, ideally with a pull request. 18 | 19 | .. Tip:: Compile with ``EMCC_DEBUG=1`` and grab the 20 | **/tmp/emscripten_temp/emcc-\*** files (these include the bitcode and 21 | JavaScript in several stages). Note that the **emscripten_temp** directory 22 | should be emptied manually first, so it only contains new content! 23 | 24 | 25 | LLVM, wasm-ld, clang, Binaryen bugs 26 | =================================== 27 | 28 | If uncertain, bugs can always be posted to the `main repository 29 | `_. But if you are sure a bug is 30 | in an upstream project, you can file it there: 31 | 32 | - `LLVM bug tracker `_ . For most issues use the 33 | "libraries" product and the "Backend: WebAssembly" component. For wasm-ld 34 | issues, use "lld" and "wasm". 35 | - `Binaryen bug tracker `_ 36 | 37 | Pull requests must (of course) go to the proper repository. 38 | 39 | 40 | .. _site-and-documentation-bug-reports: 41 | 42 | Site and documentation bugs 43 | =========================== 44 | 45 | Documentation (site) bugs should be filed in the same `Issue Tracker 46 | `_. 47 | 48 | Include relevant information including: 49 | 50 | - The URL and title of the affected page(s). 51 | - A description of the problem. 52 | - Suggestions for a possible solution. 53 | 54 | .. tip:: The `Page bug `_ link on the bottom-right of every page opens the Issue Tracker pre-seeded with the current page URL and title. 55 | -------------------------------------------------------------------------------- /_sources/docs/getting_started/bug_reports.txt: -------------------------------------------------------------------------------- 1 | .. _bug-reports: 2 | 3 | ============= 4 | Bug Reporting 5 | ============= 6 | 7 | All bugs should be filed in the GitHub `main `_ Emscripten repository `Issue Tracker `_. 8 | 9 | Please supply as much relevant information as possible, including: 10 | 11 | - Original source code. 12 | - Generated bitcode (**.bc**, **.o** or **.ll**) 13 | - Environment information — including *emcc* and *clang* versions (as reported by ``emcc -v``). 14 | - Error symptoms. 15 | - Proposed solutions, ideally with a pull request. 16 | 17 | .. Tip:: Compile with ``EMCC_DEBUG=1`` and grab the **/tmp/emscripten_temp/emcc-\*** files (these include the bitcode and JavaScript in several stages). Note that the **emscripten_temp** directory should be emptied manually first, so it only contains new content! 18 | 19 | 20 | LLVM, wasm-ld, clang, Binaryen bugs 21 | =================================== 22 | 23 | If uncertain, bugs can always be posted to the `main repository `_. But if you are sure a bug is in an upstream project, you can file it there: 24 | 25 | - `LLVM bug tracker `_ . For most issues use the "libraries" product and the "Backend: WebAssembly" component. For wasm-ld issues, use "lld" and "wasm". 26 | - `Binaryen bug tracker `_ 27 | 28 | Pull requests must (of course) go to the proper repository. 29 | 30 | 31 | .. _site-and-documentation-bug-reports: 32 | 33 | Site and documentation bugs 34 | =========================== 35 | 36 | Documentation (site) bugs should be filed in the same `Issue Tracker `_. 37 | 38 | Include relevant information including: 39 | 40 | - The URL and title of the affected page(s). 41 | - A description of the problem. 42 | - Suggestions for a possible solution. 43 | 44 | .. tip:: The `Page bug `_ link on the bottom-right of every page opens the Issue Tracker pre-seeded with the current page URL and title. 45 | -------------------------------------------------------------------------------- /_sources/docs/getting_started/index.rst.txt: -------------------------------------------------------------------------------- 1 | .. _getting-started-index: 2 | 3 | =============== 4 | Getting Started 5 | =============== 6 | 7 | Now you know why Emscripten is :ref:`right for you `, it's 8 | time to *get started*. 9 | 10 | This section provides a walk-through of :ref:`downloading and installing the SDK 11 | ` and the basics of :ref:`using the Emscripten 12 | toolchain `. The general :ref:`FAQ` answers many common questions 13 | about setting up and using Emscripten. 14 | 15 | We also explain where to :ref:`Report Bugs ` in the toolchain and 16 | the site. The :ref:`emscripten-test-suite` is a great resource for finding 17 | examples of how to use Emscripten. 18 | 19 | .. toctree:: 20 | :maxdepth: 1 21 | 22 | downloads 23 | Tutorial 24 | test-suite 25 | bug_reports 26 | FAQ 27 | -------------------------------------------------------------------------------- /_sources/docs/getting_started/index.txt: -------------------------------------------------------------------------------- 1 | .. _getting-started-index: 2 | 3 | =============== 4 | Getting Started 5 | =============== 6 | 7 | Now you know why Emscripten is :ref:`right for you `, it's time to *get started*. 8 | 9 | This section provides a walk-through of :ref:`downloading and installing the SDK ` and the basics of :ref:`using the Emscripten toolchain `. The general :ref:`FAQ` answers many common questions about setting up and using Emscripten. 10 | 11 | We also explain where to :ref:`Report Bugs ` in the toolchain and the site. The :ref:`emscripten-test-suite` is a great resource for finding examples of how to use Emscripten. 12 | 13 | .. toctree:: 14 | :maxdepth: 1 15 | 16 | downloads 17 | Tutorial 18 | test-suite 19 | bug_reports 20 | FAQ 21 | -------------------------------------------------------------------------------- /_sources/docs/index.rst.txt: -------------------------------------------------------------------------------- 1 | :orphan: 2 | 3 | .. _documentation-home: 4 | 5 | ======================== 6 | Emscripten Documentation 7 | ======================== 8 | 9 | 10 | This comprehensive documentation set contains everything you need to know to use Emscripten. 11 | 12 | **Getting started:** 13 | 14 | - :ref:`introducing-emscripten-index` explains what Emscripten does, why it is needed, its limitations and its licensing. It will help you understand whether Emscripten is the right tool for you. 15 | - :ref:`getting-started-index` walks you through downloading, installing and using the Emscripten SDK. 16 | 17 | **Emscripten Fundamentals:** 18 | 19 | - :ref:`integrating-porting-index` illustrates the main differences between the native and Emscripten runtime environments, and explains the changes you need to make to prepare your C/C++ code for the Web. 20 | - :ref:`Optimizing-Code` shows how to optimise your code for size and performance. 21 | - :ref:`Optimizing-WebGL` gives tips for how to maximize WebGL rendering performance for your page. 22 | - :ref:`compiling-and-running-projects-index` demonstrates how to integrate Emscripten into your existing project build system. 23 | 24 | **Contributing:** 25 | 26 | - :ref:`contributing-to-emscripten-index` explains how you can contribute to the project. 27 | - :ref:`installing-from-source` explains how to build Emscripten from sources on GitHub (this is useful for contributors). 28 | - :ref:`about-this-site` describes the documentation tools and writing conventions used to create this site. 29 | 30 | **Reference:** 31 | 32 | - :ref:`api-reference-index` is a reference for the Emscripten toolchain. 33 | - :ref:`settings-reference` is a reference of all the Emscripten compiler settings. 34 | - :ref:`tools-reference` is a reference for the Emscripten integration APIs. 35 | - :ref:`Sanitizers` shows how to debug with sanitizers. 36 | - :ref:`Module-Splitting` is a guide to splitting modules and deferring the 37 | loading of code to improve startup time. 38 | 39 | The full hierarchy of articles, opened to the second level, is shown below. 40 | 41 | .. toctree:: 42 | :maxdepth: 2 43 | 44 | introducing_emscripten/index 45 | getting_started/index 46 | porting/index 47 | optimizing/Optimizing-Code 48 | optimizing/Optimizing-WebGL 49 | optimizing/Profiling-Toolchain 50 | optimizing/Module-Splitting 51 | compiling/index 52 | building_from_source/index 53 | contributing/index 54 | api_reference/index 55 | tools_reference/index 56 | debugging/Sanitizers 57 | site/index 58 | -------------------------------------------------------------------------------- /_sources/docs/index.txt: -------------------------------------------------------------------------------- 1 | :orphan: 2 | 3 | .. _documentation-home: 4 | 5 | ======================== 6 | Emscripten Documentation 7 | ======================== 8 | 9 | 10 | This comprehensive documentation set contains everything you need to know to use Emscripten. 11 | 12 | **Getting started:** 13 | 14 | - :ref:`introducting-emscripten-index` explains what Emscripten does, why it is needed, its limitations and its licensing. It will help you understand whether Emscripten is the right tool for you. 15 | - :ref:`getting-started-index` walks you through downloading, installing and using the Emscripten SDK. 16 | 17 | **Emscripten Fundamentals:** 18 | 19 | - :ref:`integrating-porting-index` illustrates the main differences between the native and Emscripten runtime environments, and explains the changes you need to make to prepare your C/C++ code for the Web. 20 | - :ref:`Optimizing-Code` shows how to optimise your code for size and performance. 21 | - :ref:`Optimizing-WebGL` gives tips for how to maximize WebGL rendering performance for your page. 22 | - :ref:`compiling-and-running-projects-index` demonstrates how to integrate Emscripten into your existing project build system. 23 | 24 | **Contributing:** 25 | 26 | - :ref:`contributing-to-emscripten-index` explains how you can contribute to the project. 27 | - :ref:`installing-from-source` explains how to build Emscripten from sources on GitHub (this is useful for contributors). 28 | - :ref:`about-this-site` describes the documentation tools and writing conventions used to create this site. 29 | 30 | **Reference:** 31 | 32 | - :ref:`api-reference-index` is a reference for the Emscripten toolchain. 33 | - :ref:`tools-reference` is a reference for the Emscripten integration APIs. 34 | - :ref:`CyberDWARF` shows how to use the CyberDWARF debugging system 35 | - :ref:`Sanitizers` shows how to debug with sanitizers 36 | 37 | The full hierarchy of articles, opened to the second level, is shown below. 38 | 39 | .. toctree:: 40 | :maxdepth: 2 41 | 42 | introducing_emscripten/index 43 | getting_started/index 44 | porting/index 45 | optimizing/Optimizing-Code 46 | optimizing/Optimizing-WebGL 47 | optimizing/Profiling-Toolchain 48 | compiling/index 49 | building_from_source/index 50 | contributing/index 51 | api_reference/index 52 | tools_reference/index 53 | debugging/CyberDWARF 54 | debugging/Sanitizers 55 | site/index 56 | -------------------------------------------------------------------------------- /_sources/docs/introducing_emscripten/Talks-and-Publications.rst.txt: -------------------------------------------------------------------------------- 1 | .. _Talks-and-Publications: 2 | 3 | ====================== 4 | Talks and Publications 5 | ====================== 6 | 7 | Presentations 8 | ============= 9 | 10 | - Slides from Mozlando 2015: `Emscripten, WebAssembly, and Binaryen `_ (`kripken `_) 11 | 12 | - Slides from CppCon 2014: 13 | 14 | - `Emscripten & asm.js: C++'s role in the modern web `_ (`kripken `_) 15 | 16 | - `Video of talk `__ 17 | 18 | - `Connecting C++ and JavaScript on the Web with Embind `_ (`chadaustin `_) 19 | 20 | - `Video of talk `__ 21 | 22 | - Slides from GDC 2014: `Getting started with asm.js and Emscripten `_ (`kripken `_, `lwagner `_) 23 | - Slides from Strange Loop 2013: `Native speed on the web, JavaScript and asm.js `_ (`kripken `_) 24 | - Slides from GDC Europe 2013: `C++ on the Web `_ (`floh `_) 25 | - Slides from QCon 2013: `Connecting languages together `_ (`kripken `_) 26 | - Slides from Quo Vadis 2013: `C++ on the Web: Run your big 3D game in the browser! `_ (`floh `_) 27 | - Slides from GDC 2013: 28 | 29 | - `Compiling C/C++ to JavaScript `_ (`kripken `_) 30 | - `Multiplatform C++ on the Web with Emscripten `_ (`chadaustin `_) 31 | 32 | - Slides from mloc.js: `Big Web App? Compile it! `_ (`kripken `_) 33 | - JSConf.eu 2011: `Emscripten `_ (`kripken `_) 34 | 35 | 36 | Papers 37 | ====== 38 | 39 | - `Emscripten: An LLVM-to-JavaScript Compiler `_ (`kripken `_) — A detailed explanation of how Emscripten works, covering the memory model, relooper algorithm, etc. **This is now somewhat outdated**. 40 | 41 | Books 42 | ===== 43 | 44 | - `WebGL Insights `_: Desaulniers, N. (2015). **Chapter 5: Emscripten and WebGL**. In P. Cozzi, WebGL Insights (pp. 71-88). Boca Raton, Florida: A K Peters/CRC Press. Amazon CRC Press. 45 | - `HTML5 Game Development Insights `_ — Book with a chapter on Emscripten (2014). 46 | 47 | -------------------------------------------------------------------------------- /_sources/docs/introducing_emscripten/Talks-and-Publications.txt: -------------------------------------------------------------------------------- 1 | .. _Talks-and-Publications: 2 | 3 | ====================== 4 | Talks and Publications 5 | ====================== 6 | 7 | Presentations 8 | ============= 9 | 10 | - Slides from Mozlando 2015: `Emscripten, WebAssembly, and Binaryen `_ (`kripken `_) 11 | 12 | - Slides from CppCon 2014: 13 | 14 | - `Emscripten & asm.js: C++'s role in the modern web `_ (`kripken `_) 15 | 16 | - `Video of talk `__ 17 | 18 | - `Connecting C++ and JavaScript on the Web with Embind `_ (`chadaustin `_) 19 | 20 | - `Video of talk `__ 21 | 22 | - Slides from GDC 2014: `Getting started with asm.js and Emscripten `_ (`kripken `_, `lwagner `_) 23 | - Slides from Strange Loop 2013: `Native speed on the web, JavaScript and asm.js `_ (`kripken `_) 24 | - Slides from GDC Europe 2013: `C++ on the Web `_ (`floh `_) 25 | - Slides from QCon 2013: `Connecting languages together `_ (`kripken `_) 26 | - Slides from Quo Vadis 2013: `C++ on the Web: Run your big 3D game in the browser! `_ (`floh `_) 27 | - Slides from GDC 2013: 28 | 29 | - `Compiling C/C++ to JavaScript `_ (`kripken `_) 30 | - `Multiplatform C++ on the Web with Emscripten `_ (`chadaustin `_) 31 | 32 | - Slides from mloc.js: `Big Web App? Compile it! `_ (`kripken `_) 33 | - JSConf.eu 2011: `Emscripten `_ (`kripken `_) 34 | 35 | 36 | Papers 37 | ====== 38 | 39 | - `Emscripten: An LLVM-to-JavaScript Compiler `_ (`kripken `_) — A detailed explanation of how Emscripten works, covering the memory model, relooper algorithm, etc. **This is now somewhat outdated**. 40 | 41 | Books 42 | ===== 43 | 44 | - `WebGL Insights `_: Desaulniers, N. (2015). **Chapter 5: Emscripten and WebGL**. In P. Cozzi, WebGL Insights (pp. 71-88). Boca Raton, Florida: A K Peters/CRC Press. Amazon CRC Press. 45 | - `HTML5 Game Development Insights `_ — Book with a chapter on Emscripten (2014). 46 | 47 | -------------------------------------------------------------------------------- /_sources/docs/introducing_emscripten/about_emscripten.rst.txt: -------------------------------------------------------------------------------- 1 | .. _about-emscripten: 2 | 3 | ================ 4 | About Emscripten 5 | ================ 6 | 7 | Emscripten is a complete :ref:`Open Source ` compiler 8 | toolchain to WebAssembly. Using Emscripten you can: 9 | 10 | - Compile C and C++ code, or any other language that uses LLVM, into WebAssembly, 11 | and run it on the Web, Node.js, or other Wasm runtimes. 12 | - Compile the C/C++ **runtimes** of other languages into WebAssembly, and then 13 | run code in those other languages in an *indirect* way (for example, this has 14 | been done for 15 | `Python `_ and 16 | `Lua `_). 17 | 18 | Practically any **portable** C or C++ codebase can be compiled into WebAssembly 19 | using Emscripten, ranging from high-performance games that need to render 20 | graphics, play sounds, and load and process files, through to application 21 | frameworks like Qt. Emscripten has already been used to convert a very long list 22 | of real-world codebases to WebAssembly, including commercial codebases like the 23 | `Unreal Engine 4 `_ 24 | and the `Unity `_ engine. 25 | For examples and demos, see the 26 | `community-maintained list on the wiki `_. 27 | 28 | Emscripten generates small and fast code! Its default output format is 29 | `WebAssembly `_ , a highly optimizable executable 30 | format, that runs almost as fast as native code, while being portable and safe. 31 | Emscripten does a lot of optimization work for you automatically, by careful 32 | integration with LLVM, 33 | `Binaryen `_, 34 | `Closure Compiler `_, and other 35 | tools. 36 | 37 | .. _about-emscripten-toolchain: 38 | 39 | Emscripten Toolchain 40 | ==================== 41 | 42 | A high level view of the Emscripten toolchain is given below. The main tool is 43 | the :ref:`emccdoc`. This is a drop-in replacement for a standard compiler like *gcc* or *clang*. 44 | 45 | *Emcc* uses :term:`Clang` and LLVM to compile to WebAssembly. Emcc also 46 | emits JavaScript that provides API support to the compiled code. That JavaScript 47 | can be executed by :term:`Node.js`, or from within HTML in a browser. 48 | 49 | The :ref:`Emscripten SDK ` is used to install the entire toolchain, including emcc and 50 | LLVM and so forth. The :ref:`emsdk` can be used on Linux, Windows or MacOS. 51 | 52 | .. _about-emscripten-porting-code: 53 | 54 | Porting code to use Emscripten 55 | ============================== 56 | 57 | Emscripten support for **portable** C/C++ code is fairly comprehensive. 58 | Support for the C standard library, C++ standard library, C++ exceptions, etc. 59 | is very good, as is `SDL2 `_ and other APIs. 60 | :ref:`OpenGL-support` 61 | support is excellent for OpenGL ES 2.0-type code, and acceptable for other types. 62 | 63 | There are differences between the native and :ref:`emscripten-runtime-environment`, 64 | which mean some changes usually need to be made to the native code. That said, 65 | many applications will only need to change the way they define their main loop, 66 | and also modify their :ref:`file handling ` to adapt to 67 | the limitations of the browser/JavaScript. 68 | 69 | There are also limitations that can make some code easier to port — read 70 | :ref:`code-portability-guidelines` to determine where you may need to spend more 71 | effort. 72 | -------------------------------------------------------------------------------- /_sources/docs/introducing_emscripten/about_emscripten.txt: -------------------------------------------------------------------------------- 1 | .. _about-emscripten: 2 | 3 | ================ 4 | About Emscripten 5 | ================ 6 | 7 | Emscripten is a complete :ref:`Open Source ` compiler 8 | toolchain to WebAssembly. Using Emscripten you can: 9 | 10 | - Compile C and C++ code, or any other language that uses LLVM, into WebAssembly, 11 | and run it on the Web, Node.js, or wasm runtimes. 12 | - Compile the C/C++ **runtimes** of other languages into WebAssembly, and then 13 | run code in those other languages in an *indirect* way (for example, this has 14 | been done for 15 | `Python `_ and 16 | `Lua `_). 17 | 18 | Practically any **portable** C or C++ codebase can be compiled into WebAssembly 19 | using Emscripten, ranging from high performance games that need to render 20 | graphics, play sounds, and load and process files, through to application 21 | frameworks like Qt. Emscripten has already been used to convert a very long list 22 | of real-world codebases to WebAssembly, including commercial codebases like the 23 | `Unreal Engine 4 `_ 24 | and the `Unity `_ engine. 25 | For examples and demos, see the 26 | `community-maintained list on the wiki `_. 27 | 28 | Emscripten generates small and fast code! Its default output format is 29 | `WebAssembly `_ , a highly optimizable executable 30 | format, that runs almost as fast as native code, while being portable and safe. 31 | Emscripten does a lot of optimization work for you automatically, by careful 32 | integration with LLVM, 33 | `Binaryen `_, 34 | `Closure Compiler `_, and other 35 | tools. 36 | 37 | .. _about-emscripten-toolchain: 38 | 39 | Emscripten Toolchain 40 | ==================== 41 | 42 | A high level view of the Emscripten toolchain is given below. The main tool is 43 | the :ref:`emccdoc`. This is a drop-in replacement for a standard compiler like *gcc* or *clang*. 44 | 45 | *Emcc* uses :term:`Clang` and LLVM to compile to WebAssembly. Emscripten also 46 | emits JavaScript that provides API support to the compiled code. That JavaScript 47 | can be executed by :term:`node.js`, or from within HTML in a browser. 48 | 49 | The :ref:`Emscripten SDK ` is used to install the entire toolchain, including emcc and 50 | LLVM and so forth. The :ref:`emsdk` can be used on Linux, Windows or MacOS. 51 | 52 | .. _about-emscripten-porting-code: 53 | 54 | Porting code to use Emscripten 55 | ============================== 56 | 57 | Emscripten support for **portable** C/C++ code is fairly comprehensive. 58 | Support for the C standard library, C++ standard library, C++ exceptions, etc. 59 | is very good, as is `SDL2 `_ and other APIs. 60 | :ref:`OpenGL-support` 61 | support is excellent for OpenGL ES 2.0-type code, and acceptable for other types. 62 | 63 | There are differences between the native and :ref:`emscripten-runtime-environment`, 64 | which mean some changes usually need to be made to the native code. That said, 65 | many applications will only need to change the way they define their main loop, 66 | and also modify their :ref:`file handling ` to adapt to 67 | the limitations of the browser/JavaScript. 68 | 69 | There are also limitations that can make some code easier to port — read 70 | :ref:`code-portability-guidelines` to determine where you may need to spend more 71 | effort. 72 | -------------------------------------------------------------------------------- /_sources/docs/introducing_emscripten/community.rst.txt: -------------------------------------------------------------------------------- 1 | .. _community: 2 | 3 | ========= 4 | Community 5 | ========= 6 | 7 | Welcome to the Emscripten community! 8 | 9 | 10 | .. _contact: 11 | 12 | Get in touch 13 | ============ 14 | 15 | The best ways contact the community are: 16 | 17 | - The GitHub `Issue Tracker `_ 18 | - Mailing list: `emscripten-discuss `_ 19 | - Real-time chat: `#emscripten on Discord `_ (there was also an IRC channel on Mozilla IRC, but they are shutting those servers down). We are also open to exploring other options than Discord, if you're interested to help out, let us know! 20 | 21 | Feel free to ask questions, share your ideas, or just join the conversation! 22 | 23 | Emscripten also has a presence on social media: 24 | 25 | - `@emscripten on Bluesky `_ 26 | - `@emscripten on Mastodon `_ 27 | - `@emscripten on Twitter `_ 28 | 29 | 30 | Report a bug 31 | ============ 32 | 33 | :ref:`Bug reports ` can be posted in the GitHub `Issue Tracker `_. 34 | 35 | 36 | Contribute 37 | ========== 38 | 39 | Anyone can contribute to Emscripten. We've got some ideas to get you started on our :ref:`contributing` page! 40 | -------------------------------------------------------------------------------- /_sources/docs/introducing_emscripten/community.txt: -------------------------------------------------------------------------------- 1 | .. _community: 2 | 3 | ========= 4 | Community 5 | ========= 6 | 7 | Welcome to the Emscripten community! 8 | 9 | 10 | .. _contact: 11 | 12 | Get in touch 13 | ============ 14 | 15 | The best ways contact the community are: 16 | 17 | - The GitHub `Issue Tracker `_ 18 | - Mailing list: `emscripten-discuss `_ 19 | - Real-time chat: `#emscripten on Discord `_ (there was also an IRC channel on Mozilla IRC, but they are shutting those servers down). We are also open to exploring other options than Discord, if you're interested to help out, let us know! 20 | 21 | Feel free to ask questions, share your ideas, or just join the conversation! 22 | 23 | Emscripten also has a presence on social media: 24 | 25 | - `#emscripten `_ (Emscripten Hashtag on Twitter) 26 | - `@kripken `_ (an Emscripten developer's account on Twitter, mentions Emscripten updates) 27 | 28 | 29 | Report a bug 30 | ============ 31 | 32 | :ref:`Bug reports ` can be posted in the GitHub `Issue Tracker `_. 33 | 34 | 35 | Contribute 36 | ========== 37 | 38 | Anyone can contribute to Emscripten. We've got some ideas to get you started on our :ref:`contributing` page! 39 | -------------------------------------------------------------------------------- /_sources/docs/introducing_emscripten/emscripten_license.rst.txt: -------------------------------------------------------------------------------- 1 | .. _emscripten-license: 2 | 3 | =================== 4 | Open Source License 5 | =================== 6 | 7 | Emscripten is made available under two permissive open source licenses: the *MIT license* and the *University of Illinois/NCSA Open Source License*. 8 | 9 | There is little, if any, practical difference between the licenses. They are both offered because the: 10 | 11 | - *MIT license* is well known and understood. 12 | - *University of Illinois/NCSA Open Source License* allows Emscripten's code to be integrated upstream into LLVM, should the opportunity arise. 13 | 14 | The license for Emscripten |release| (|today|) is reproduced below. The `current full licence `_ can be found on GitHub (and is also present in the root of the SDK). 15 | 16 | .. include:: ../../../../LICENSE 17 | :literal: 18 | 19 | -------------------------------------------------------------------------------- /_sources/docs/introducing_emscripten/emscripten_license.txt: -------------------------------------------------------------------------------- 1 | .. _emscripten-license: 2 | 3 | =================== 4 | Open Source License 5 | =================== 6 | 7 | Emscripten is made available under two permissive open source licenses: the *MIT license* and the *University of Illinois/NCSA Open Source License*. 8 | 9 | There is little, if any, practical difference between the licenses. They are both offered because the: 10 | 11 | - *MIT license* is well known and understood. 12 | - *University of Illinois/NCSA Open Source License* allows Emscripten's code to be integrated upstream into LLVM, should the opportunity arise. 13 | 14 | The license for Emscripten |release| (|today|) is reproduced below. The `current full licence `_ can be found on GitHub (and is also present in the root of the SDK). 15 | 16 | .. include:: ../../../../LICENSE 17 | :literal: 18 | 19 | -------------------------------------------------------------------------------- /_sources/docs/introducing_emscripten/index.rst.txt: -------------------------------------------------------------------------------- 1 | .. _introducing-emscripten-index: 2 | 3 | ====================== 4 | Introducing Emscripten 5 | ====================== 6 | 7 | This section explains what Emscripten does, why it is needed, its limitations and its licensing. After reading, you will understand whether Emscripten is the right tool for you, and where to go if you have :ref:`further questions `. 8 | 9 | .. toctree:: 10 | :maxdepth: 1 11 | 12 | about_emscripten 13 | community 14 | emscripten_license 15 | release_notes 16 | Talks-and-Publications 17 | -------------------------------------------------------------------------------- /_sources/docs/introducing_emscripten/index.txt: -------------------------------------------------------------------------------- 1 | .. _introducting-emscripten-index: 2 | 3 | ====================== 4 | Introducing Emscripten 5 | ====================== 6 | 7 | This section explains what Emscripten does, why it is needed, its limitations and its licensing. After reading, you will understand whether Emscripten is the right tool for you, and where to go if you have :ref:`further questions `. 8 | 9 | .. toctree:: 10 | :maxdepth: 1 11 | 12 | about_emscripten 13 | community 14 | emscripten_license 15 | release_notes 16 | Talks-and-Publications 17 | -------------------------------------------------------------------------------- /_sources/docs/introducing_emscripten/release_notes.rst.txt: -------------------------------------------------------------------------------- 1 | .. _release-notes: 2 | 3 | ============= 4 | Release Notes 5 | ============= 6 | 7 | Changes between tagged Emscripten versions are recorded in the 8 | `ChangeLog `_ 9 | (``ChangeLog.md`` in the source repo). 10 | This log includes high-level information about new features, user-oriented 11 | fixes, options, command-line parameters, usage changes, deprecations, 12 | significant internal modifications, optimizations, etc. The log for each version 13 | links to a detailed diff report, which lists all the incremental changes since 14 | the previous release. 15 | -------------------------------------------------------------------------------- /_sources/docs/introducing_emscripten/release_notes.txt: -------------------------------------------------------------------------------- 1 | .. _release-notes: 2 | 3 | ============= 4 | Release Notes 5 | ============= 6 | 7 | Changes between tagged Emscripten versions are recorded in the :ref:`ChangeLog`. 8 | This log includes high-level information about new features, user-oriented 9 | fixes, options, command-line parameters, usage changes, deprecations, 10 | significant internal modifications, optimizations, etc. The log for each version 11 | links to a detailed diff report, which lists all the incremental changes since 12 | the previous release. 13 | 14 | In addition, the mailing list is used to announce each new :term:`SDK` release; 15 | these announcements include additional informal release notes and "highlights" 16 | information. The easiest way to find these posts is to use `this search 17 | `_. 18 | 19 | .. _ChangeLog: 20 | 21 | ChangeLog 22 | ========= 23 | 24 | The ChangeLog for Emscripten |release| (|today|) is listed below. 25 | 26 | .. include:: ../../../../ChangeLog.md 27 | :literal: 28 | -------------------------------------------------------------------------------- /_sources/docs/optimizing/Profiling-Toolchain.rst.txt: -------------------------------------------------------------------------------- 1 | .. _Profiling-Toolchain: 2 | 3 | ======================= 4 | Profiling the Toolchain 5 | ======================= 6 | 7 | The toolchain interacts with a moderate amount of external tools and sublibraries, the exact set generally depends on which compilation and linker flags were used. If you are seeing abnormal compilation times, or if you are developing the Emscripten toolchain itself, it may be useful to profile the toolchain performance itself as it compiles your project. Emscripten has a built-in toolchain wide ``emprofile.py`` profiler that can be used for this purpose. 8 | 9 | Quick Example 10 | ============= 11 | 12 | To try out the toolchain profiler, run the following set of commands: 13 | 14 | .. code-block:: bash 15 | 16 | cd path/to/emscripten 17 | export EMPROFILE=1 18 | emcc test/hello_world.c -O3 -o a.html 19 | emprofile 20 | 21 | On Windows, replace the ``export`` keyword with ``set`` instead. The last command should generate a HTML file of form ``toolchain_profiler.results_yyyymmdd_hhmm.html`` that can be opened in the web browser to view the results. 22 | 23 | Details 24 | ======= 25 | 26 | The toolchain profiler is active whenever the toolchain is invoked with the environment variable ``EMPROFILE=1`` being set. In this mode, each called tool will accumulate profiling instrumentation data to a set of .json files under the Emscripten temp directory. 27 | 28 | Profiling Tool Commands 29 | ----------------------- 30 | 31 | The command ``tools/emprofile.py --clear`` deletes all previously stored profiling data. Call this command to erase the profiling session to a fresh empty state. To start profiling, call Emscripten tool commands with the environment variable ``EMPROFILE=1`` set either system-wide as shown in the example, or on a per command basis, like this: 32 | 33 | .. code-block:: bash 34 | 35 | emprofile --clear 36 | EMPROFILE=1 emcc -c foo.c a.o 37 | EMPROFILE=1 emcc a.o -O3 -o a.html 38 | emprofile --outfile=myresults.html 39 | 40 | Any number of commands can be profiled within one session, and when ``emprofile`` is finally called, it will pick up records from all Emscripten tool invocations up to that point, graph them, and clear the recorded profiling data for the next run. 41 | 42 | The output HTML filename can be chosen with the optional ``--outfile=myresults.html`` parameter. 43 | 44 | Instrumenting Python Scripts 45 | ============================ 46 | 47 | Python Profiling Blocks 48 | ----------------------- 49 | 50 | Graphing the subprocess start and end times alone might sometimes be a bit too coarse view into what is happening. In Python code, it is possible to hierarchically annotate individual blocks of code to break down execution into custom tasks. These blocks will be shown in blue in the output graph. To add a custom profiling block, use the Python ``with`` keyword to add a ``profile_block`` section: 51 | 52 | .. code-block:: python 53 | 54 | with ToolchainProfiler.profile_block('my_custom_task'): 55 | do_some_tasks() 56 | call_another_function() 57 | more_code() 58 | 59 | this_is_outside_the_block() 60 | 61 | This will show the three functions in the same scope under a block 'my_custom_task' drawn in blue in the profiling swimlane. 62 | 63 | In some cases it may be cumbersome to wrap the code inside a ``with`` section. For these scenarios, it is also possible to use low level C-style ``enter_block`` and ``exit_block`` statements. 64 | 65 | .. code-block:: python 66 | 67 | ToolchainProfiler.enter_block('my_code_block') 68 | try: 69 | do_some_tasks() 70 | call_another_function() 71 | more_code() 72 | finally: 73 | ToolchainProfiler.exit_block('my_code_block') 74 | 75 | However when using this form one must be cautious to ensure that each call to ``ToolchainProfiler.enter_block()`` is matched by exactly one call to ``ToolchainProfiler.exit_block()`` in all code flows, so wrapping the code in a ``try-finally`` statement is a good idea. 76 | -------------------------------------------------------------------------------- /_sources/docs/optimizing/Profiling-Toolchain.txt: -------------------------------------------------------------------------------- 1 | .. _Profiling-Toolchain: 2 | 3 | ======================= 4 | Profiling the Toolchain 5 | ======================= 6 | 7 | The toolchain interacts with a moderate amount of external tools and sublibraries, the exact set generally depends on which compilation and linker flags were used. If you are seeing abnormal compilation times, or if you are developing the Emscripten toolchain itself, it may be useful to profile the toolchain performance itself as it compiles your project. Emscripten has a built-in toolchain wide ``emprofile.py`` profiler that can be used for this purpose. 8 | 9 | Quick Example 10 | ============= 11 | 12 | To try out the toolchain profiler, run the following set of commands: 13 | 14 | .. code-block:: bash 15 | 16 | cd path/to/emscripten 17 | tools/emprofile.py --reset 18 | export EM_PROFILE_TOOLCHAIN=1 19 | emcc tests/hello_world.c -O3 -o a.html 20 | tools/emprofile.py --graph 21 | 22 | On Windows, replace the ``export`` keyword with ``set`` instead. The last command should generate a HTML file of form ``toolchain_profiler.results_yyyymmdd_hhmm.html`` that can be opened in the web browser to view the results. 23 | 24 | Details 25 | ======= 26 | 27 | The toolchain profiler is active whenever the toolchain is invoked with the environment variable ``EM_PROFILE_TOOLCHAIN=1`` being set. In this mode, each called tool will accumulate profiling instrumentation data to a set of .json files under the Emscripten temp directory. 28 | 29 | Profiling Tool Commands 30 | ----------------------- 31 | 32 | The command ``tools/emprofile.py --reset`` deletes all previously stored profiling data. Call this command to erase the profiling session to a fresh empty state. To start profiling, call Emscripten tool commands with the environment variable ``EM_PROFILE_TOOLCHAIN=1`` set either system-wide as shown in the example, or on a per command basis, like this: 33 | 34 | .. code-block:: bash 35 | 36 | cd path/to/emscripten 37 | tools/emprofile.py --reset 38 | EM_PROFILE_TOOLCHAIN=1 emcc tests/hello_world.c -o a.bc 39 | EM_PROFILE_TOOLCHAIN=1 emcc a.bc -O3 -o a.html 40 | tools/emprofile.py --graph --outfile=myresults.html 41 | 42 | Any number of commands can be profiled within one session, and when ``tools/emprofile.py --graph`` is finally called, it will pick up records from all Emscripten tool invocations up to that point. Calling ``--graph`` also clears the recorded profiling data. 43 | 44 | The output HTML filename can be chosen with the optional ``--outfile=myresults.html`` parameter. 45 | 46 | Instrumenting Python Scripts 47 | ============================ 48 | 49 | In order for the toolchain to work, each "top level" Python script (a script that is directly called from the command line, or by a subprocess spawn) should have the following preamble in the beginning of the script: 50 | 51 | .. code-block:: python 52 | 53 | from tools.toolchain_profiler import ToolchainProfiler 54 | if __name__ == '__main__': 55 | ToolchainProfiler.record_process_start() 56 | 57 | Additionally, at the end of the script when the script is about to exit, it should do so by explicitly calling either the ``sys.exit()`` function, or by calling the ``ToolchainProfiler.record_process_exit()`` function, whichever is more convenient for the script. The function ``ToolchainProfiler.record_process_exit()`` does not exit by itself, but only records that the process is quitting. 58 | 59 | These two blocks ensure that the toolchain profiler will be aware of all tool invocations that occur. In the graphed output, the process spawns will be shown in green color. 60 | 61 | Python Profiling Blocks 62 | ----------------------- 63 | 64 | Graphing the subprocess start and end times alone might sometimes be a bit too coarse view into what is happening. In Python code, it is possible to hierarchically annotate individual blocks of code to break down execution into custom tasks. These blocks will be shown in blue in the output graph. To add a custom profiling block, use the Python ``with`` keyword to add a ``profile_block`` section: 65 | 66 | .. code-block:: python 67 | 68 | with ToolchainProfiler.profile_block('my_custom_task'): 69 | do_some_tasks() 70 | call_another_function() 71 | more_code() 72 | 73 | this_is_outside_the_block() 74 | 75 | This will show the three functions in the same scope under a block 'my_custom_task' drawn in blue in the profiling swimlane. 76 | 77 | In some cases it may be cumbersome to wrap the code inside a ``with`` section. For these scenarios, it is also possible to use low level C-style ``enter_block`` and ``exit_block`` statements. 78 | 79 | .. code-block:: python 80 | 81 | ToolchainProfiler.enter_block('my_code_block') 82 | try: 83 | do_some_tasks() 84 | call_another_function() 85 | more_code() 86 | finally: 87 | ToolchainProfiler.exit_block('my_code_block') 88 | 89 | However when using this form one must be cautious to ensure that each call to ``ToolchainProfiler.enter_block()`` is matched by exactly one call to ``ToolchainProfiler.exit_block()`` in all code flows, so wrapping the code in a ``try-finally`` statement is a good idea. 90 | -------------------------------------------------------------------------------- /_sources/docs/porting/connecting_cpp_and_javascript/index.rst.txt: -------------------------------------------------------------------------------- 1 | .. _connecting-cpp-and-javascript-index: 2 | 3 | ============================= 4 | Connecting C++ and JavaScript 5 | ============================= 6 | 7 | Emscripten provides various options for connecting "normal" JavaScript and compiled code, which range from functions to call compiled C/C++ from JavaScript (and vice versa) through to accessing environment variables from compiled code. 8 | 9 | The topic :ref:`Interacting-with-code` provides an overview of all the methods. The other two topics provide additional detail on the :ref:`Embind` and :ref:`WebIDL-Binder` tools. 10 | 11 | .. note:: For information on how compiled code interacts with the browser environment, see :ref:`emscripten-runtime-environment`. For file system-related manners, see the :ref:`file-system-overview`. 12 | 13 | .. toctree:: 14 | :maxdepth: 1 15 | 16 | Interacting-with-code 17 | embind 18 | WebIDL-Binder 19 | 20 | -------------------------------------------------------------------------------- /_sources/docs/porting/connecting_cpp_and_javascript/index.txt: -------------------------------------------------------------------------------- 1 | .. _connecting-cpp-and-javascript-index: 2 | 3 | ============================= 4 | Connecting C++ and JavaScript 5 | ============================= 6 | 7 | Emscripten provides various options for connecting "normal" JavaScript and compiled code, which range from functions to call compiled C/C++ from JavaScript (and vice versa) through to accessing environment variables from compiled code. 8 | 9 | The topic :ref:`Interacting-with-code` provides an overview of all the methods. The other two topics provide additional detail on the :ref:`Embind` and :ref:`WebIDL-Binder` tools. 10 | 11 | .. note:: For information on how compiled code interacts with the browser environment, see :ref:`emscripten-runtime-environment`. For file system-related manners, see the :ref:`file-system-overview`. 12 | 13 | .. toctree:: 14 | :maxdepth: 1 15 | 16 | Interacting-with-code 17 | embind 18 | WebIDL-Binder 19 | 20 | -------------------------------------------------------------------------------- /_sources/docs/porting/files/Synchronous-Virtual-XHR-Backed-File-System-Usage.rst.txt: -------------------------------------------------------------------------------- 1 | .. _Synchronous-Virtual-XHR-Backed-File-System-Usage: 2 | 3 | ================================================ 4 | Synchronous Virtual XHR Backed File System Usage 5 | ================================================ 6 | 7 | Emscripten supports lazy loading of binary data from HTTP servers using :term:`XHR`. This functionality can be used to create a backend for synchronous file access from compiled code. 8 | 9 | The backend can improve start up time as the whole file system does not need to be preloaded before compiled code is run. It can also be very efficient if the web server supports `byte serving `_ — in this case Emscripten can just read the parts of files that are actually needed. 10 | 11 | .. warning:: This mechanism is only possible in `Web Workers `_ (due to browser limitations). 12 | 13 | .. note:: If byte serving is not supported then Emscripten will have to load the whole file (however big) even if a single byte is read. 14 | 15 | 16 | Test code 17 | ========= 18 | 19 | An example of how to implement a synchronous virtual XHR backed file system is provided in the test code at `test/test_browser.py `_ (see ``test_chunked_synchronous_xhr``). The test case also contains an HTTP server (see `test_chunked_synchronous_xhr_server `_) showing CORS headers that might need to be set (if the resources are hosted from the same domain Emscripten runs from, there is no issue). 20 | 21 | The tests use `checksummer.c `_ as the Emscripten-compiled program. This is simply a vanilla C program using synchronous *libc* file system calls like ``fopen()``, ``fread()``, ``fclose()`` etc. 22 | 23 | JavaScript code is added (using *emcc*'s :ref:`pre-js ` option) to map the file system calls in **checksummer.c** to a file in the virtual file system. This file is *created* early in Emscripten initialisation using :js:func:`FS.createLazyFile`, but only loaded with content from the server when the file is first accessed by compiled code. The added JavaScript code also sets up communication between the web worker and the main thread. 24 | 25 | 26 | Instructions 27 | ============ 28 | 29 | #. 30 | You will need to add JavaScript to the generated code to map the file accessed by your compiled native code and the server. 31 | 32 | The test code simply creates a file in the virtual file system using :js:func:`FS.createLazyFile` and sets the compiled code to use the same file (**/bigfile**): 33 | 34 | .. include:: ../../../../../test/test_browser.py 35 | :literal: 36 | :start-after: create_file('worker_prejs.js' 37 | :end-before: var doTrace = true; 38 | :code: javascript 39 | 40 | .. note:: 41 | 42 | - The compiled test code (in this case) gets the file name from command line arguments — these are set in Emscripten using :js:attr:`Module.arguments`. 43 | - The call to create the file is added to :js:attr:`Module.preInit`. This ensures that it is run before any compiled code. 44 | - The additional JavaScript is added using *emcc*'s :ref:`prejs ` option. 45 | 46 | #. 47 | The added JavaScript should also include code to allow the web worker to communicate with the original thread. 48 | 49 | The test code adds the following JavaScript to the web worker for this purpose. It uses ``postMessage()`` to send its ``stdout`` back to the main thread. 50 | 51 | .. include:: ../../../../../test/test_browser.py 52 | :literal: 53 | :start-after: var doTrace = true; 54 | :end-before: """) 55 | :code: javascript 56 | 57 | .. note:: If you use the above solution, the parent page should probably contain handwritten glue code to handle the ``stdout`` data. 58 | 59 | #. 60 | You will need a page that spawns the web worker. 61 | 62 | The `test code `_ that does this is shown below: 63 | 64 | .. include:: ../../../../../test/test_browser.py 65 | :literal: 66 | :start-after: create_file('main.html', ''' 67 | :end-before: ''' % self.PORT) 68 | :code: html 69 | -------------------------------------------------------------------------------- /_sources/docs/porting/files/Synchronous-Virtual-XHR-Backed-File-System-Usage.txt: -------------------------------------------------------------------------------- 1 | .. _Synchronous-Virtual-XHR-Backed-File-System-Usage: 2 | 3 | ================================================ 4 | Synchronous Virtual XHR Backed File System Usage 5 | ================================================ 6 | 7 | Emscripten supports lazy loading of binary data from HTTP servers using :term:`XHR`. This functionality can be used to create a backend for synchronous file access from compiled code. 8 | 9 | The backend can improve start up time as the whole file system does not need to be preloaded before compiled code is run. It can also be very efficient if the web server supports `byte serving `_ — in this case Emscripten can just read the parts of files that are actually needed. 10 | 11 | .. warning:: This mechanism is only possible in `Web Workers `_ (due to browser limitations). 12 | 13 | .. note:: If byte serving is not supported then Emscripten will have to load the whole file (however big) even if a single byte is read. 14 | 15 | 16 | Test code 17 | ========= 18 | 19 | An example of how to implement a synchronous virtual XHR backed file system is provided in the test code at `tests/test_browser.py `_ (see ``test_chunked_synchronous_xhr``). The test case also contains an HTTP server (see `test_chunked_synchronous_xhr_server `_) showing CORS headers that might need to be set (if the resources are hosted from the same domain Emscripten runs from, there is no issue). 20 | 21 | The tests use `checksummer.c `_ as the Emscripten-compiled program. This is simply a vanilla C program using synchronous *libc* file system calls like ``fopen()``, ``fread()``, ``fclose()`` etc. 22 | 23 | JavaScript code is added (using *emcc*'s :ref:`pre-js ` option) to map the file system calls in **checksummer.c** to a file in the virtual file system. This file is *created* early in Emscripten initialisation using :js:func:`FS.createLazyFile`, but only loaded with content from the server when the file is first accessed by compiled code. The added JavaScript code also sets up communication between the web worker and the main thread. 24 | 25 | 26 | Instructions 27 | ============ 28 | 29 | #. 30 | You will need to add JavaScript to the generated code to map the file accessed by your compiled native code and the server. 31 | 32 | The test code simply creates a file in the virtual file system using :js:func:`FS.createLazyFile` and sets the compiled code to use the same file (**/bigfile**): 33 | 34 | .. include:: ../../../../../tests/test_browser.py 35 | :literal: 36 | :start-after: prejs_file.write(r""" 37 | :end-before: var doTrace = true; 38 | :code: javascript 39 | 40 | .. note:: 41 | 42 | - The compiled test code (in this case) gets the file name from command line arguments — these are set in Emscripten using :js:attr:`Module.arguments`. 43 | - The call to create the file is added to :js:attr:`Module.preInit`. This ensures that it is run before any compiled code. 44 | - The additional JavaScript is added using *emcc*'s :ref:`prejs ` option. 45 | 46 | #. 47 | The added JavaScript should also include code to allow the web worker to communicate with the original thread. 48 | 49 | The test code adds the following JavaScript to the web worker for this purpose. It uses ``postMessage()`` to send its ``stdout`` back to the main thread. 50 | 51 | .. include:: ../../../../../tests/test_browser.py 52 | :literal: 53 | :start-after: var doTrace = true; 54 | :end-before: """) 55 | :code: javascript 56 | 57 | .. note:: If you use the above solution, the parent page should probably contain handwritten glue code to handle the ``stdout`` data. 58 | 59 | #. 60 | You will need a page that spawns the web worker. 61 | 62 | The `test code `_ that does this is shown below: 63 | 64 | .. include:: ../../../../../tests/test_browser.py 65 | :literal: 66 | :start-after: html_file.write(r""" 67 | :end-before: html_file.close() 68 | :code: html 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | -------------------------------------------------------------------------------- /_sources/docs/porting/files/file_systems_overview.rst.txt: -------------------------------------------------------------------------------- 1 | .. _file-system-overview: 2 | 3 | ==================== 4 | File System Overview 5 | ==================== 6 | 7 | The following sections provide a brief overview of the :ref:`Emscripten file system environment ` and :ref:`architecture `. In addition to discussing support for standard C/C++ synchronous file APIs, it briefly discusses the :ref:`File System API ` and Emscripten's :ref:`emscripten-h-asynchronous-file-system-api`. 8 | 9 | .. _file-system-runtime-environment: 10 | 11 | Emscripten file system runtime environment 12 | ========================================== 13 | 14 | Native code and "normal" JavaScript use quite different file-access paradigms. Portable native code usually calls *synchronous* file APIs in **libc** and **libcxx**, while JavaScript allows only *asynchronous* file access (except in web workers). In addition, JavaScript does not have direct access to the host file system when run inside the sandbox environment provided by a web browser. 15 | 16 | Emscripten provides a virtual file system that simulates the local file system, so that native code using synchronous file APIs can be compiled and run with little or no change. 17 | 18 | :ref:`packaging-files` explains how you can use *emcc* to specify which files you need to include in the file system. For many developers, that may be all you need to do. 19 | 20 | .. _file-system-architectural-overview: 21 | 22 | Emscripten file system architecture 23 | =================================== 24 | 25 | The main elements of the Emscripten File System architecture are shown below. Most native code will call the *synchronous* file APIs in **libc** and **libcxx**. These in turn call the underlying :ref:`File System API `, which by default uses the :ref:`MEMFS ` virtual file system. 26 | 27 | .. figure:: FileSystemArchitecture.png 28 | :alt: File System Architecture 29 | :align: center 30 | 31 | ``MEMFS`` is mounted at ``/`` when the runtime is initialized. Files to be added to the MEMFS virtual file system are specified at compile time using *emcc*, as discussed in :ref:`packaging-files`. The files are loaded asynchronously by JavaScript using :ref:`Synchronous XHRs ` when the page is first loaded. The compiled code is only allowed to run (and call synchronous APIs) when the asynchronous download has completed and the files are available in the virtual file system. 32 | 33 | With ``MEMFS`` all files exist strictly in-memory, and any data written to them is lost when the page is reloaded. If persistent data is required you can mount the :ref:`IDBFS ` file system in a browser or :ref:`NODEFS ` on *node.js*. :ref:`NODEFS ` provides direct access to the local file system, but only when run inside *node.js*. You can call the :ref:`File System API ` directly from your own JavaScript to mount new file systems, and to perform other synchronous file system operations that might be required. There is more information on this topic in :ref:`filesystem-api-filesystems`. 34 | 35 | If you need to fetch other files from the network to the file system then use :c:func:`emscripten_wget` and the other methods in the :ref:`emscripten-h-asynchronous-file-system-api`. These methods are asynchronous and the application must wait until the registered callback completes before trying to read them. 36 | 37 | 38 | -------------------------------------------------------------------------------- /_sources/docs/porting/files/file_systems_overview.txt: -------------------------------------------------------------------------------- 1 | .. _file-system-overview: 2 | 3 | ==================== 4 | File System Overview 5 | ==================== 6 | 7 | The following sections provide a brief overview of the :ref:`Emscripten file system environment ` and :ref:`architecture `. In addition to discussing support for standard C/C++ synchronous file APIs, it briefly discusses the :ref:`File System API ` and Emscripten's :ref:`emscripten-h-asynchronous-file-system-api`. 8 | 9 | .. _file-system-runtime-environment: 10 | 11 | Emscripten file system runtime environment 12 | ========================================== 13 | 14 | Native code and "normal" JavaScript use quite different file-access paradigms. Portable native code usually calls *synchronous* file APIs in **libc** and **libcxx**, while JavaScript allows only *asynchronous* file access (except in web workers). In addition, JavaScript does not have direct access to the host file system when run inside the sandbox environment provided by a web browser. 15 | 16 | Emscripten provides a virtual file system that simulates the local file system, so that native code using synchronous file APIs can be compiled and run with little or no change. 17 | 18 | :ref:`packaging-files` explains how you can use *emcc* to specify which files you need to include in the file system. For many developers, that may be all you need to do. 19 | 20 | .. _file-system-architectural-overview: 21 | 22 | Emscripten file system architecture 23 | =================================== 24 | 25 | The main elements of the Emscripten File System architecture are shown below. Most native code will call the *synchronous* file APIs in **libc** and **libcxx**. These in turn call the underlying :ref:`File System API `, which by default uses the :ref:`MEMFS ` virtual file system. 26 | 27 | .. figure:: FileSystemArchitecture.png 28 | :alt: File System Architecture 29 | :align: center 30 | 31 | ``MEMFS`` is mounted at ``/`` when the runtime is initialized. Files to be added to the MEMFS virtual file system are specified at compile time using *emcc*, as discussed in :ref:`packaging-files`. The files are loaded asynchronously by JavaScript using :ref:`Synchronous XHRs ` when the page is first loaded. The compiled code is only allowed to run (and call synchronous APIs) when the asynchronous download has completed and the files are available in the virtual file system. 32 | 33 | With ``MEMFS`` all files exist strictly in-memory, and any data written to them is lost when the page is reloaded. If persistent data is required you can mount the :ref:`IDBFS ` file system in a browser or :ref:`NODEFS ` on *node.js*. :ref:`NODEFS ` provides direct access to the local file system, but only when run inside *node.js*. You can call the :ref:`File System API ` directly from your own JavaScript to mount new file systems, and to perform other synchronous file system operations that might be required. There is more information on this topic in :ref:`filesystem-api-filesystems`. 34 | 35 | If you need to fetch other files from the network to the file system then use :c:func:`emscripten_wget` and the other methods in the :ref:`emscripten-h-asynchronous-file-system-api`. These methods are asynchronous and the application must wait until the registered callback completes before trying to read them. 36 | 37 | 38 | -------------------------------------------------------------------------------- /_sources/docs/porting/files/index.rst.txt: -------------------------------------------------------------------------------- 1 | .. _packaging-code-index: 2 | 3 | ====================== 4 | Files and File Systems 5 | ====================== 6 | 7 | This section contains articles related to using files in Emscripten-compiled code. 8 | 9 | - The :ref:`file-system-overview` provides a high level overview of how file operations are supported by Emscripten. 10 | - :ref:`packaging-files` shows how to use :ref:`emcc ` to package the files needed by compiled code. 11 | - :ref:`Synchronous-Virtual-XHR-Backed-File-System-Usage` explains how to setup lazy loading of binary data from HTTP servers using XHR’s. 12 | 13 | .. seealso:: API Reference: 14 | 15 | - :ref:`Filesystem-API` (JavaScript). 16 | - :ref:`emscripten-h-asynchronous-file-system-api` (C/C++). 17 | 18 | .. toctree:: 19 | :hidden: 20 | 21 | file_systems_overview 22 | packaging_files 23 | Synchronous-Virtual-XHR-Backed-File-System-Usage 24 | 25 | -------------------------------------------------------------------------------- /_sources/docs/porting/files/index.txt: -------------------------------------------------------------------------------- 1 | .. _packaging-code-index: 2 | 3 | ====================== 4 | Files and File Systems 5 | ====================== 6 | 7 | This section contains articles related to using files in Emscripten-compiled code. 8 | 9 | - The :ref:`file-system-overview` provides a high level overview of how file operations are supported by Emscripten. 10 | - :ref:`packaging-files` shows how to use :ref:`emcc ` to package the files needed by compiled code. 11 | - :ref:`Synchronous-Virtual-XHR-Backed-File-System-Usage` explains how to setup lazy loading of binary data from HTTP servers using XHR’s. 12 | 13 | .. seealso:: API Reference: 14 | 15 | - :ref:`Filesystem-API` (JavaScript). 16 | - :ref:`emscripten-h-asynchronous-file-system-api` (C/C++). 17 | 18 | .. toctree:: 19 | :hidden: 20 | 21 | file_systems_overview 22 | packaging_files 23 | Synchronous-Virtual-XHR-Backed-File-System-Usage 24 | 25 | -------------------------------------------------------------------------------- /_sources/docs/porting/guidelines/api_limitations.rst.txt: -------------------------------------------------------------------------------- 1 | .. _api-limitations: 2 | 3 | =============== 4 | API Limitations 5 | =============== 6 | 7 | The browser environment and JavaScript are different from the native environments that C and C++ typically run in. These differences impose some limitations on how native APIs can be called and used. This section lists some of the more obvious limitations. 8 | 9 | Networking 10 | ========== 11 | 12 | Emscripten supports *libc* networking functions but you must limit yourself to asynchronous (non-blocking) operations. This is required because the underlying JavaScript networking functions are asynchronous. 13 | 14 | File Systems 15 | ============ 16 | 17 | Emscripten supports *libc* file system functions and C/C++ code can be written in the normal way. 18 | 19 | Code run in a :ref:`browser environment ` is sandboxed, and does not have direct access to the local file system. Instead, Emscripten creates a virtual file system that may be preloaded with data or linked to URLs for lazy loading. This affects when synchronous file system functions can be called and how a project is compiled. See the :ref:`file-system-overview` for more information. 20 | 21 | 22 | Application Main Loop 23 | ===================== 24 | 25 | The browser event model uses *co-operative multitasking* — each event has a "turn" to run, and must then return control to the browser event loop so that other events can be processed. A common cause of HTML pages hanging is JavaScript that does not complete and return control to the browser. 26 | 27 | This can affect how an application using an infinite main loop is written. See :ref:`emscripten-runtime-environment` for more information. 28 | 29 | Other APIs 30 | ========== 31 | 32 | Support for other **portable** C/C++ code is :ref:`fairly comprehensive `. 33 | 34 | -------------------------------------------------------------------------------- /_sources/docs/porting/guidelines/api_limitations.txt: -------------------------------------------------------------------------------- 1 | .. _api-limitations: 2 | 3 | =============== 4 | API Limitations 5 | =============== 6 | 7 | The browser environment and JavaScript are different from the native environments that C and C++ typically run in. These differences impose some limitations on how native APIs can be called and used. This section lists some of the more obvious limitations. 8 | 9 | Networking 10 | ========== 11 | 12 | Emscripten supports *libc* networking functions but you must limit yourself to asynchronous (non-blocking) operations. This is required because the underlying JavaScript networking functions are asynchronous. 13 | 14 | File Systems 15 | ============ 16 | 17 | Emscripten supports *libc* file system functions and C/C++ code can be written in the normal way. 18 | 19 | Code run in a :ref:`browser environment ` is sandboxed, and does not have direct access to the local file system. Instead, Emscripten creates a virtual file system that may be preloaded with data or linked to URLs for lazy loading. This affects when synchronous file system functions can be called and how a project is compiled. See the :ref:`file-system-overview` for more information. 20 | 21 | 22 | Application Main Loop 23 | ===================== 24 | 25 | The browser event model uses *co-operative multitasking* — each event has a "turn" to run, and must then return control to the browser event loop so that other events can be processed. A common cause of HTML pages hanging is JavaScript that does not complete and return control to the browser. 26 | 27 | This can affect how an application using an infinite main loop is written. See :ref:`emscripten-runtime-environment` for more information. 28 | 29 | Other APIs 30 | ========== 31 | 32 | Support for other **portable** C/C++ code is :ref:`fairly comprehensive `. 33 | 34 | -------------------------------------------------------------------------------- /_sources/docs/porting/guidelines/browser_limitations.rst.txt: -------------------------------------------------------------------------------- 1 | .. _Browser-limitations: 2 | 3 | ============================ 4 | Specific Browser Limitations 5 | ============================ 6 | 7 | This page lists some of the differences between the latest versions of the major browsers that are relevant to Emscripten-compiled applications and games: 8 | 9 | - The function :c:func:`emscripten_get_now` returns a wallclock time as a ``float`` in milliseconds. *Opera 12.16* and `Windows Google Chrome 28.0.1500.95 `_ have a limitation that the timer precision is only in milliseconds. On other major browsers (*IE10*, *Firefox 22*, *Chrome 28* on non-Windows) it has sub-millisecond precision. 10 | - WebGL is not fully supported on *Internet Explorer*: 11 | 12 | - *Internet Explorer 10* and older do not support WebGL. Trying to initialize a GL context via EGL, GLUT, SDL or similar will fail. Emscripten applications that do not depend on OpenGL can still run on this browser. 13 | - *Internet Explorer 11* supports only part of WebGL 1.0. Some commands, shaders etc. may not work. You may be able to limit your app to using the subset that is supported by IE11. 14 | - WebGL support on other major browsers is fairly good (see `WebGL support in different browsers `_). 15 | 16 | - *Opera 12.16* has limited support for the W3C File API. In particular it does not support `createObjectURL functionality `_, which means that it is not possible to use the browser's image codecs to decode preloaded files in the Emscripten virtual file system. 17 | - OpenAL and SDL audio support in Emscripten depend on the Web Audio API (see `Web Audio API support in different browsers `_). 18 | 19 | -------------------------------------------------------------------------------- /_sources/docs/porting/guidelines/browser_limitations.txt: -------------------------------------------------------------------------------- 1 | .. _Browser-limitations: 2 | 3 | ============================ 4 | Specific Browser Limitations 5 | ============================ 6 | 7 | This page lists some of the differences between the latest versions of the major browsers that are relevant to Emscripten-compiled applications and games: 8 | 9 | - The function :c:func:`emscripten_get_now` returns a wallclock time as a ``float`` in milliseconds. *Opera 12.16* and `Windows Google Chrome 28.0.1500.95 `_ have a limitation that the timer precision is only in milliseconds. On other major browsers (*IE10*, *Firefox 22*, *Chrome 28* on non-Windows) it has sub-millisecond precision. 10 | - WebGL is not fully supported on *Internet Explorer* (at least prior to IE12): 11 | 12 | - *Internet Explorer 10* and older do not support WebGL. Trying to initialize a GL context via EGL, GLUT, SDL or similar will fail. Emscripten applications that do not depend on OpenGL can still run on this browser. 13 | - *Internet Explorer 11* supports only part of WebGL 1.0. Some commands, shaders etc. may not work. You may be able to limit your app to using the subset that is supported by IE11. 14 | - WebGL support on other major browsers is fairly good (see `WebGL support in different browsers `_). 15 | 16 | - *Opera 12.16* has limited support for the W3C File API. In particular it does not support `createObjectURL functionality `_, which means that it is not possible to use the browser's image codecs to decode preloaded files in the Emscripten virtual file system. 17 | - OpenAL and SDL audio support in Emscripten depend on the Web Audio API (see `Web Audio API support in different browsers `_). 18 | 19 | -------------------------------------------------------------------------------- /_sources/docs/porting/guidelines/index.rst.txt: -------------------------------------------------------------------------------- 1 | .. _guidelines-index: 2 | 3 | ================================ 4 | Code Portability and Limitations 5 | ================================ 6 | 7 | Emscripten can be used to compile almost any *portable* C/C++ code to JavaScript. The topics in this section help identify less portable code, and code that may need to be changed because of limitations in the browser environment or Emscripten-compiled JavaScript. 8 | 9 | .. toctree:: 10 | :maxdepth: 1 11 | 12 | portability_guidelines 13 | api_limitations 14 | function_pointer_issues 15 | browser_limitations.rst 16 | 17 | 18 | 19 | 20 | -------------------------------------------------------------------------------- /_sources/docs/porting/guidelines/index.txt: -------------------------------------------------------------------------------- 1 | .. _guidelines-index: 2 | 3 | ================================ 4 | Code Portability and Limitations 5 | ================================ 6 | 7 | Emscripten can be used to compile almost any *portable* C/C++ code to JavaScript. The topics in this section help identify less portable code, and code that may need to be changed because of limitations in the browser environment or Emscripten-compiled JavaScript. 8 | 9 | .. toctree:: 10 | :maxdepth: 1 11 | 12 | portability_guidelines 13 | api_limitations 14 | function_pointer_issues 15 | browser_limitations.rst 16 | 17 | 18 | 19 | 20 | -------------------------------------------------------------------------------- /_sources/docs/porting/guidelines/portability_guidelines.rst.txt: -------------------------------------------------------------------------------- 1 | .. _code-portability-guidelines: 2 | 3 | ====================== 4 | Portability Guidelines 5 | ====================== 6 | 7 | Emscripten can be used to compile almost any *portable* C++/C code to JavaScript. 8 | 9 | This section explains what types of code are non-portable (or more difficult to port), and what code can be compiled but will run slowly. Developers can use this information for evaluating the effort to port and re-write code. 10 | 11 | Current Web limitations 12 | ======================= 13 | 14 | - Multithreading depends on SharedArrayBuffer, which is still being standardized and implemented by browsers. Emscripten has working support for threads, which you can try in development browsers by setting the proper preference. 15 | - SIMD is also in the process of standardization and implementation. 16 | 17 | Code that cannot be compiled 18 | ============================ 19 | 20 | The following types of code would need to be re-written in order to work with Emscripten. (While in theory it might be possible for Emscripten to work around these issues using emulation, it would be very slow.) 21 | 22 | - Code relying on a big-endian architecture. Emscripten-compiled code currently requires a little-endian host to run on, which accounts for 99% of machines connected to the internet. This is because JavaScript typed arrays (used for views on memory) obey the host byte ordering and LLVM needs to know which endianness to target. 23 | - Code that uses low-level features of the native environment, for example native stack manipulation in conjunction with ``setjmp``/``longjmp`` (we support proper ``setjmp``/``longjmp``, i.e., jumping down the stack, but not jumping up to an unwound stack, which is undefined behavior). 24 | - Code that scans registers or the stack. This won't work because a variable in a register or on the stack may be held in a JavaScript local variable (which cannot be scanned). 25 | 26 | .. note:: Code of this type might be used for conservative garbage collection. You can do conservative scanning when there is no other code on the stack, e.g. from an iteration of the main event loop. Other solutions include the SpillPointers pass in Binaryen. 27 | 28 | - Code with architecture-specific inline assembly (like an ``asm()`` containing x86 code) is not portable. That code would need to be replaced with portable C or C++. Sometimes a codebase will have both portable code and optional inline assembly as an optimization, so you might find an option to disable the inline assembly. 29 | 30 | 31 | Code that compiles but might run slowly 32 | ======================================= 33 | 34 | .. note:: Understanding these issues can be helpful when optimising code. 35 | 36 | The following types of code will compile, but may not run as fast as expected: 37 | 38 | - In asm.js (but not WebAssembly), 64-bit ``int`` variables. Mathematical operations (+, -, \*, /) are slow because they are emulated (bitwise operations are reasonably fast). JavaScript does not have a native 64-bit ``int`` type so this is unavoidable. 39 | - C++ Exceptions. In JavaScript such code generally makes the JavaScript engine turn off various optimizations. For that reason exceptions are turned off by default in ``-O1`` and above. To re-enable them, run *emcc* with ``-sDISABLE_EXCEPTION_CATCHING=0`` (see `src/settings.js `_). 40 | - ``setjmp`` also prevents :term:`relooping` around it, forcing us to emulate control flow using a less efficient approach. 41 | 42 | 43 | Other issues 44 | ============ 45 | 46 | - Code that relies on x86 alignment behavior. x86 allows unaligned reads and writes (so for example you can read a 16-bit value from a non-even address), but other architectures do not (32-bit ARM will raise ``SIGILL``). For asm.js loads and stores are forced to aligned offsets; for WebAssembly unaligned loads and stores will work but may be slow depending on the underlying CPU. If you build your code with ``SAFE_HEAP=1`` then you will get a clear runtime exception, see :ref:`Debugging`. 47 | 48 | -------------------------------------------------------------------------------- /_sources/docs/porting/guidelines/portability_guidelines.txt: -------------------------------------------------------------------------------- 1 | .. _code-portability-guidelines: 2 | 3 | ====================== 4 | Portability Guidelines 5 | ====================== 6 | 7 | Emscripten can be used to compile almost any *portable* C++/C code to JavaScript. 8 | 9 | This section explains what types of code are non-portable (or more difficult to port), and what code can be compiled but will run slowly. Developers can use this information for evaluating the effort to port and re-write code. 10 | 11 | Current Web limitations 12 | ======================= 13 | 14 | - Multithreading depends on SharedArrayBuffer, which is still being standardized and implemented by browsers. Emscripten has working support for threads, which you can try in development browsers by setting the proper preference. 15 | - SIMD is also in the process of standardization and implementation. 16 | 17 | Code that cannot be compiled 18 | ============================ 19 | 20 | The following types of code would need to be re-written in order to work with Emscripten. (While in theory it might be possible for Emscripten to work around these issues using emulation, it would be very slow.) 21 | 22 | - Code relying on a big-endian architecture. Emscripten-compiled code currently requires a little-endian host to run on, which accounts for 99% of machines connected to the internet. This is because JavaScript typed arrays (used for views on memory) obey the host byte ordering and LLVM needs to know which endianness to target. 23 | - Code that uses low-level features of the native environment, for example native stack manipulation in conjunction with ``setjmp``/``longjmp`` (we support proper ``setjmp``/``longjmp``, i.e., jumping down the stack, but not jumping up to an unwound stack, which is undefined behavior). 24 | - Code that scans registers or the stack. This won't work because a variable in a register or on the stack may be held in a JavaScript local variable (which cannot be scanned). 25 | 26 | .. note:: Code of this type might be used for conservative garbage collection. You can do conservative scanning when there is no other code on the stack, e.g. from an iteration of the main event loop. Other solutions include the SpillPointers pass in Binaryen. 27 | 28 | - Code with architecture-specific inline assembly (like an ``asm()`` containing x86 code) is not portable. That code would need to be replaced with portable C or C++. Sometimes a codebase will have both portable code and optional inline assembly as an optimization, so you might find an option to disable the inline assembly. 29 | 30 | 31 | Code that compiles but might run slowly 32 | ======================================= 33 | 34 | .. note:: Understanding these issues can be helpful when optimising code. 35 | 36 | The following types of code will compile, but may not run as fast as expected: 37 | 38 | - In asm.js (but not WebAssembly), 64-bit ``int`` variables. Mathematical operations (+, -, \*, /) are slow because they are emulated (bitwise operations are reasonably fast). JavaScript does not have a native 64-bit ``int`` type so this is unavoidable. 39 | - C++ Exceptions. In JavaScript such code generally makes the JavaScript engine turn off various optimizations. For that reason exceptions are turned off by default in ``-O1`` and above. To re-enable them, run *emcc* with ``-s DISABLE_EXCEPTION_CATCHING=0`` (see `src/settings.js `_). 40 | - ``setjmp`` also prevents :term:`relooping` around it, forcing us to emulate control flow using a less efficient approach. 41 | 42 | 43 | Other issues 44 | ============ 45 | 46 | - Code that relies on x86 alignment behavior. x86 allows unaligned reads and writes (so for example you can read a 16-bit value from a non-even address), but other architectures do not (32-bit ARM will raise ``SIGILL``). For asm.js loads and stores are forced to aligned offsets; for WebAssembly unaligned loads and stores will work but may be slow depending on the underlying CPU. If you build your code with ``SAFE_HEAP=1`` then you will get a clear runtime exception, see :ref:`Debugging`. 47 | 48 | -------------------------------------------------------------------------------- /_sources/docs/porting/index.rst.txt: -------------------------------------------------------------------------------- 1 | .. _integrating-porting-index: 2 | 3 | ======= 4 | Porting 5 | ======= 6 | 7 | The topics in this section cover the main integration points that you need to consider when porting C/C++ code to Emscripten, along with general coding and debugging guidelines. 8 | 9 | .. toctree:: 10 | :maxdepth: 1 11 | 12 | guidelines/index 13 | emscripten-runtime-environment 14 | connecting_cpp_and_javascript/index 15 | files/index 16 | multimedia_and_graphics/index 17 | Audio 18 | Debugging 19 | pthreads 20 | networking 21 | simd 22 | exceptions 23 | setjmp-longjmp 24 | asyncify 25 | ../compiling/Building-Projects 26 | 27 | -------------------------------------------------------------------------------- /_sources/docs/porting/index.txt: -------------------------------------------------------------------------------- 1 | .. _integrating-porting-index: 2 | 3 | ======= 4 | Porting 5 | ======= 6 | 7 | The topics in this section cover the main integration points that you need to consider when porting C/C++ code to Emscripten, along with general coding and debugging guidelines. 8 | 9 | .. toctree:: 10 | :maxdepth: 1 11 | 12 | guidelines/index 13 | emscripten-runtime-environment 14 | connecting_cpp_and_javascript/index 15 | files/index 16 | multimedia_and_graphics/index 17 | Audio 18 | Debugging 19 | pthreads 20 | networking 21 | simd 22 | asyncify 23 | ../compiling/Building-Projects 24 | 25 | -------------------------------------------------------------------------------- /_sources/docs/porting/multimedia_and_graphics/index.rst.txt: -------------------------------------------------------------------------------- 1 | .. _multimedia-and-graphics-index: 2 | 3 | ======================= 4 | Multimedia and Graphics 5 | ======================= 6 | 7 | This section contains articles about Emscripten's support for graphics and audio APIs. 8 | 9 | 10 | .. toctree:: 11 | :maxdepth: 1 12 | 13 | EGL-Support-in-Emscripten 14 | OpenGL-support 15 | 16 | -------------------------------------------------------------------------------- /_sources/docs/porting/multimedia_and_graphics/index.txt: -------------------------------------------------------------------------------- 1 | .. _multimedia-and-graphics-index: 2 | 3 | ======================= 4 | Multimedia and Graphics 5 | ======================= 6 | 7 | This section contains articles about Emscripten's support for graphics and audio APIs. 8 | 9 | 10 | .. toctree:: 11 | :maxdepth: 1 12 | 13 | EGL-Support-in-Emscripten 14 | OpenGL-support 15 | 16 | -------------------------------------------------------------------------------- /_sources/docs/porting/setjmp-longjmp.rst.txt: -------------------------------------------------------------------------------- 1 | .. _setjmp-longjmp: 2 | 3 | ======================== 4 | C setjmp-longjmp Support 5 | ======================== 6 | 7 | setjmp-longjmp support is enabled by default in Emscripten. This is controlled 8 | by the ``SUPPORT_LONGJMP`` setting, which can take these values: 9 | 10 | * ``emscripten``: JavaScript-based support 11 | * ``wasm``: WebAssembly exception handling-based support 12 | * 0: No support 13 | * 1: Default support, depending on the exception mode. ``wasm`` if ``-fwasm-exceptions`` is used, ``emscripten`` otherwise. 14 | 15 | If :ref:`native Wasm exceptions ` 16 | are used, ``SUPPORT_LONGJMP`` defaults to ``wasm``, and if :ref:`JavaScript-based 17 | exceptions ` are used or no exception 18 | support is used, it defaults to ``emscripten``. 19 | 20 | ``setjmp`` saves information about the calling environment into a buffer, and 21 | ``longjmp`` transfers the control back to the point where ``setjmp`` was called 22 | by using the buffer. ``longjmp``'s call stack should contain the function from 23 | which ``setjmp`` was called. 24 | 25 | Emscripten's support has a restriction that indirect calls to ``setjmp`` are not 26 | supported. For example, the below does not work: 27 | 28 | .. code-block:: c 29 | 30 | jmp_buf env; 31 | int (*fp)(jmp_buf) = setjmp; 32 | fp(env); // Doesn't work 33 | 34 | 35 | JavaScript-based setjmp-longjmp Support 36 | ======================================= 37 | 38 | In this mode, Emscripten emulates setjmp-longjmp using JavaScript. This option 39 | is set by adding ``-sSUPPORT_LONGJMP=emscripten`` to the command line, but this 40 | is currently enabled by default. 41 | 42 | Note that this option can have relatively high overhead in terms of code size, 43 | but it will work on all JavaScript engines with WebAssembly support, even if 44 | they do not yet support the `new WebAssembly exception handling proposal 45 | `_. 46 | 47 | 48 | WebAssembly Exception Handling-based setjmp-longjmp Support 49 | =========================================================== 50 | 51 | Alternatively, you can opt-in to the new support using the `WebAssembly 52 | exception handling 53 | `_ 54 | proposal. To enable it, pass ``-sSUPPORT_LONGJMP=wasm`` at both compile time and 55 | link time. 56 | 57 | This option leverages a new feature that brings built-in instructions for 58 | throwing and catching exceptions to WebAssembly. As a result, it can reduce code 59 | size and performance overhead compared to the JavaScript-based implementation. 60 | This option is currently supported in several major web browsers, but `may not 61 | be supported in all WebAssembly engines yet 62 | `_. 63 | 64 | 65 | .. _using-exceptions-and-setjmp-longjmp-together: 66 | 67 | Using Exceptions and setjmp-longjmp Together 68 | ============================================ 69 | 70 | We also have two kinds of :ref:`exception handling support `: 71 | JavaScript-based support and the new WebAssembly EH-based support. Our 72 | setjmp-longjmp support use the same mechanisms. Because of that, you should use 73 | the same kind of EH and setjmp-longjmp support when using exceptions and 74 | setjmp-longjmp together. 75 | 76 | For example, to use the JavaScript-based EH and setjmp-longjmp support together: 77 | 78 | .. code-block:: bash 79 | 80 | em++ -fexceptions test.cpp -o test.js 81 | 82 | ``-sSUPPORT_LONGJMP``, which defaults to ``emscripten`` or ``wasm`` depending on 83 | the exception mode, is enabled by default, so you don't need to pass it 84 | explicitly. 85 | 86 | To use the WebAssembly EH and setjmp-longjmp support together: 87 | 88 | .. code-block:: bash 89 | 90 | em++ -fwasm-exceptions -sSUPPORT_LONGJMP=wasm test.cpp -o test.js 91 | 92 | There is one specific restriction for using WebAssembly EH-based support for 93 | exceptions and setjmp-longjmp at the same time. You cannot call ``setjmp`` 94 | within a C++ ``catch`` clause. For example, the following will error out during 95 | compile time: 96 | 97 | .. code-block:: cpp 98 | 99 | try { 100 | ... 101 | catch (int n) { 102 | setjmp(buf); // Doesn't work 103 | } 104 | 105 | Calling ``setjmp`` within a ``try`` clause is fine. Calling another user 106 | function that calls ``setjmp`` within a ``catch`` clause is also fine. 107 | 108 | .. code-block:: cpp 109 | 110 | try { 111 | setjmp(buf); // Works 112 | catch (int n) { 113 | ... 114 | } 115 | 116 | try { 117 | ... 118 | } catch (int n) { 119 | function_that_calls_setjmp(); // Works 120 | } 121 | -------------------------------------------------------------------------------- /_sources/docs/site/index.rst.txt: -------------------------------------------------------------------------------- 1 | .. _site-links-index: 2 | 3 | ========== 4 | Site Links 5 | ========== 6 | 7 | This section contains articles that are specific to the site, or which do not belong in any other category. 8 | 9 | .. COMMENT (not rendered):: This isn't actually displayed anywhere, except on the documentation home. In the main sidebar the link is to the "About" document below (which is most important) and the glossary is not shown. This is intentional. 10 | 11 | 12 | .. toctree:: 13 | :maxdepth: 1 14 | 15 | about 16 | glossary 17 | 18 | -------------------------------------------------------------------------------- /_sources/docs/site/index.txt: -------------------------------------------------------------------------------- 1 | .. _site-links-index: 2 | 3 | ========== 4 | Site Links 5 | ========== 6 | 7 | This section contains articles that are specific to the site, or which do not belong in any other category. 8 | 9 | .. COMMENT (not rendered):: This isn't actually displayed anywhere, except on the documentation home. In the main sidebar the link is to the "About" document below (which is most important) and the glossary is not shown. This is intentional. 10 | 11 | 12 | .. toctree:: 13 | :maxdepth: 1 14 | 15 | about 16 | glossary 17 | 18 | -------------------------------------------------------------------------------- /_sources/docs/tools_reference/emcmdprompt.rst.txt: -------------------------------------------------------------------------------- 1 | .. _emcmdprompt: 2 | 3 | =================================================== 4 | Emscripten Windows Command Prompt (emcmdprompt.bat) 5 | =================================================== 6 | 7 | The *Emscripten Command Prompt* is used to call Emscripten tools from the command line on Windows. 8 | 9 | The prompt can be launched from the file system by locating and opening the file **emcmdprompt.bat**. 10 | 11 | .. note:: The *Emscripten Command Prompt* is configured with the correct system paths and settings to point to the :term:`active ` Emscripten tools. From within the prompt you can call :ref:`emsdk ` to change the current SDK or tools. 12 | 13 | .. _emcmdprompt-command-line-syntax: 14 | 15 | Command line syntax 16 | ============================================ 17 | 18 | The tool is not *intended* to be run from an existing command line prompt. 19 | 20 | However, if **emcmdprompt.bat** is called on the command line, a nested Emscripten command prompt is spawned within the current prompt (note that this is not necessarily obvious). You can then use this prompt to access the SDK tools. To exit the nested command prompt, type **exit** and then press the **Enter** key. 21 | -------------------------------------------------------------------------------- /_sources/docs/tools_reference/emcmdprompt.txt: -------------------------------------------------------------------------------- 1 | .. _emcmdprompt: 2 | 3 | =================================================== 4 | Emscripten Windows Command Prompt (emcmdprompt.bat) 5 | =================================================== 6 | 7 | The *Emscripten Command Prompt* is used to call Emscripten tools from the command line on Windows. 8 | 9 | The prompt can be launched from the file system by locating and opening the file **emcmdprompt.bat**. 10 | 11 | .. note:: The *Emscripten Command Prompt* is configured with the correct system paths and settings to point to the :term:`active ` Emscripten tools. From within the prompt you can call :ref:`emsdk ` to change the current SDK or tools. 12 | 13 | .. _emcmdprompt-command-line-syntax: 14 | 15 | Command line syntax 16 | ============================================ 17 | 18 | The tool is not *intended* to be run from an existing command line prompt. 19 | 20 | However, if **emcmdprompt.bat** is called on the command line, a nested Emscripten command prompt is spawned within the current prompt (note that this is not necessarily obvious). You can then use this prompt to access the SDK tools. To exit the nested command prompt, type **exit** and then press the **Enter** key. 21 | -------------------------------------------------------------------------------- /_sources/docs/tools_reference/index.rst.txt: -------------------------------------------------------------------------------- 1 | .. _tools-reference: 2 | 3 | =============== 4 | Tools Reference 5 | =============== 6 | 7 | This section provides reference for the main tools in the :ref:`Emscripten toolchain `: 8 | 9 | - :ref:`emccdoc` 10 | *Emcc* is used to call the Emscripten compiler from the command line. It is effectively a drop-in replacement for a standard compiler like *gcc* or *clang*. 11 | 12 | - :ref:`emsdk`: 13 | *Emsdk* is used to perform all SDK maintenance. You can use it to download, install, activate, and remove SDKs and tools, and even to build and use the latest compiler from source on GitHub. 14 | 15 | - :ref:`emcmdprompt` 16 | This prompt is used to call *Emscripten* from the command line on Windows. It is configured with the correct system paths and settings to point to the active Emscripten SDK/tools. 17 | 18 | 19 | 20 | .. toctree:: 21 | :hidden: 22 | 23 | emsdk 24 | emcc 25 | emcmdprompt 26 | settings_reference 27 | -------------------------------------------------------------------------------- /_sources/docs/tools_reference/index.txt: -------------------------------------------------------------------------------- 1 | .. _tools-reference: 2 | 3 | =============== 4 | Tools Reference 5 | =============== 6 | 7 | This section provides reference for the main tools in the :ref:`Emscripten toolchain `: 8 | 9 | - :ref:`emccdoc` 10 | *Emcc* is used to call the Emscripten compiler from the command line. It is effectively a drop-in replacement for a standard compiler like *gcc* or *clang*. 11 | 12 | - :ref:`emsdk`: 13 | *Emsdk* is used to perform all SDK maintenance. You can use it to download, install, activate, and remove SDKs and tools, and even to build and use the latest compiler from source on GitHub. 14 | 15 | - :ref:`emcmdprompt` 16 | This prompt is used to call *Emscripten* from the command line on Windows. It is configured with the correct system paths and settings to point to the active Emscripten SDK/tools. 17 | 18 | 19 | 20 | .. toctree:: 21 | :hidden: 22 | 23 | emsdk 24 | emcc 25 | emcmdprompt 26 | 27 | -------------------------------------------------------------------------------- /_sources/index.rst.txt: -------------------------------------------------------------------------------- 1 | .. title:: Main 2 | 3 | .. _home-page: 4 | 5 | .. only:: sdkbuild 6 | 7 | .. admonition:: Welcome to Emscripten SDK |release| 8 | 9 | This documentation contains everything you need to :ref:`start developing ` with the Emscripten SDK. 10 | 11 | .. raw:: html 12 | :file: home_page_layout.html 13 | 14 | 15 | ----- 16 | 17 | .. toctree:: 18 | :hidden: 19 | 20 | docs/introducing_emscripten/index 21 | docs/getting_started/index 22 | docs/compiling/index 23 | docs/porting/index 24 | docs/api_reference/index 25 | docs/tools_reference/index 26 | docs/optimizing/Optimizing-Code 27 | docs/optimizing/Optimizing-WebGL 28 | docs/debugging/Sanitizers 29 | docs/building_from_source/index 30 | docs/contributing/index 31 | docs/optimizing/Profiling-Toolchain 32 | 33 | docs/site/about 34 | genindex 35 | -------------------------------------------------------------------------------- /_sources/index.txt: -------------------------------------------------------------------------------- 1 | .. title:: Main 2 | 3 | .. _home-page: 4 | 5 | .. only:: sdkbuild 6 | 7 | .. admonition:: Welcome to Emscripten SDK |release| 8 | 9 | This documentation contains everything you need to :ref:`start developing ` with the Emscripten SDK. 10 | 11 | .. raw:: html 12 | :file: home_page_layout.html 13 | 14 | 15 | ----- 16 | 17 | .. toctree:: 18 | :hidden: 19 | 20 | docs/introducing_emscripten/index 21 | docs/getting_started/index 22 | docs/compiling/index 23 | docs/porting/index 24 | docs/api_reference/index 25 | docs/tools_reference/index 26 | docs/optimizing/Optimizing-Code 27 | docs/optimizing/Optimizing-WebGL 28 | docs/debugging/CyberDWARF 29 | docs/debugging/Sanitizers 30 | docs/building_from_source/index 31 | docs/contributing/index 32 | docs/optimizing/Profiling-Toolchain 33 | 34 | docs/site/about 35 | -------------------------------------------------------------------------------- /_static/Emscripten_logo_full.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/Emscripten_logo_full.png -------------------------------------------------------------------------------- /_static/_sphinx_javascript_frameworks_compat.js: -------------------------------------------------------------------------------- 1 | /* Compatability shim for jQuery and underscores.js. 2 | * 3 | * Copyright Sphinx contributors 4 | * Released under the two clause BSD licence 5 | */ 6 | 7 | /** 8 | * small helper function to urldecode strings 9 | * 10 | * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL 11 | */ 12 | jQuery.urldecode = function(x) { 13 | if (!x) { 14 | return x 15 | } 16 | return decodeURIComponent(x.replace(/\+/g, ' ')); 17 | }; 18 | 19 | /** 20 | * small helper function to urlencode strings 21 | */ 22 | jQuery.urlencode = encodeURIComponent; 23 | 24 | /** 25 | * This function returns the parsed url parameters of the 26 | * current request. Multiple values per key are supported, 27 | * it will always return arrays of strings for the value parts. 28 | */ 29 | jQuery.getQueryParameters = function(s) { 30 | if (typeof s === 'undefined') 31 | s = document.location.search; 32 | var parts = s.substr(s.indexOf('?') + 1).split('&'); 33 | var result = {}; 34 | for (var i = 0; i < parts.length; i++) { 35 | var tmp = parts[i].split('=', 2); 36 | var key = jQuery.urldecode(tmp[0]); 37 | var value = jQuery.urldecode(tmp[1]); 38 | if (key in result) 39 | result[key].push(value); 40 | else 41 | result[key] = [value]; 42 | } 43 | return result; 44 | }; 45 | 46 | /** 47 | * highlight a given string on a jquery object by wrapping it in 48 | * span elements with the given class name. 49 | */ 50 | jQuery.fn.highlightText = function(text, className) { 51 | function highlight(node, addItems) { 52 | if (node.nodeType === 3) { 53 | var val = node.nodeValue; 54 | var pos = val.toLowerCase().indexOf(text); 55 | if (pos >= 0 && 56 | !jQuery(node.parentNode).hasClass(className) && 57 | !jQuery(node.parentNode).hasClass("nohighlight")) { 58 | var span; 59 | var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg"); 60 | if (isInSVG) { 61 | span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); 62 | } else { 63 | span = document.createElement("span"); 64 | span.className = className; 65 | } 66 | span.appendChild(document.createTextNode(val.substr(pos, text.length))); 67 | node.parentNode.insertBefore(span, node.parentNode.insertBefore( 68 | document.createTextNode(val.substr(pos + text.length)), 69 | node.nextSibling)); 70 | node.nodeValue = val.substr(0, pos); 71 | if (isInSVG) { 72 | var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect"); 73 | var bbox = node.parentElement.getBBox(); 74 | rect.x.baseVal.value = bbox.x; 75 | rect.y.baseVal.value = bbox.y; 76 | rect.width.baseVal.value = bbox.width; 77 | rect.height.baseVal.value = bbox.height; 78 | rect.setAttribute('class', className); 79 | addItems.push({ 80 | "parent": node.parentNode, 81 | "target": rect}); 82 | } 83 | } 84 | } 85 | else if (!jQuery(node).is("button, select, textarea")) { 86 | jQuery.each(node.childNodes, function() { 87 | highlight(this, addItems); 88 | }); 89 | } 90 | } 91 | var addItems = []; 92 | var result = this.each(function() { 93 | highlight(this, addItems); 94 | }); 95 | for (var i = 0; i < addItems.length; ++i) { 96 | jQuery(addItems[i].parent).before(addItems[i].target); 97 | } 98 | return result; 99 | }; 100 | 101 | /* 102 | * backward compatibility for jQuery.browser 103 | * This will be supported until firefox bug is fixed. 104 | */ 105 | if (!jQuery.browser) { 106 | jQuery.uaMatch = function(ua) { 107 | ua = ua.toLowerCase(); 108 | 109 | var match = /(chrome)[ \/]([\w.]+)/.exec(ua) || 110 | /(webkit)[ \/]([\w.]+)/.exec(ua) || 111 | /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) || 112 | /(msie) ([\w.]+)/.exec(ua) || 113 | ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) || 114 | []; 115 | 116 | return { 117 | browser: match[ 1 ] || "", 118 | version: match[ 2 ] || "0" 119 | }; 120 | }; 121 | jQuery.browser = {}; 122 | jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true; 123 | } 124 | -------------------------------------------------------------------------------- /_static/ajax-loader.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/ajax-loader.gif -------------------------------------------------------------------------------- /_static/comment-bright.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/comment-bright.png -------------------------------------------------------------------------------- /_static/comment-close.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/comment-close.png -------------------------------------------------------------------------------- /_static/comment.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/comment.png -------------------------------------------------------------------------------- /_static/css/badge_only.css: -------------------------------------------------------------------------------- 1 | .clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-style:normal;font-weight:400;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#FontAwesome) format("svg")}.fa:before{font-family:FontAwesome;font-style:normal;font-weight:400;line-height:1}.fa:before,a .fa{text-decoration:inherit}.fa:before,a .fa,li .fa{display:inline-block}li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before,.icon-book:before{content:"\f02d"}.fa-caret-down:before,.icon-caret-down:before{content:"\f0d7"}.fa-caret-up:before,.icon-caret-up:before{content:"\f0d8"}.fa-caret-left:before,.icon-caret-left:before{content:"\f0d9"}.fa-caret-right:before,.icon-caret-right:before{content:"\f0da"}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60}.rst-versions .rst-current-version:after{clear:both;content:"";display:block}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions .rst-other-versions .rtd-current-item{font-weight:700}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}#flyout-search-form{padding:6px} -------------------------------------------------------------------------------- /_static/css/fonts/Roboto-Slab-Bold.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/css/fonts/Roboto-Slab-Bold.woff -------------------------------------------------------------------------------- /_static/css/fonts/Roboto-Slab-Bold.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/css/fonts/Roboto-Slab-Bold.woff2 -------------------------------------------------------------------------------- /_static/css/fonts/Roboto-Slab-Regular.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/css/fonts/Roboto-Slab-Regular.woff -------------------------------------------------------------------------------- /_static/css/fonts/Roboto-Slab-Regular.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/css/fonts/Roboto-Slab-Regular.woff2 -------------------------------------------------------------------------------- /_static/css/fonts/fontawesome-webfont.eot: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/css/fonts/fontawesome-webfont.eot -------------------------------------------------------------------------------- /_static/css/fonts/fontawesome-webfont.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/css/fonts/fontawesome-webfont.ttf -------------------------------------------------------------------------------- /_static/css/fonts/fontawesome-webfont.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/css/fonts/fontawesome-webfont.woff -------------------------------------------------------------------------------- /_static/css/fonts/fontawesome-webfont.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/css/fonts/fontawesome-webfont.woff2 -------------------------------------------------------------------------------- /_static/css/fonts/lato-bold-italic.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/css/fonts/lato-bold-italic.woff -------------------------------------------------------------------------------- /_static/css/fonts/lato-bold-italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/css/fonts/lato-bold-italic.woff2 -------------------------------------------------------------------------------- /_static/css/fonts/lato-bold.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/css/fonts/lato-bold.woff -------------------------------------------------------------------------------- /_static/css/fonts/lato-bold.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/css/fonts/lato-bold.woff2 -------------------------------------------------------------------------------- /_static/css/fonts/lato-normal-italic.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/css/fonts/lato-normal-italic.woff -------------------------------------------------------------------------------- /_static/css/fonts/lato-normal-italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/css/fonts/lato-normal-italic.woff2 -------------------------------------------------------------------------------- /_static/css/fonts/lato-normal.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/css/fonts/lato-normal.woff -------------------------------------------------------------------------------- /_static/css/fonts/lato-normal.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/css/fonts/lato-normal.woff2 -------------------------------------------------------------------------------- /_static/doctools.js: -------------------------------------------------------------------------------- 1 | /* 2 | * doctools.js 3 | * ~~~~~~~~~~~ 4 | * 5 | * Base JavaScript utilities for all Sphinx HTML documentation. 6 | * 7 | * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. 8 | * :license: BSD, see LICENSE for details. 9 | * 10 | */ 11 | "use strict"; 12 | 13 | const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([ 14 | "TEXTAREA", 15 | "INPUT", 16 | "SELECT", 17 | "BUTTON", 18 | ]); 19 | 20 | const _ready = (callback) => { 21 | if (document.readyState !== "loading") { 22 | callback(); 23 | } else { 24 | document.addEventListener("DOMContentLoaded", callback); 25 | } 26 | }; 27 | 28 | /** 29 | * Small JavaScript module for the documentation. 30 | */ 31 | const Documentation = { 32 | init: () => { 33 | Documentation.initDomainIndexTable(); 34 | Documentation.initOnKeyListeners(); 35 | }, 36 | 37 | /** 38 | * i18n support 39 | */ 40 | TRANSLATIONS: {}, 41 | PLURAL_EXPR: (n) => (n === 1 ? 0 : 1), 42 | LOCALE: "unknown", 43 | 44 | // gettext and ngettext don't access this so that the functions 45 | // can safely bound to a different name (_ = Documentation.gettext) 46 | gettext: (string) => { 47 | const translated = Documentation.TRANSLATIONS[string]; 48 | switch (typeof translated) { 49 | case "undefined": 50 | return string; // no translation 51 | case "string": 52 | return translated; // translation exists 53 | default: 54 | return translated[0]; // (singular, plural) translation tuple exists 55 | } 56 | }, 57 | 58 | ngettext: (singular, plural, n) => { 59 | const translated = Documentation.TRANSLATIONS[singular]; 60 | if (typeof translated !== "undefined") 61 | return translated[Documentation.PLURAL_EXPR(n)]; 62 | return n === 1 ? singular : plural; 63 | }, 64 | 65 | addTranslations: (catalog) => { 66 | Object.assign(Documentation.TRANSLATIONS, catalog.messages); 67 | Documentation.PLURAL_EXPR = new Function( 68 | "n", 69 | `return (${catalog.plural_expr})` 70 | ); 71 | Documentation.LOCALE = catalog.locale; 72 | }, 73 | 74 | /** 75 | * helper function to focus on search bar 76 | */ 77 | focusSearchBar: () => { 78 | document.querySelectorAll("input[name=q]")[0]?.focus(); 79 | }, 80 | 81 | /** 82 | * Initialise the domain index toggle buttons 83 | */ 84 | initDomainIndexTable: () => { 85 | const toggler = (el) => { 86 | const idNumber = el.id.substr(7); 87 | const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`); 88 | if (el.src.substr(-9) === "minus.png") { 89 | el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`; 90 | toggledRows.forEach((el) => (el.style.display = "none")); 91 | } else { 92 | el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`; 93 | toggledRows.forEach((el) => (el.style.display = "")); 94 | } 95 | }; 96 | 97 | const togglerElements = document.querySelectorAll("img.toggler"); 98 | togglerElements.forEach((el) => 99 | el.addEventListener("click", (event) => toggler(event.currentTarget)) 100 | ); 101 | togglerElements.forEach((el) => (el.style.display = "")); 102 | if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler); 103 | }, 104 | 105 | initOnKeyListeners: () => { 106 | // only install a listener if it is really needed 107 | if ( 108 | !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS && 109 | !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS 110 | ) 111 | return; 112 | 113 | document.addEventListener("keydown", (event) => { 114 | // bail for input elements 115 | if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; 116 | // bail with special keys 117 | if (event.altKey || event.ctrlKey || event.metaKey) return; 118 | 119 | if (!event.shiftKey) { 120 | switch (event.key) { 121 | case "ArrowLeft": 122 | if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; 123 | 124 | const prevLink = document.querySelector('link[rel="prev"]'); 125 | if (prevLink && prevLink.href) { 126 | window.location.href = prevLink.href; 127 | event.preventDefault(); 128 | } 129 | break; 130 | case "ArrowRight": 131 | if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; 132 | 133 | const nextLink = document.querySelector('link[rel="next"]'); 134 | if (nextLink && nextLink.href) { 135 | window.location.href = nextLink.href; 136 | event.preventDefault(); 137 | } 138 | break; 139 | } 140 | } 141 | 142 | // some keyboard layouts may need Shift to get / 143 | switch (event.key) { 144 | case "/": 145 | if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break; 146 | Documentation.focusSearchBar(); 147 | event.preventDefault(); 148 | } 149 | }); 150 | }, 151 | }; 152 | 153 | // quick alias for translations 154 | const _ = Documentation.gettext; 155 | 156 | _ready(Documentation.init); 157 | -------------------------------------------------------------------------------- /_static/documentation_options.js: -------------------------------------------------------------------------------- 1 | var DOCUMENTATION_OPTIONS = { 2 | URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'), 3 | VERSION: '4.0.9-git (dev)', 4 | LANGUAGE: 'en', 5 | COLLAPSE_INDEX: false, 6 | BUILDER: 'html', 7 | FILE_SUFFIX: '.html', 8 | LINK_SUFFIX: '.html', 9 | HAS_SOURCE: true, 10 | SOURCELINK_SUFFIX: '.txt', 11 | NAVIGATION_WITH_KEYS: false, 12 | SHOW_SEARCH_SUMMARY: true, 13 | ENABLE_SEARCH_SHORTCUTS: true, 14 | }; -------------------------------------------------------------------------------- /_static/down-pressed.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/down-pressed.png -------------------------------------------------------------------------------- /_static/down.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/down.png -------------------------------------------------------------------------------- /_static/emscripten.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/emscripten.ico -------------------------------------------------------------------------------- /_static/file.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/file.png -------------------------------------------------------------------------------- /_static/fonts/fontawesome-webfont.eot: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/fonts/fontawesome-webfont.eot -------------------------------------------------------------------------------- /_static/fonts/fontawesome-webfont.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/fonts/fontawesome-webfont.ttf -------------------------------------------------------------------------------- /_static/fonts/fontawesome-webfont.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kripken/emscripten-site/531ef9e75ccf7b6387bd5939d96233de21cf0557/_static/fonts/fontawesome-webfont.woff -------------------------------------------------------------------------------- /_static/js/theme.js: -------------------------------------------------------------------------------- 1 | !function(n){var e={};function t(i){if(e[i])return e[i].exports;var o=e[i]={i:i,l:!1,exports:{}};return n[i].call(o.exports,o,o.exports,t),o.l=!0,o.exports}t.m=n,t.c=e,t.d=function(n,e,i){t.o(n,e)||Object.defineProperty(n,e,{enumerable:!0,get:i})},t.r=function(n){"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(n,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(n,"__esModule",{value:!0})},t.t=function(n,e){if(1&e&&(n=t(n)),8&e)return n;if(4&e&&"object"==typeof n&&n&&n.__esModule)return n;var i=Object.create(null);if(t.r(i),Object.defineProperty(i,"default",{enumerable:!0,value:n}),2&e&&"string"!=typeof n)for(var o in n)t.d(i,o,function(e){return n[e]}.bind(null,o));return i},t.n=function(n){var e=n&&n.__esModule?function(){return n.default}:function(){return n};return t.d(e,"a",e),e},t.o=function(n,e){return Object.prototype.hasOwnProperty.call(n,e)},t.p="",t(t.s=0)}([function(n,e,t){t(1),n.exports=t(3)},function(n,e,t){(function(){var e="undefined"!=typeof window?window.jQuery:t(2);n.exports.ThemeNav={navBar:null,win:null,winScroll:!1,winResize:!1,linkScroll:!1,winPosition:0,winHeight:null,docHeight:null,isRunning:!1,enable:function(n){var t=this;void 0===n&&(n=!0),t.isRunning||(t.isRunning=!0,e((function(e){t.init(e),t.reset(),t.win.on("hashchange",t.reset),n&&t.win.on("scroll",(function(){t.linkScroll||t.winScroll||(t.winScroll=!0,requestAnimationFrame((function(){t.onScroll()})))})),t.win.on("resize",(function(){t.winResize||(t.winResize=!0,requestAnimationFrame((function(){t.onResize()})))})),t.onResize()})))},enableSticky:function(){this.enable(!0)},init:function(n){n(document);var e=this;this.navBar=n("div.wy-side-scroll:first"),this.win=n(window),n(document).on("click","[data-toggle='wy-nav-top']",(function(){n("[data-toggle='wy-nav-shift']").toggleClass("shift"),n("[data-toggle='rst-versions']").toggleClass("shift")})).on("click",".wy-menu-vertical .current ul li a",(function(){var t=n(this);n("[data-toggle='wy-nav-shift']").removeClass("shift"),n("[data-toggle='rst-versions']").toggleClass("shift"),e.toggleCurrent(t),e.hashChange()})).on("click","[data-toggle='rst-current-version']",(function(){n("[data-toggle='rst-versions']").toggleClass("shift-up")})),n("table.docutils:not(.field-list,.footnote,.citation)").wrap("
"),n("table.docutils.footnote").wrap("
"),n("table.docutils.citation").wrap("
"),n(".wy-menu-vertical ul").not(".simple").siblings("a").each((function(){var t=n(this);expand=n(''),expand.on("click",(function(n){return e.toggleCurrent(t),n.stopPropagation(),!1})),t.prepend(expand)}))},reset:function(){var n=encodeURI(window.location.hash)||"#";try{var e=$(".wy-menu-vertical"),t=e.find('[href="'+n+'"]');if(0===t.length){var i=$('.document [id="'+n.substring(1)+'"]').closest("div.section");0===(t=e.find('[href="#'+i.attr("id")+'"]')).length&&(t=e.find('[href="#"]'))}if(t.length>0){$(".wy-menu-vertical .current").removeClass("current").attr("aria-expanded","false"),t.addClass("current").attr("aria-expanded","true"),t.closest("li.toctree-l1").parent().addClass("current").attr("aria-expanded","true");for(let n=1;n<=10;n++)t.closest("li.toctree-l"+n).addClass("current").attr("aria-expanded","true");/*t[0].scrollIntoView()*/}}catch(n){console.log("Error expanding nav for anchor",n)}},onScroll:function(){this.winScroll=!1;var n=this.win.scrollTop(),e=n+this.winHeight,t=this.navBar.scrollTop()+(n-this.winPosition);n<0||e>this.docHeight||(this.navBar.scrollTop(t),this.winPosition=n)},onResize:function(){this.winResize=!1,this.winHeight=this.win.height(),this.docHeight=$(document).height()},hashChange:function(){this.linkScroll=!0,this.win.one("hashchange",(function(){this.linkScroll=!1}))},toggleCurrent:function(n){var e=n.closest("li");e.siblings("li.current").removeClass("current").attr("aria-expanded","false"),e.siblings().find("li.current").removeClass("current").attr("aria-expanded","false");var t=e.find("> ul li");t.length&&(t.removeClass("current").attr("aria-expanded","false"),e.toggleClass("current").attr("aria-expanded",(function(n,e){return"true"==e?"false":"true"})))}},"undefined"!=typeof window&&(window.SphinxRtdTheme={Navigation:n.exports.ThemeNav,StickyNav:n.exports.ThemeNav}),function(){for(var n=0,e=["ms","moz","webkit","o"],t=0;t