Improve build and add instructions

Summary:
Tweak the CMake build to better support Emacripten and add
instructions.

## Performance

When built in Release+Wasm mode and executed by NodeJS, the Hermes
compiler itself is about 5-10% slower than a native version when compiling
a multi-megabyte JS source. It is likely that tweaking the memory growth
parameters will help even further.

VM execution performance of interp-dispatch.js is
about 6 times slower with Wasm Hermes compared to a native one. I
haven't spent time to look into it though. It is likely that it can be
improved.

Reviewed By: dulinriley

Differential Revision: D19804100

fbshipit-source-id: d808fa9235d28b3217504e51ddd0d408befeb534

CMakeLists.txt

@@ -163,6 +163,9 @@ set(ANDROID_LINUX_PERF_PATH ""
 set(HERMES_MSVC_MP ON CACHE STRING
   "Enable /MP in MSVC for parallel builds")
 
+set(EMSCRIPTEN_FASTCOMP ON CACHE BOOL
+  "Emscripten is using the fastcomp backend instead of the LLVM one")
+
 if (HERMES_IS_ANDROID)
   add_definitions(-DHERMES_PLATFORM_UNICODE=HERMES_PLATFORM_UNICODE_JAVA)
 

cmake/modules/Hermes.cmake

@@ -21,6 +21,13 @@ elseif (CMAKE_CXX_COMPILER_ID MATCHES "Clang")
   endif ()
 endif ()
 
+# Emscripten with Fastcomp backend in WASM mode generates trapping conversions
+# from float/double to int. We require non-trapping behavior.
+if (EMSCRIPTEN AND EMSCRIPTEN_FASTCOMP)
+  # Note that this flag only affects Wasm, not Asm.js.
+  set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -s BINARYEN_TRAP_MODE=clamp")
+endif()
+
 # For compatibility, CMake adds /EHsc by default for MSVC. We want to set that
 # flag per target, so remove it.
 if (MSVC)

doc/Emscripten.md

@@ -0,0 +1,36 @@
+---
+id: Emscripten
+title: Building Hermes with Emscripten
+---
+
+# Building Hermes With Emscripten and CMake
+
+    # Create a new build directory
+    mkdir embuild && cd embuild
+    # Configure the build
+    cmake ${HermesSourcePath?} \
+          -DCMAKE_TOOLCHAIN_FILE=${EmscriptenRoot?}/emscripten/cmake/Modules/Platform/Emscripten.cmake \
+          -DCMAKE_BUILD_TYPE=MinSizeRel \
+          -DEMSCRIPTEN_FASTCOMP=1 \
+          -DCMAKE_EXE_LINKER_FLAGS="-s NODERAWFS=1 -s WASM=0 -s ALLOW_MEMORY_GROWTH=1"
+    # Build Hermes
+    make -j hermes
+    # Execute hermes
+    node bin/hermes.js --help
+
+In the commands above, replace `${HermesSourcePath?}` with the path where you
+cloned Hermes, and `${EmscriptenRoot?}` with the path to your Emscripten
+install.
+
+You can further customize the following settings:
+- `CMAKE_BUILD_TYPE`: set it to one of CMake's build modes: `Debug`, `Release`, 
+`MinSizeRel`, etc.
+- `EMSCRIPTEN_FASTCOMP`: Set it to 1 or 0 depending on whether you are using
+Emscripten with the *fastcomp* backend, or with the new LLVM backend.
+- `-s NODERAWFS`: add this if you will be running Hermes directly with Node. It
+enables direct access to the filesystem.
+- `-s WASM=`: set this to 0 for *Asm.js* output, 1 for *Wasm*, and 2 for both.
+
+You can customize the build generator by passing the `-G` option to CMake, for 
+example `-G Ninja`.
+