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.
 
 
-Work-in-Progress Notes
-----------------------
+Draft 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.
+There are a few known deficiencies.
 
 ### Other targets
 
 There are no targets for testing or documentation.
 
-### Location of generated files
+### eslint
 
-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`
-
+There's no provision for ignoring compiled-js files in eslint. This is only an
+issue for an in-source-tree build.