Add documentation on CMake support for building and testing

This is basically provided by Nagy-Egri Máté Ferenc in his PR description on
triSYCL#29

README.rst

@@ -4,6 +4,10 @@ triSYCL
 News
 ----
 
+- 2017/03/03: triSYCL can use CMake & ctest and works on Windows 10 with
+  Visual Studio 2017. It works also with Ubuntu WSL on Windows. :-)
+  `More info <doc/cmake.rst>`_
+
 - 2017/01/12: Add test case using the Xilinx_ compiler for FPGA
 
 - 2016/11/18: If you missed the free SYCL T-shirt on the Khronos booth
@@ -418,12 +422,14 @@ triSYCL_ is configurable through preprocessor macros described in
 
 Also use ``-fopenmp`` if you want to use multicore parallelism on the CPU.
 
+The ``CMake`` support is described in `doc/cmake.rst <doc/cmake.rst>`_.
+
 
 Examples and tests
 ------------------
 
-There are simple examples and tests in the ``tests`` directory.  Look at
-`tests/README.rst` description.
+There are simple examples and tests in the `tests <tests>`_ directory.
+Look at `tests/README.rst <tests/README.rst>`_ description.
 
 
 Generating the Doxygen documentation

doc/cmake.rst

@@ -0,0 +1,170 @@
+======================
+ CMake infrastructure
+======================
+
+Features
+========
+
+Building
+--------
+
+The scripts intended to mimic the capabilities of the original GNU
+Makefiles but enhance them with a little CMake awesome. The scripts
+start off as:
+
+.. code:: CMake
+
+  #
+  # Behavioural options for the solution
+  #
+    option(TRISYCL_OPENMP "triSYCL multi-threading with OpenMP" ON)
+    option(TRISYCL_NO_ASYNC "triSYCL use synchronous kernel execution" OFF)
+    option(BUILD_OPENCL "triSYCL build OpenCL tests" ON)
+    option(BUILD_XILINX "triSYCL build Xilinx-specific tests" OFF)
+    option(TRISYCL_DEBUG "triSCYL use debug mode" OFF)
+    option(TRISYCL_DEBUG_STRUCTORS "triSYCL trace of object lifetimes" OFF)
+
+    set(CL_SYCL_LANGUAGE_VERSION 220 CACHE VERSION "Host language version to be used by trisYCL (default is: 220)")
+    set(TRISYCL_CL_LANGUAGE_VERSION 220 CACHE VERSION "Device language version to be used by trisYCL (default is: 220) (not used yet)")
+
+These variables can be set from the command-line at configuration
+time. The default values I hope make sense for the vast majority of
+development scenarios.
+
+
+Testing
+-------
+
+The scripts also hook unit testing into the familiar CTest
+framework. These scripts **do not rely on LIT** being present (one
+less dependency), because none of the unit tests used any features
+that are not present in CTest. CTest produces similarly sexy output as
+LIT, can test exit codes and match stdout vs. a regex.
+
+
+Warning-free
+------------
+
+As a good habit of mine, I raise the warning level on all compilers to
+the highest value, and went ahead and disabled warnings specifically
+that triggered in any of the tests. I would like to invite all devs to
+take on their favorite compiler they use to develop/consume triSYCL
+and get rid of all the warnings one by one. Some are fairly banal, but
+some may be quite severe.
+
+Notes
+`````
+
+The ``multiple_compilation_units`` tests fails on almost all compilers
+with the output being scrambled even though the NO_BARRIER define is
+set in code. What is the reason for this?
+
+.. code:: CMake
+
+  add_compile_options("/wd4459") # warning C4459: declaration of '<id>' hides global declaration
+  add_compile_options("/wd4456") # warning C4456: declaration of '<id>' hides previous local declaration
+
+
+For instance in the case of MSVC is either a two-phase name lookup
+error or a potential source of a serious bug. These options can be
+found in the top-level ``CMakeLists.txt`` file for all compilers.
+
+
+Tested platforms
+================
+
+Windows 10 + VS 15 + Boost 1.63.0
+---------------------------------
+
+Importing the environment of a developer command prompt, (and having
+the Ninja build system for eg. on the path), one can do something
+like:
+
+.. code:: PowerShell
+
+  PS C:\Users\Matty\Build\triSYCL> Import-CmdEnvironment 'C:\Kellekek\Microsoft\Visual Studio\15RC\VC\Auxiliary\Build\vcvars64.bat'
+  PS C:\Users\Matty\Build\triSYCL> cmake.exe -G"Ninja" -DBoost_COMPILER="-vc140" C:\Users\Matty\Source\Repos\triSYCL\
+
+This creates Ninja makefiles that can be invoked as simply as:
+
+.. code:: PowerShell
+
+  PS C:\Users\Matty\Build\triSYCL> cmake --build .
+
+which essentially invokes the underlying build systems 'all'
+target. After build is complete, one can run tests simply by typing:
+
+.. code:: PowerShell
+
+  PS C:\Users\Matty\Build\triSYCL> ctest
+
+which essentially invokes the underlying build systems 'test' target.
+
+
+Notes
+`````
+
+Because the ``FindBoost.cmake`` scripts wrongly expected the toolset
+of VS 15 to be v150 (instead of v141) one manually has to set the
+toolset version by configuring using `-DBoost_COMPILER="-vc140"`. One
+might ask: why 140 and not 141? Because even the coming Boost 1.64
+does not compile with the new toolset, due to it having gone ahead and
+riding the STL of deprecated STL functions such as |std::unary_function|_
+which Boost does not handle yet.
+
+..
+  Some hack to have formatting + link
+.. |std::unary_function| replace:: ``std::unary_function``
+.. _std::unary_function: http://en.cppreference.com/w/cpp/utility/functional/unary_function
+
+
+Ubuntu 16.04 (WSL) + GCC 6.2 + Boost 1.58.0
+-------------------------------------------
+
+Configure using:
+
+.. code:: Bash
+
+  mnagy@MATTY-Z50-75:~/build/triSYCL/gcc-6.2$ cmake -DCMAKE_C_COMPILER=gcc-6 -DCMAKE_CXX_COMPILER=g++-6 /mnt/c/Users/Matty/Source/Repos/triSYCL/
+
+Building using:
+
+.. code:: Bash
+
+  mnagy@MATTY-Z50-75:~/build/triSYCL/gcc-6.2$ cmake --build . -- -j5
+
+Testing:
+
+.. code:: Bash
+
+  mnagy@MATTY-Z50-75:~/build/triSYCL/gcc-6.2$ ctest
+
+
+Ubuntu 16.04 (WSL) + Clang 4.0 + Boost 1.58.0
+---------------------------------------------
+
+Configure using:
+
+.. code:: Bash
+
+  mnagy@MATTY-Z50-75:~/build/triSYCL/clang-4.0$ cmake -DCMAKE_C_COMPILER=clang-4.0 -DCMAKE_CXX_COMPILER=clang++-4.0 -DTRISYCL_OPENMP=OFF /mnt/c/Users/Matty/Source/Repos/triSYCL/
+
+Building using:
+
+.. code:: Bash
+
+  mnagy@MATTY-Z50-75:~/build/triSYCL/clang-4.0$ cmake --build . -- -j5
+
+Testing:
+
+.. code:: Bash
+
+  mnagy@MATTY-Z50-75:~/build/triSYCL/clang-4.0$ ctest
+
+
+Notes
+`````
+
+I could not get Clang actually work with OpenMP. It throws a runtime
+(?!?!) exception for using unimplemented feature. Otherwise omitting
+OpenMP results in some dead-locking tests.

tests/README.rst

@@ -7,13 +7,24 @@ triSYCL testing
 
 Here are some simple examples and tests using triSYCL.
 
-Everything is under control of the GNU `Makefile` for now but there is
-a CMake version on-going.
+Everything is under control of either
+
+- a native GNU `Makefile`
+
+- or a `CMake`-based configuration.
 
 
 Compiling and execution
 =======================
 
+Using ``CMake``
+---------------
+
+See `../doc/cmake.rst <../doc/cmake.rst>`_
+
+
+Using ``make`` directly
+-----------------------
 
 To compile them:
 
@@ -57,6 +68,17 @@ want to run, such as:
 Testing
 =======
 
+Using ``CMake`` ``ctest``
+-------------------------
+
+See `../doc/cmake.rst <../doc/cmake.rst>`_
+
+Basically, just use ``ctest``.
+
+
+Using ``make`` and ``LIT``
+--------------------------
+
 The tests are based on the LIT_ tool from the LLVM_ infrastructure.
 
 To install it on Debian or Ubuntu, use typically:
@@ -110,6 +132,7 @@ files, use the ``clone-T`` targets, such as:
 
   make clone-check
 
+
 ..
   Somme useful link definitions: