Provided by: emscripten_1.10.0~20140205~ef1e460-1_amd64 bug

NAME

       emcc - Emscripten compiler frontend

DESCRIPTION

       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)

       -O1    Simple  optimizations,  including  asm.js,  LLVM  -O1 optimizations, and no runtime
              assertions or C++ exception catching (to re-enable C++ exception catching,  use  -s
              DISABLE_EXCEPTION_CATCHING=0  ).   (For  details  on  the  affects of different opt
              levels, see apply_opt_level() in tools/shared.py and also src/settings.js.)   Note:
              Optimizations  are  only  done  when  compiling  to JavaScript, not to intermediate
              bitcode, *unless* you build with EMCC_OPTIMIZE_NORMALLY=1 (not  recommended  unless
              you know what you are doing!)

       -O2    As -O1, plus the relooper (loop recreation), LLVM -O2 optimizations, and

              -s ALIASING_FUNCTION_POINTERS=1

       -O3    As -O2, plus dangerous optimizations that may break the generated code! This adds

              -s  FORCE_ALIGNED_MEMORY=1  -s  DOUBLE_MODE=0  -s  PRECISE_I64_MATH=0  --closure  1
              --llvm-lto 1

              This is not recommended at all. A better idea is to try each of these separately on
              top of -O2 to see what works. See the wiki and src/settings.js (for the -s options)
              for more information.

       -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.  Note  that  you need this during the last compilation phase from
              bitcode to JavaScript, or else we will remove it by default in -O1 and  above.   In
              -O0,  line  numbers  wil  be  shown  in  the  generated code. In -O1 and above, the
              optimizer removes those comments.  This  flag  does  however  have  the  effect  of
              disabling  anything  that  causes  name  mangling  or  minification (closure or the
              registerize pass).

       --typed-arrays <mode>
              0: No typed arrays 1:  Parallel  typed  arrays  2:  Shared  (C-like)  typed  arrays
              (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+)

       --llvm-lto <level>
              0: No LLVM LTO (default in -O2 and below) 1: LLVM LTO (default  in  -O3)  Note:  If
              LLVM optimizations are not run (see --llvm-opts), setting this to 1 has no effect.

       --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. This is run by default in -O3.

              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).

       --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.

       --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.

       --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.

       --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).

       --compression <codec>
              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 <on>
              0: Do not minify the generated JavaScript's whitespace (default in -O0, -O1, or  if
              -g is used)

              1: Minify the generated JavaScript's

              whitespace (default in -O2+, assuming -g is not used)

       --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".

       --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.

       --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_CODE }}}  Note  that  this
              argument is ignored if a target other than HTML is specified using the -o option.

       --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, and also enable EMCC_DEBUG to
              details emcc's operations

       --jcache
              Use a JavaScript cache. This is disabled by default. When enabled, emcc will  store
              the  results  of  compilation  in a cache and check the cache when compiling later,
              something like what ccache does. This allows incremental builds  -  where  you  are
              compiling  a large program but only modified a small part of it - to be much faster
              (at the cost of more disk IO for cache accesses). Note  that  you  need  to  enable
              --jcache for both loading and saving of data, so you must enable it on a full build
              for a later incremental build (where you also enable it) to be sped up.

              Caching works separately on 4 parts of compilation: 'pre' which is types and global
              variables; that information is then fed into 'funcs' which are the functions (which
              we parallelize), and  then  'post'  which  adds  final  information  based  on  the
              functions   (e.g.,  do  we  need  long64  support  code).  Finally,  'jsfuncs'  are
              JavaScript-level optimizations. Each of the 4 parts can be cached  separately,  but
              note  that  they  can  affect  each  other: If you recompile a single C++ file that
              changes a global variable - e.g., adds, removes or modifies a global variable,  say
              by  adding  a  printf  or  by adding a compile-time timestamp, then 'pre' cannot be
              loaded from the cache. And since 'pre's output is sent to 'funcs' and 'post',  they
              will get invalidated as well, and only 'jsfuncs' will be cached. So avoid modifying
              globals to let caching work fully.

              To work around the problem mentioned in the previous paragraph, you can use

              emscripten_jcache_printf

              when adding debug printfs to your code. That function is specially preprocessed  so
              that  it  does  not  create  a  constant  string global for its first argument. See
              emscripten.h for more details. Note in particular that you need to already  have  a
              call  to  that  function  in  your  code *before* you add one and do an incremental
              build, so that adding an external reference  (also  a  global  property)  does  not
              invalidate everything.

              Note that you should use -g during the linking stage (bitcode to JS), for jcache to
              work (otherwise, JS minification can confuse it).

       --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>
              If on, we generate a separate memory initialization file. This  is  more  efficient
              than  storing  the  memory  initialization data embedded inside JavaScript as text.
              (default is off)

       The target file, if specified (-o <target>), defines what will be generated:

       <name>.js
              JavaScript

       <name>.html
              HTML with embedded JavaScript

       <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)

COPYRIGHT

       Copyright  ©  2013  the  Emscripten authors (see AUTHORS.txt) This is free and open source
       software under the MIT license.  There is NO warranty; not  even  for  MERCHANTABILITY  or
       FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO

       The  full  documentation for emcc is maintained as a Texinfo manual.  If the info and emcc
       programs are properly installed at your site, the command

              info emcc

       should give you access to the complete manual.

emcc (Emscripten GCC-like replacement) 1.4.7June 2013                                     EMCC(1)