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,113 @@
+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.
+
+
+Work-in-Progress Notes
+----------------------
+
+There are a number of known deficiencies.
+
+### Configurations
+
+The compile script has two options `--debug` and `--trace`. The current CMake
+file has debug on and trace off. The right way to do with is with CMake
+configurations: "Release", "ReleaseTrace", "Debug", "DebugTrace".
+
+### Building bindings
+
+As of the present version, the step to run the bindings generator always runs
+whether it needs to or not. This deficiency arises because the obvious way to do
+this in CMake uses phony make targets that have this behavior.
+
+### Other targets
+
+There are no targets for testing or documentation.
+
+### Location of generated files
+
+The generated files are built in the root directory at present. This works fine
+for an out-of-source build with CMake. It might work less fine in the long term
+for an in-source build, but it has been expedient to date to put these files
+in different locations from the `compile` script to make "before" vs. "after"
+comparisons more quickly. Here's a list of these changes.
+
+* `compiled/bindings.cpp.js` --> `binding-generator.js`
+* `compiled/bindings.js` --> `bindings.js`
+* `lib/compiled.js` --> `compiled.js`
+* `lib/compiled.js.symbols` --> `compiled.js.symbols`
+