Working Draft: CMake build for Emscripten

README.CMAKE.md

 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
 ------------
 
@@ skipping 36 matching lines @@
 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.
+#### 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.