diff --git a/README.rst b/README.rst index 5721733ce..9e1e0225a 100644 --- a/README.rst +++ b/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 `_ + - 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 `_. + 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 `_ directory. +Look at `tests/README.rst `_ description. Generating the Doxygen documentation diff --git a/doc/cmake.rst b/doc/cmake.rst new file mode 100644 index 000000000..4fec327eb --- /dev/null +++ b/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 '' hides global declaration + add_compile_options("/wd4456") # warning C4456: declaration of '' 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. diff --git a/tests/README.rst b/tests/README.rst index 6a54a17cf..2086eb59a 100644 --- a/tests/README.rst +++ b/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: