Minor doc updates (#6528)

* add a FAQ entry about uglify parsing errors

* update changelog

* update docs on optimizing code when building projects

Author: kripken

ChangeLog.markdown

@@ -9,6 +9,7 @@ Not all changes are documented here. In particular, new features, user-oriented
 
 Current Trunk
 -------------
+ - Remove special-case support for src/struct_info.compiled.json: Make it a normal cached thing like system libraries, not something checked into the source tree.
  - Breaking change: Emit WebAssembly by default. Only the default is changed - we of course still support asm.js, and will for a very long time. But changing the default makes sense as the recommended output for most use cases should be WebAssembly, given it has shipped in all major browsers and platforms and is more efficient than asm.js. Build with `-s WASM=0` to disable wasm and use asm.js if you want that (or use `-s LEGACY_VM_SUPPORT=1`, which emits output that can run in older browsers, which includes a bunch of polyfills as well as disables wasm). (#6419)
 
 v1.38.0: 05/09/2018

site/source/docs/compiling/Building-Projects.rst

@@ -56,15 +56,15 @@ The last step is to compile the linked bitcode into JavaScript. We do this by ca
 Building projects with optimizations
 ====================================
 
-Emscripten performs :ref:`compiler optimization <Optimizing-Code>` at two levels: each source file is optimized by LLVM as it is compiled into an object file, and then JavaScript-specific optimizations are applied when converting object files into JavaScript.
+Emscripten performs :ref:`compiler optimization <Optimizing-Code>` at two levels: each source file is optimized by LLVM as it is compiled into an object file, and then JavaScript/WebAssembly-specific optimizations are applied when converting object files into the final JavaScript/WebAssembly.
 
-In order to properly optimize code, it is important to use the **same** :ref:`optimization flags <emcc-compiler-optimization-options>` and other :ref:`compiler options <emcc-s-option-value>` when compiling source to object code, and object code to JavaScript (or HTML).
+In order to properly optimize code, it is usually best to use the **same** :ref:`optimization flags <emcc-compiler-optimization-options>` and other :ref:`compiler options <emcc-s-option-value>` when compiling source to object code, and object code to JavaScript (or HTML).
 
 Consider the examples below:
 
 .. code-block:: bash
 
-	# Sub-optimal - JavaScript optimizations are omitted
+	# Sub-optimal - JavaScript/WebAssembly optimizations are omitted
 	./emcc -O2 a.cpp -o a.bc
 	./emcc -O2 b.cpp -o b.bc
 	./emcc a.bc b.bc -o project.js
@@ -74,26 +74,27 @@ Consider the examples below:
 	./emcc b.cpp -o b.bc
 	./emcc -O2 a.bc b.bc -o project.js
 
-	# Broken! Different JavaScript and LLVM optimisations used.
-	./emcc -O1 a.cpp -o a.bc
-	./emcc -O2 b.cpp -o b.bc
-	./emcc -O3 a.bc b.bc -o project.js
-	
-	# Correct. The SAME LLVM and JavaScript options are provided at both levels.
+	# Usually the right thing: The SAME LLVM and JavaScript options are provided at both levels.
 	./emcc -O2 a.cpp -o a.bc
 	./emcc -O2 b.cpp -o b.bc
 	./emcc -O2 a.bc b.bc -o project.js
 
+However, sometimes you may want slightly different optimizations on certain files:
+
+.. code-block:: bash
 
-The same rule applies when :ref:`building Emscripten using a build system <building-projects-build-system>` — both LLVM and JavaScript must be optimized using the same settings. 
+	# Optimize the first file for size, and the rest using `-O2`.
+	./emcc -Oz a.cpp -o a.bc
+	./emcc -O2 b.cpp -o b.bc
+	./emcc -O2 a.bc b.bc -o project.js
 
 .. note:: Unfortunately each build-system defines its own mechanisms for setting compiler and optimization methods. **You will need to work out the correct approach to set the LLVM optimization flags for your system**.
 
 	- Some build systems have a flag like ``./configure --enable-optimize``. 
 	- You can control whether LLVM optimizations are run using ``--llvm-opts N`` where N is an integer in the range 0-3. Sending ``-O2 --llvm-opts 0`` to *emcc* during all compilation stages will disable LLVM optimizations but utilize JavaScript optimizations. This can be useful when debugging a build failure.
 
 
-JavaScript optimizations are specified in the final step, when you compile the linked LLVM bitcode to JavaScript. For example, to compile with :ref:`-O1 <emcc-O1>`:
+JavaScript/WebAssembly optimizations are specified in the final step (sometimes called "link", as that step typically also links together a bunch of files that are all compiled together into one JavaScript/WebAssembly output). For example, to compile with :ref:`-O1 <emcc-O1>`:
 
 .. code-block:: bash
 

site/source/docs/getting_started/FAQ.rst

@@ -420,6 +420,18 @@ A possible cause is that building *libcxx* or *libcxxabi* failed. Go to **system
 Another possible cause of this error is the lack of ``make``, which is necessary to build these libraries. If you are on Windows, you need *cmake*.
 
 
+Why do I get an error mentioning Uglify and ``throw new JS_Parse_Error``?
+=========================================================================
+
+In ``-O2`` and above, emscripten will optimize the JS using Uglify1. If you added any JS (using ``--pre-js``/``--post-js``/``EM_ASM``/``EM_JS``) and it contains JS that Uglify1 can't parse - like recent ES6 features - then it will throw such a parsing error.
+
+In the long term we hope to upgrade our internal JS parser. Meanwhile, you can move such code to another script tag on the page, that is, not pass it through the emscripten optimizer.
+
+See also
+
+ * https://github.com/kripken/emscripten/issues/6000
+ * https://github.com/kripken/emscripten/issues/5700
+
 Why does running LLVM bitcode generated by emcc through **lli** break with errors about ``impure_ptr``?
 =======================================================================================================