-
Notifications
You must be signed in to change notification settings - Fork 3
/
help.txt
446 lines (364 loc) · 23.9 KB
/
help.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
emcc [options] file...
Most normal gcc/g++ options will work, for example:
--help Display this information
--version Display compiler version information
Options that are modified or new in emcc include:
-O0 No optimizations (default). This is the recommended
setting for starting to port a project, as it
includes various assertions.
-O1 Simple optimizations, including asm.js, LLVM -O1
optimizations, relooping, and no runtime assertions
or C++ exception catching (to re-enable
C++ exception catching, use
-s DISABLE_EXCEPTION_CATCHING=0 ), and enables
-s ALIASING_FUNCTION_POINTERS=1
This is the recommended setting when you want a
reasonably optimized build that is generated as
quickly as possible (it builds much faster than -O2).
(Note: for details on the affects of different
opt levels, see apply_opt_level() in
tools/shared.py and also src/settings.js.)
-O2 As -O1, plus various js-level optimizations, LLVM
-O3 optimizations, and memory init file generation
(--memory-init-file 1). This is a good setting
for an optimized build: runs much faster than
-O1, and compiles much faster than -O3.
-Os Like -O2 with extra optimizations for size.
-Oz Like -Os but reduces code size further.
-O3 Like -O2 plus additional JS optimizations that can
take a significant amount of compilation time and/or
are relatively new. Note that differs from -O2 only
during the bitcode to JS (final link + JS generation)
stage, as it is JS-specific, so you can run -Os
on your source files for example, and -O3 during
JS generation if you want.
For tips on optimizing your code, see
https://github.com/kripken/emscripten/wiki/Optimizing-Code
-s OPTION=VALUE JavaScript code generation option passed
into the emscripten compiler. For the
available options, see src/settings.js
Note that for options that are lists, you
need quotation marks in most shells, for
example
-s RUNTIME_LINKED_LIBS="['liblib.so']"
or
-s "RUNTIME_LINKED_LIBS=['liblib.so']"
(without the external "s in either of those,
you would get an error)
You can also specify a file from which the
value would be read, for example,
-s DEAD_FUNCTIONS=@/path/to/file
The contents of /path/to/file will be read,
JSON.parsed and set into DEAD_FUNCTIONS (so
the file could contain
["_func1", "func2"]
). Note that the path must be absolute, not
relative.
-g Use debug info. When compiling to bitcode,
this is the same as in clang and gcc, it
adds debug info to the object files. When
compiling from source to JS or bitcode to JS,
it is equivalent to -g3 (keep code as debuggable
as possible, except for discarding LLVM
debug info, so no C/C++ line numbers; use
-g4 to get line number debugging info in JS).
-g<level> When compiling from bitcode to JS, we can
keep the code debuggable to different
degrees. Each of these levels builds on the
previous:
-g0 Make no effort to keep code debuggable.
Will discard LLVM debug info. (default
in -O1+)
-g1 Preserve (do not minify) whitespace
-g2 Preserve function names
-g3 Preserve variable names
-g4 Preserve LLVM debug info (if -g was
used when compiling the C/C++ sources),
show line number debug comments, and
generate source maps. This is the highest
level of debuggability. Note that this
may make -O1 and above significantly
slower because JS optimization will be
limited to 1 core. (default in -O0)
-profiling Use reasonable defaults when emitting JS to
make the build useful for profiling. This
sets -g2 (preserve function names) and may
also enable optimizations that affect
performance and otherwise might not be
performed in -g2.
--emit-symbol-map Save a map file between the minified
global names and the original function names.
This allows you to reconstruct meaningful
stack traces, for example. (This is only
relevant when minifying global names, which
happens in -O2 and above, and when no -g
option to prevent minification was specified.)
--typed-arrays <mode> 0: No typed arrays
1: Parallel typed arrays
2: Shared (C-like) typed arrays (default)
--js-opts <on> 0: Prevent JS optimizer from running
1: Use JS optimizer (default)
--llvm-opts <level> 0: No LLVM optimizations (default in -O0)
1: -O1 LLVM optimizations (default in -O1)
2: -O2 LLVM optimizations
3: -O3 LLVM optimizations (default in -O2+)
You can also specify arbitrary LLVM options, e.g.
--llvm-opts "['-O3', '-somethingelse']"
--llvm-lto <level> 0: No LLVM LTO (default)
1: LLVM LTO is performed
2: We combine all the bitcode and run LLVM opt -O3
on that (which optimizes across modules, but is
not the same as normal LTO), but do not do normal
LTO
3: We do both 2 and then 1
Note: If LLVM optimizations are not run
(see --llvm-opts), setting this has no
effect.
Note that LLVM LTO is not perfectly stable yet,
and can can cause code to behave incorrectly.
--closure <on> 0: No closure compiler (default in -O2 and below)
1: Run closure compiler. This greatly reduces
code size and may in some cases increase
runtime speed (although the opposite can also
occur). Note that it takes time to run, and
may require some changes to the code.
In asm.js mode, closure will only be used on the
'shell' code around the compiled code (the
compiled code will be processed by the custom
asm.js minifier).
Note: If closure compiler hits an out-of-memory,
try adjusting JAVA_HEAP_SIZE in the environment
(for example, to 4096m for 4GB).
Note: Closure is only run if js opts are being
done (-O2 or above, or --js-opts 1).
--pre-js <file> A file whose contents are added before the
generated code. This is done *before*
optimization, so it will be minified
properly if closure compiler is run.
--post-js <file> A file whose contents are added after the
generated code This is done *before*
optimization, so it will be minified
properly if closure compiler is run.
Note that the post js will typically run after
main() completes (unless there is something
async). In that case, main() will exit and
the post js will not be reached (just as if
you call exit() in C code). If you want to
prevent that, you can build with
-s NO_EXIT_RUNTIME=1
--embed-file <file> A file to embed inside the generated
JavaScript. The compiled code will be able
to access the file in the current directory
with the same name as given here. So if
you do --embed-file dir/file.dat, then
(1) dir/file.dat must exist relative to
where you run emcc, and (2) your compiled
code will be able to find the file by
reading that same path, dir/file.dat.
If a directory is passed here, its entire
contents will be embedded.
Note: Embedding files is much less
efficient than preloading them. You
should only use it for small amounts
of small files. Instead, use
--preload-file which emits efficient
binary data.
--preload-file <name> A file to preload before running the
compiled code asynchronously. Otherwise
similar to --embed-file, except that this
option is only relevant when generating
HTML (it uses asynchronous binary XHRs),
or JS that will be used in a web page.
If a directory is passed here, its entire
contents will be preloaded.
Preloaded files are stored in filename.data,
where filename.html is the main file you
are compiling to. To run your code, you
will need both the .html and the .data.
emcc runs tools/file_packager.py to do the
actual packaging of embedded and preloaded
files. You can run the file packager yourself
if you want, see docs inside that file. You
should then put the output of the file packager
in an emcc --pre-js, so that it executes before
your main compiled code (or run it before in
some other way).
For more docs on the options --preload-file
accepts, see https://github.com/kripken/emscripten/wiki/Filesystem-Guide
--exclude-file <name> Files and directories to be excluded from
--embed-file and --preload-file
wildcard is supported
--shell-file <path> The path name to a skeleton HTML file used
when generating HTML output. The shell file
used needs to have this token inside it:
{{{ SCRIPT }}}
(see src/shell.html and
src/shell_minimal.html for examples)
Note that this argument is ignored if a
target other than HTML is specified using
the -o option.
--compression <codec> **THIS OPTION IS DEPRECATED**
Compress both the compiled code and embedded/
preloaded files. <codec> should be a triple,
<native_encoder>,<js_decoder>,<js_name>
where native_encoder is a native executable
that compresses stdin to stdout (the simplest
possible interface), js_decoder is a
JavaScript file that implements a decoder,
and js_name is the name of the function to
call in the decoder file (which should
receive an array/typed array and return
an array/typed array.
Compression only works when generating HTML.
When compression is on, all filed specified
to be preloaded are compressed in one big
archive, which is given the same name as the
output HTML but with suffix .data.compress
--minify 0 Identical to -g1
--js-transform <cmd> <cmd> will be called on the generated code
before it is optimized. This lets you modify
the JavaScript, for example adding some code
or removing some code, in a way that those
modifications will be optimized together with
the generated code properly. <cmd> will be
called with the filename 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.
--split <size> Splits the resulting javascript file into pieces
to ease debugging. This option only works if
Javascript is generated (target -o <name>.js).
Files with function declarations must be loaded
before main file upon execution.
Without "-g" option:
Creates files with function declarations up
to the given size with the suffix
"_functions.partxxx.js" and a main file with
the suffix ".js".
With "-g" option:
Recreates the directory structure of the C
source files and stores function declarations
in their respective C files with the suffix
".js". If such a file exceeds the given size,
files with the suffix ".partxxx.js" are created.
The main file resides in the base directory and
has the suffix ".js".
Note: this option is deprecated (modern JS debuggers
should work ok even on large files)
--bind Compiles the source code using the "embind"
bindings approach, which connects C/C++ and JS.
--ignore-dynamic-linking Normally emcc will treat dynamic linking like
static linking, by linking in the code from
the dynamic library. This fails if the same
dynamic library is linked more than once.
With this option, dynamic linking is ignored,
which allows the build system to proceed without
errors. However, you will need to manually
link to the shared libraries later on yourself.
--js-library <lib> A JavaScript library to use in addition to
those in Emscripten's src/library_*
-v Turns on verbose output. This will pass
-v to Clang. It will also run emscripten's internal
sanity checks, checking that things like the LLVM
directory path looks correct, etc. This works with or
without other arguments, so it can be useful to run
emcc -v
if you see odd errors, as it can help diagnose
things.
To enable additional emscripten logging, you can
set EMCC_DEBUG=1 in the environment, which will
also save temporary files in the canonical location
(usually /tmp/emscripten_temp).
--clear-cache Manually clears the cache of compiled
emscripten system libraries (libc++,
libc++abi, libc). This is normally
handled automatically, but if you update
llvm in-place (instead of having a different
directory for a new version), 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 like the jcache and
the bootstrapped relooper. After the cache
is cleared, this process will exit.
--save-bc PATH When compiling to JavaScript or HTML, this
option will save a copy of the bitcode to
the specified path. The bitcode will include
all files being linked, including standard
libraries, and after any link-time optimizations
(if any).
--memory-init-file <on> 0: Do not emit a separate memory initialization
file, keep the static initialization inside
the generated JavaScript as text (default
in -O0 and -O1)
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 applied; you cannot
call any C functions until it arrives. (Call
yourself from main() to know when all async
stuff has happened and it is safe to call
library functions, as main() will only be
called at that time. You can also call
addOnPreMain from a preRun.) (default in -O2+)
Note the .mem file should be in the same
directory as the .js file when the code is run.
If you want it to be in a different directory,
you can define Module.memoryInitializerPrefixURL
which will be used as a prefix.
-Wno-warn-absolute-paths If not specified, the compiler will warn about any
uses of absolute paths in -I and -L command line
directives. Pass this flag on the command line
to hide these warnings and acknowledge that the
explicit use of absolute paths is intentional.
--proxy-to-worker Runs the main application code in a worker, proxying
events to it and output from it.
If emitting htmlL, this emits an html and a js file,
with the js to be run in a worker. If emitting
js, the target filename 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 Enables the generated output to be aware of the
emrun command line tool. This allows stdout, stderr
and exit(returncode) capture when running the
generated application through emrun.
--em-config Specifies the location of the .emscripten configuration
file for the current compiler run. If not specified,
the environment variable EM_CONFIG is read for this
file, and if that is not set, the default location
~/.emscripten is assumed.
--default-obj-ext .ext Specifies the file suffix to generate if the location
of a directory name is passed to -o directive, e.g.
emcc -c a.c -o dir/
will by default generate an output name 'dir/a.o',
but this cmdline param can be passed to generate a
file with a custom suffix 'dir/a.ext'.
--valid_abspath path Whitelist an absolute path to prevent warnings about
absolute include paths.
The target file, if specified (-o <target>), defines what will
be generated:
<name>.js JavaScript
<name>.html HTML + side JavaScript file (<name>.js)
(JS on the side improves page load time)
<name>.bc LLVM bitcode (default)
<name>.o LLVM bitcode (same as .bc)
(Note that if --memory-init-file is used, then in addition to a
.js or .html file that is generated, a .mem file will also appear.)
The -c option (which tells gcc not to run the linker) will
cause LLVM bitcode to be generated, as emcc only generates
JavaScript in the final linking stage of building.
The input file(s) can be either source code files that
Clang can handle (C or C++), LLVM bitcode in binary form,
or LLVM assembly files in human-readable form.
emcc is affected by several environment variables. For details, view
the source of emcc (search for 'os.environ').
emcc: supported targets: llvm bitcode, javascript, NOT elf
(autoconf likes to see elf above to enable shared object support)