Working Draft: CMake build for Emscripten

README.CMAKE.md

Index: README.CMAKE.md
===================================================================
new file mode 100644
--- /dev/null
+++ b/README.CMAKE.md
@@ -0,0 +1,80 @@
+Experimental CMake build for adblockpluscore
+============================================
+
+This files describes an experimental build using CMake. For the duration of 
+this experiment, this file will describe the build independently, leaving the 
+existing README.md intact.
+
+Requirements
+------------
+
+* [CMake](https://cmake.org). The Emscripten toolchain file requires version 
+3.4.3 or newer.
+* [Emscripten 1.37](https://kripken.github.io/emscripten-site/)
+
+Configuring CMake
+-----------------
+
+CMake uses a cache to hold configuration information that is not an ordinary 
+part of the write-build-test cycle. Thus the first invocation of CMake requires
+extra configuration parameters. Subsequent invocations do not require these. 
+We require two such kinds of configuration data:
+* Generator for build system
+* Emscriptem tool chain
+
+### Build system generator
+
+CMake is a cross-platform build system generator. It has the capability of 
+generating project files for a number of build systems, including those that 
+are an integral part of an IDE. Specifically, these include makefiles in 
+several variants, ninja, Eclipse, Visual Studio, and XCode.
+
+To set up the cache with a generator, use the `-G` option on the CMake command 
+line. The quickest way to find the exact text to use as the argument to this
+option is run CMake with the `--help` option`. Further information is available
+in the CMake documentation; see cmake-generators(7).
+
+### Emscripten
+
+CMake treats Emscripten as a cross-compiler. CMake can auto-detect native 
+compilers but requires pre-configuration for cross-compilers. Emscripten 
+provides a CMake toolchain file for this purpose. The location of this file is 
+what CMake ultimately needs.
+
+The most direct way to specify the path to the toolchain file is to define a 
+cache variable directly on the CMake command line. The toolchain file is 
+buried within the Emscripten installation. The name of the cache variable and 
+the specific location of the file are visible within the following command 
+line fragment:
+
+```
+    cmake -DCMAKE_TOOLCHAIN_FILE=<EmscriptenRoot>/cmake/Modules/Platform/Emscripten.cmake [...]
+```
+
+Note that the `<EmscriptenRoot>` about is _not_ the root of the Emscripten 
+SDK. Within the SDK, the location is `<SdkRoot>/emscripten/<version>`
+
+This toolchain file assumes that it's running within an Emscripten shell with 
+all paths and environment variables set up. CMake will appear to configure 
+correctly outside this, but will not find executables, etc.
+
+
+Notes
+-----
+
+### Setting up Emscripten under Cygwin.
+
+tl;dr version: Don't.
+
+It's a known issue that the Emscripten tool chain as distributed does not work 
+under Cygwin. The core of the issue is that Emscripten uses a number of native 
+Windows executables and the transition from Cygwin path names to Windows path 
+names doesn't work correctly.
+
+https://github.com/kripken/emscripten/issues/3947
+
+Once the command `emcc -v` runs correctly, CMake will be able to set up the 
+Emscripten tool chain. Even then, there will still be errors in other ways.
+
+
+