EMCC(1) User Commands EMCC(1)
NAME
emcc - emscripten compiler for WASM and JavaScript like gcc or clang
DESCRIPTION
Emscripten Compiler Frontend (emcc) ***********************************
The Emscripten Compiler Frontend ("emcc") is used to call the Em-
scripten compiler from the command line. It is effectively a drop-in
replacement for a standard compiler like *gcc* or *clang*.
Command line syntax ===================
emcc [options] file...
(Note that you will need "./emcc" if you want to run emcc from your
current directory.)
The input file(s) can be either source code files that *Clang* can han-
dle (C or C++), object files (produced by *emcc -c*), or LLVM assembly
files.
Arguments ---------
Most clang options will work, as will gcc options, for example:
# Display this information emcc --help
# Display compiler version information emcc --version
To see the full list of *Clang* options supported on the version of
*Clang* used by Emscripten, run "clang --help".
Options that are modified or new in *emcc* are listed below:
"-O0"
[compile+link] No optimizations (default). This is the recom-
mended setting for starting to port a project, as it includes
various assertions.
This and other optimization settings are meaningful both during
compile and during link. During compile it affects LLVM opti-
mizations, and during link it affects final optimization of the
code in Binaryen as well as optimization of the JS. (For fast
incremental builds "-O0" is best, while for release you should
link with something higher.)
"-O1"
[compile+link] Simple optimizations. During the compile step
these include LLVM "-O1" optimizations. During the link step
this does not include various runtime assertions in JS that
*-O0* would do.
"-O2"
[compile+link] Like "-O1", but enables more optimizations. Dur-
ing link this will also enable various JavaScript optimizations.
Note:
These JavaScript optimizations can reduce code size by removing
things that the compiler does not see being used, in particular,
parts of the runtime may be stripped if they are not exported on
the "Module" object. The compiler is aware of code in --pre-js
and --post-js, so you can safely use the runtime from there.
Alternatively, you can use "EXPORTED_RUNTIME_METHODS", see
src/settings.js.
"-O3"
[compile+link] Like "-O2", but with additional optimizations
that may take longer to run.
Note:
This is a good setting for a release build.
"-Os"
[compile+link] Like "-O3", but focuses more on code size (and
may make tradeoffs with speed). This can affect both wasm and
JavaScript.
"-Oz"
[compile+link] Like "-Os", but reduces code size even further,
and may take longer to run. This can affect both wasm and Java-
Script.
Note:
For more tips on optimizing your code, see Optimizing Code.
"-s OPTION[=VALUE]"
[different OPTIONs affect at different stages, most at link
time] Emscripten build options. For the available options, see
src/settings.js.
Note:
You can prefix boolean options with "NO_" to reverse them. For
example, "-s EXIT_RUNTIME=1" is the same as "-s NO_EXIT_RUN-
TIME=0".
Note:
If no value is specifed it will default to "1".
Note:
Lists can be specified as comma separated strings:
-s EXPORTED_FUNCTIONS=foo,bar
Note:
We also support older list formats that involve more quoting.
Lists can be specified with or without quotes around each ele-
ment and with or without brackets around the list. For example,
all the following are equivalent:
-s EXPORTED_FUNCTIONS="foo","bar"
-s EXPORTED_FUNCTIONS=["foo","bar"]
-s EXPORTED_FUNCTIONS=[foo,bar]
Note:
For lists that include brackets or quote, you need quotation
marks (") around the list in most shells (to avoid errors being
raised). Two examples are shown below:
-s EXPORTED_FUNCTIONS="['liblib.so']"
-s "EXPORTED_FUNCTIONS=['liblib.so']"
You can also specify that the value of an option will be read
from a file. For example, the following will set "EXPORTED_FUNC-
TIONS" based on the contents of the file at **path/to/file**.
-s EXPORTED_FUNCTIONS=@/path/to/file
Note:
* In this case the file should contain a list of symbols, one
per
line.
For legacy use cases JSON-formatted files are also
supported: e.g. "["_func1", "func2"]".
* The specified file path must be absolute, not relative.
Note:
Options can be specified as a single argument without a space
between the "-s" and option name. e.g. "-sFOO=1".
"-g"
[compile+link] Preserve debug information.
* When compiling to object files, this is the same as in *Clang*
and *gcc*, it adds DWARF debug information to the object files.
* When linking, this is equivalent to -g3.
"-gseparate-dwarf[=FILENAME]"
[same as -g3 if passed at compile time, otherwise applies at
link] Preserve debug information, but in a separate file on the
side. This is the same as "-g", but the main file will contain
no debug info. Instead, debug info will be present in a file on
the side, in "FILENAME" if provided, otherwise the same as the
wasm file but with suffix ".debug.wasm". While the main file
contains no debug info, it does contain a URL to where the debug
file is, so that devtools can find it. You can use "-s SEPA-
RATE_DWARF_URL=URL" to customize that location (this is useful
if you want to host it on a different server, for example).
"-gsource-map"
When linking, generate a source map using LLVM debug information
(which must be present in object files, i.e., they should have
been compiled with "-g").
"-g<level>"
[compile+link] Controls the level of debuggability. Each level
builds on the previous one:
* "-g0": Make no effort to keep code debuggable.
* "-g1": When linking, preserve whitespace in JavaScript.
* "-g2": When linking, preserve function names in compiled code.
* "-g3": When compiling to object files, keep debug info,
including JS whitespace, function names, and LLVM debug info
(DWARF) if any (this is the same as -g).
"--profiling"
[same as -g2 if passed at compile time, otherwise applies at
link] Use reasonable defaults when emitting JavaScript to make
the build readable but still useful for profiling. This sets
"-g2" (preserve whitespace and function names) and may also en-
able optimizations that affect performance and otherwise might
not be performed in "-g2".
"--profiling-funcs"
[link] Preserve function names in profiling, but otherwise
minify whitespace and names as we normally do in optimized
builds. This is useful if you want to look at profiler results
based on function names, but do *not* intend to read the emitted
code.
"--tracing"
[link] Enable the Emscripten Tracing API.
"--emit-symbol-map"
[link] Save a map file between function indexes in the wasm and
function names. By storing the names on a file on the side, you
can avoid shipping the names, and can still reconstruct meaning-
ful stack traces by translating the indexes back to the names.
Note:
When used with "-s WASM=2", two symbol files are created.
"[name].js.symbols" (with WASM symbols) and "[name].wasm.js.sym-
bols" (with ASM.js symbols)
"-flto"
[compile+link] Enables link-time optimizations (LTO).
"--closure 0|1|2"
[link] Runs the *Closure Compiler*. Possible values are:
* "0": No closure compiler (default in "-O2" and below).
* "1": Run closure compiler. This greatly reduces the size of
the support JavaScript code (everything but the WebAssembly or
asm.js). Note that this increases compile time significantly.
* "2": Run closure compiler on *all* the emitted code, even on
**asm.js** output in **asm.js** mode. This can further reduce
code size, but does prevent a significant amount of **asm.js**
optimizations, so it is not recommended unless you want to re-
duce code size at all costs.
Note:
* Consider using "-s MODULARIZE=1" when using closure, as it
minifies globals to names that might conflict with others in the
global scope. "MODULARIZE" puts all the output into a function
(see "src/settings.js").
* Closure will minify the name of *Module* itself, by default!
Using "MODULARIZE" will solve that as well. Another solution is
to make sure a global variable called *Module* already exists
before the closure-compiled code runs, because then it will re-
use that variable.
* If closure compiler hits an out-of-memory, try adjusting
"JAVA_HEAP_SIZE" in the environment (for example, to 4096m for
4GB).
* Closure is only run if JavaScript opts are being done ("-O2"
or
above).
"--closure-args=<args>"
[link] Pass arguments to the *Closure compiler*. This is an al-
ternative to "EMCC_CLOSURE_ARGS".
For example, one might want to pass an externs file to avoid
minifying JS functions defined in "--pre-js" or "--post-js"
files. To pass to Closure the "externs.js" file containing
those public APIs that should not be minified, one would add the
flag: "-- closure-args=--externs=path/to/externs.js"
"--pre-js <file>"
[link] Specify a file whose contents are added before the emit-
ted code and optimized together with it. Note that this might
not literally be the very first thing in the JS output, for ex-
ample if "MODULARIZE" is used (see "src/settings.js"). If you
want that, you can just prepend to the output from emscripten;
the benefit of "-- pre-js" is that it optimizes the code with
the rest of the emscripten output, which allows better dead code
elimination and minification, and it should only be used for
that purpose. In particular, "--pre-js" code should not alter
the main output from emscripten in ways that could confuse the
optimizer, such as using "--pre-js" + "--post-js" to put all the
output in an inner function scope (see "MODULARIZE" for that).
*--pre-js* (but not *--post-js*) is also useful for specifying
things on the "Module" object, as it appears before the JS looks
at "Module" (for example, you can define "Module['print']"
there).
"--post-js <file>"
[link] Like "--pre-js", but emits a file *after* the emitted
code.
"--extern-pre-js <file>"
[link] Specify a file whose contents are prepended to the Java-
Script output. This file is prepended to the final JavaScript
output, *after* all other work has been done, including opti-
mization, optional "MODULARIZE"-ation, instrumentation like
"SAFE_HEAP", etc. This is the same as prepending this file after
"emcc" finishes running, and is just a convenient way to do
that. (For comparison, "--pre-js" and "--post-js" optimize the
code together with everything else, keep it in the same scope if
running *MODULARIZE*, etc.).
"--extern-post-js <file>"
[link] Like "--extern-pre-js", but appends to the end.
"--embed-file <file>"
[link] Specify a file (with path) to embed inside the generated
JavaScript. The path is relative to the current directory at
compile time. If a directory is passed here, its entire contents
will be embedded.
For example, if the command includes "--embed-file
dir/file.dat", then "dir/file.dat" must exist relative to the
directory where you run *emcc*.
Note:
Embedding files is much less efficient than preloading them. You
should only use it for small files, in small numbers. Instead
use "--preload-file", which emits efficient binary data.
For more information about the "--embed-file" options, see Pack-
aging Files.
"--preload-file <name>"
[link] Specify a file to preload before running the compiled
code asynchronously. The path is relative to the current direc-
tory at compile time. If a directory is passed here, its entire
contents will be embedded.
Preloaded files are stored in **filename.data**, where **file-
name.html** is the main file you are compiling to. To run your
code, you will need both the **.html** and the **.data**.
Note:
This option is similar to --embed-file, except that it is only
relevant when generating HTML (it uses asynchronous binary
*XHRs*), or JavaScript that will be used in a web page.
*emcc* runs tools/file_packager to do the actual packaging of
embedded and preloaded files. You can run the file packager
yourself if you want (see Packaging using the file packager
tool). You should then put the output of the file packager in
an emcc "-- pre-js", so that it executes before your main com-
piled code.
For more information about the "--preload-file" options, see
Packaging Files.
"--exclude-file <name>"
[link] Files and directories to be excluded from --embed-file
and --preload-file. Wildcards (*) are supported.
"--use-preload-plugins"
[link] Tells the file packager to run preload plugins on the
files as they are loaded. This performs tasks like decoding im-
ages and audio using the browser's codecs.
"--shell-file <path>"
[link] The path name to a skeleton HTML file used when generat-
ing HTML output. The shell file used needs to have this token
inside it: "{{{ SCRIPT }}}".
Note:
* See src/shell.html and src/shell_minimal.html for examples.
* This argument is ignored if a target other than HTML is
specified using the "-o" option.
"--source-map-base <base-url>"
[link] The URL for the location where WebAssembly source maps
will be published. When this option is provided, the **.wasm**
file is updated to have a "sourceMappingURL" section. The re-
sulting URL will have format: "<base-url>" + "<wasm-file-name>"
+ ".map".
"--minify 0"
[same as -g1 if passed at compile time, otherwise applies at
link] Identical to "-g1".
"--js-transform <cmd>"
[link] Specifies a "<cmd>" to be called on the generated code
before it is optimized. This lets you modify the JavaScript, for
example adding or removing some code, in a way that those modi-
fications will be optimized together with the generated code.
"<cmd>" will be called with the file name of the generated code
as a parameter. To modify the code, you can read the original
data and then append to it or overwrite it with the modified
data.
"<cmd>" is interpreted as a space-separated list of arguments,
for example, "<cmd>" of **python processor.py** will cause a
Python script to be run.
"--bind"
[link] Links against embind library.
Deprecated: Use "-lembind"
instead.
"--ignore-dynamic-linking"
[link] Tells the compiler to ignore dynamic linking (the user
will need to manually link to the shared libraries later on).
Normally *emcc* will simply link in code from the dynamic li-
brary as though it were statically linked, which will fail if
the same dynamic library is linked more than once. With this op-
tion, dynamic linking is ignored, which allows the build system
to proceed without errors.
"--js-library <lib>"
[link] A JavaScript library to use in addition to those in Em-
scripten's core libraries (src/library_*).
"-v"
[general] Turns on verbose output.
This will print the internal sub-commands run by emscripten as
well as "-v" to *Clang*.
Tip:
"emcc -v" is a useful tool for diagnosing errors. It works with
or without other arguments.
"--check"
[general] Runs Emscripten's internal sanity checks and reports
any issues with the current configuration.
"--cache <directory>"
[general] Sets the directory to use as the Emscripten cache. The
Emscripten cache is used to store pre-built versions of "libc",
"libcxx" and other libraries.
If using this in combination with "--clear-cache", be sure to
specify this argument first.
The Emscripten cache defaults to "emscripten/cache" but can be
overridden using the "EM_CACHE" environment variable or "CACHE"
config setting.
"--clear-cache"
[general] Manually clears the cache of compiled Emscripten sys-
tem libraries (libc++, libc++abi, libc).
This is normally handled automatically, but if you update LLVM
inplace (instead of having a different directory for a new ver-
sion), the caching mechanism can get confused. Clearing the
cache can fix weird problems related to cache incompatibilities,
like *Clang* failing to link with library files. This also
clears other cached data. After the cache is cleared, this
process will exit.
By default this will also clear any download ports since the
ports directory is usually within the cache directory.
"--clear-ports"
[general] Manually clears the local copies of ports from the Em-
scripten Ports repos (sdl2, etc.). This also clears the cache,
to remove their builds.
You should only need to do this if a problem happens and you
want all ports that you use to be downloaded and built from
scratch. After this operation is complete, this process will
exit.
"--show-ports"
[general] Shows the list of available projects in the Emscripten
Ports repos. After this operation is complete, this process will
exit.
"--memory-init-file 0|1"
[link] Specifies whether to emit a separate memory initializa-
tion file.
Note:
Note that this is only relevant when *not* emitting wasm, as
wasm embeds the memory init data in the wasm binary.
Possible values are:
* "0": Do not emit a separate memory initialization file.
Instead keep the static initialization inside the generated
JavaScript as text. This is the default setting if compiling
with -O0 or -O1 link-time optimization flags.
* "1": Emit a separate memory initialization file in binary
format. This is more efficient than storing it as text inside
JavaScript, but does mean you have another file to publish. The
binary file will also be loaded asynchronously, which means
"main()" will not be called until the file is downloaded and ap-
plied; you cannot call any C functions until it arrives. This
is the default setting when compiling with -O2 or higher.
Note:
The safest way to ensure that it is safe to call C functions
(the initialisation file has loaded) is to call a notifier func-
tion from "main()".
Note:
If you assign a network request to "Module.memoryInitializerRe-
quest" (before the script runs), then it will use that request
instead of automatically starting a download for you. This is
beneficial in that you can, in your HTML, fire off a request for
the memory init file before the script actually arrives. For
this to work, the network request should be an XMLHttpRequest
with responseType set to "'arraybuffer'". (You can also put any
other object here, all it must provide is a ".response" property
containing an ArrayBuffer.)
"-Wwarn-absolute-paths"
[compile+link] Enables warnings about the use of absolute paths
in "-I" and "-L" command line directives. This is used to warn
against unintentional use of absolute paths, which is sometimes
dangerous when referring to nonportable local system headers.
"--proxy-to-worker"
[link] Runs the main application code in a worker, proxying
events to it and output from it. If emitting HTML, this emits a
**.html** file, and a separate **.js** file containing the Java-
Script to be run in a worker. If emitting JavaScript, the target
file name contains the part to be run on the main thread, while
a second **.js** file with suffix ".worker.js" will contain the
worker portion.
"--emrun"
[link] Enables the generated output to be aware of the emrun
command line tool. This allows "stdout", "stderr" and "exit(re-
turncode)" capture when running the generated application
through *emrun*. (This enables *EXIT_RUNTIME=1*, allowing normal
runtime exiting with return code passing.)
"--cpuprofiler"
[link] Embeds a simple CPU profiler onto the generated page. Use
this to perform cursory interactive performance profiling.
"--memoryprofiler"
[link] Embeds a memory allocation tracker onto the generated
page. Use this to profile the application usage of the Em-
scripten HEAP.
"--threadprofiler"
[link] Embeds a thread activity profiler onto the generated
page. Use this to profile the application usage of pthreads
when targeting multithreaded builds (-s USE_PTHREADS=1/2).
"--em-config <path>"
[general] Specifies the location of the **.emscripten** configu-
ration file. If not specified emscripten will search for ".em-
scripten" first in the emscripten directory itself, and then in
the user's home directory ("~/.emscripten"). This can be over-
ridden using the "EM_CONFIG" environment variable.
"--default-obj-ext <.ext>"
[compile] Specifies the output suffix to use when compiling with
"-c" in the absence of "-o". For example, when compiling multi-
ple sources files with "emcc -c *.c" the compiler will normally
output files with the ".o" extension, but "--default-obj-ext
.obj" can be used to instead generate files with the *.obj* ex-
tension.
"--valid-abspath <path>"
[compile+link] Note an allowed absolute path, which we should
not warn about (absolute include paths normally are warned
about, since they may refer to the local system headers etc.
which we need to avoid when cross-compiling).
"-o <target>"
[link] When linking an executable, the "target" file name exten-
sion defines the output type to be generated:
* <name> **.js** : JavaScript (+ separate **<name>.wasm** file
if emitting WebAssembly). (default)
* <name> **.mjs** : ES6 JavaScript module (+ separate
**<name>.wasm** file if emitting WebAssembly).
* <name> **.html** : HTML + separate JavaScript file
(**<name>.js**; + separate **<name>.wasm** file if emitting We-
bAssembly).
* <name> **.wasm** : WebAssembly without JavaScript support code
("standalone wasm"; this enables "STANDALONE_WASM").
These rules only apply when linking.
When compiling to object code
(See *-c* below) the name of the output file is irrelevant.
Note:
If "--memory-init-file" is used, a **.mem** file will be created
in addition to the generated **.js** and/or **.html** file.
"-c"
[compile] Tells *emcc* to emit an object file which can then be
linked with other object files to produce an executable.
"--output_eol windows|linux"
[link] Specifies the line ending to generate for the text files
that are outputted. If "--output_eol windows" is passed, the fi-
nal output files will have Windows rn line endings in them. With
"-- output_eol linux", the final generated files will be written
with Unix n line endings.
"--cflags"
[other] Prints out the flags "emcc" would pass to "clang" to
compile source code to object form. You can use this to invoke
clang yourself, and then run "emcc" on those outputs just for
the final linking+conversion to JS.
Environment variables =====================
*emcc* is affected by several environment variables, as listed below:
* "EMMAKEN_JUST_CONFIGURE" [other]
* "EMCC_AUTODEBUG" [compile+link]
* "EMCC_CFLAGS" [compile+link]
* "EMCC_CORES" [general]
* "EMCC_DEBUG" [general]
* "EMCC_DEBUG_SAVE" [general]
* "EMCC_FORCE_STDLIBS" [link]
* "EMCC_ONLY_FORCED_STDLIBS" [link]
* "EMCC_LOCAL_PORTS" [compile+link]
* "EMCC_STDERR_FILE" [general]
* "EMCC_CLOSURE_ARGS" [link] arguments to be passed to *Closure
Compiler*
* "EMCC_STRICT" [general]
* "EMCC_SKIP_SANITY_CHECK" [general]
* "EM_IGNORE_SANITY" [general]
* "EM_CONFIG" [general]
* "EM_LLVM_ROOT" [compile+link]
* "_EMCC_CCACHE" [general] Internal setting that is set to 1 by
emsdk when integrating with ccache compiler frontend
Search for 'os.environ' in emcc.py to see how these are used. The most
interesting is possibly "EMCC_DEBUG", which forces the compiler to dump
its build and temporary files to a temporary directory where they can
be reviewed.
------------------------------------------------------------------
emcc: supported targets: llvm bitcode, WebAssembly, NOT elf (autoconf
likes to see elf above to enable shared object support)
emcc 3.1.6~dfsg July 2022 EMCC(1)
Generated by dwww version 1.15 on Sat Jun 29 02:17:10 CEST 2024.