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,135 @@
+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>`
+
+#### Emscripten environment
+
+The Emscripten toolchain file is not particularly mature and can somewhat
+brittle in practice. In particular, it does not attempt to see if it's being
+used from within its SDK installation tree. Instead, it assumes that it is 
+running from within an Emscripten shell. It requires all relevant executables
+to be present with the search path. It expects to find certain environment
+variables.
+
+Therefore, it is highly recommended that initial configuration of CMake be run
+from within an Emscripten shell. These are available from the Emscripten SDK.
+CMake will appear to configure correctly in other circumstances, but it can
+fail otherwise.
+
+Using CMake
+-----------
+
+CMake supports build both inside the source tree and outside it. The CMake 
+working directory is whatever the current directory is when CMake is initially
+configured. The project root is specified on the command line of this
+configuration run. For an in-source build, simply run CMake in the project root.
+
+The present CMakeLists.txt is better suited for an out-of-source build. It
+does not put its intermediate or output files in any special place, so they all
+end up in the build directory.
+
+### Configurations
+
+The present CMakeLists.txt supports four configurations:
+* Release - `compile` 
+* Debug - `compile -d`
+* ReleaseTrace - `compile -t`
+* DebugTrace - `compile -d -t`
+
+A single-configuration generator, such as `make` or `ninja`, supports only one
+configuration per CMake build directory. Multiple build directories for
+different configurations, however, work just fine; each build directory gets
+its own CMake cache and working directory. [EH: I have a test setup locally
+with all four configurations and some scripts to configure everything and to
+build everything.] If no configuration is specified, it defaults to "Release".
+
+```
+    cmake -DCMAKE_BUILD_TYPE=Release [...]
+```
+
+A multiple-configuration generator, such as for Eclipse or XCode, makes all
+configurations available through the user interface of the IDE. 
+
+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.
+
+
+Draft Notes
+-----------
+
+There are a few known deficiencies.
+
+### Other targets
+
+There are no targets for testing or documentation.
+
+### eslint
+
+There's no provision for ignoring compiled-js files in eslint. This is only an
+issue for an in-source-tree build.