[BLAS,RNG,LAPACK] Add examples with CMake (#188)

* [blas] add source files for gemm example

* [blas] separate helper functions into .hpp

* [blas] add device description in header comment

* [blas] update source file name to match public backend name

* [blas] update file names

* [blas] change banner to apache, and move source files into RT/CT folders in domain

* [blas] add source files for gemm example

* [blas] separate helper functions into .hpp

* [blas] add device description in header comment

* [blas] update source file name to match public backend name

* [blas] update file names

* [blas] change banner to apache, and move source files into RT/CT folders in domain

* move examples common helper file under examples/

* [header] update helper header path in src

* update cmakelists for CT and levels up

* RT gemm update include header name

* test change1 cmake

* [blas][rng] fixed examples, tested on lnx

* Added lapack examples and other small fixes

* Create draft examples README.md (not for users)

* Update examples/README.md for better format

* remove detecting L0/openCL for intel backends

* add ctest and set SYCL_DEVICE_FILTER for examples testing

* small fixes with ctest

* Update examples README for users

* Update building_the_project.rst

* add_test for each SYCL_DEVICE_FILTER and align example test name

* fix typo

* improve format of output

* Update examples README output format

* Delete common_helper_functions.hpp

* fix cmake message

* Update examples/blas/CMakeLists.txt

Co-authored-by: Andrew T. Barker <andrew1.barker@intel.com>

* Update examples/blas/compile_time_dispatching/CMakeLists.txt

Co-authored-by: Andrew T. Barker <andrew1.barker@intel.com>

* [blas] remove standalone CT for every backend and add mklcpu+cuda, use malloc_device

* [rng] remove standalone CT for every backend and add mklcpu+cuda, use malloc_device

* [blas][include] improve style

* [lapack] remove standalone CT and add mklcpu+cuda, use malloc_device, and clean up

* small fix in output message

* Update README.md

* style fix

* [all] change calloc to std::vector

* [all] wait_and_throw on events and reverse sycl::free order

* [all] clang-format cpp and hpp files

* set build_examples to true as default, correct year in liscence

* remove not needed files

* remove unnecessary headers

* improve headers

* add comments about CT examples need CUDA backends

* Update README.md

* print matrices instead of check for correctness

* add note about float precision limit in README

* update CMake to work on AMD

* remove extra if

* clean up(improve wording, remove -DNOMINMAX)

* clean up with wording

Co-authored-by: Andrew T. Barker <andrew1.barker@intel.com>

Author: mcao59

CMakeLists.txt

@@ -59,6 +59,9 @@ set(ONEMKL_SYCL_IMPLEMENTATION "dpc++" CACHE STRING "Name of the SYCL compiler")
 ## Testing
 option(BUILD_FUNCTIONAL_TESTS "" ON)
 
+## Examples
+option(BUILD_EXAMPLES "" ON)
+
 ## Documentation
 option(BUILD_DOC "" OFF)
 
@@ -211,11 +214,19 @@ endif()
 add_subdirectory(src bin)
 
 # Functional Tests
-if(BUILD_FUNCTIONAL_TESTS)
+if(BUILD_FUNCTIONAL_TESTS OR BUILD_EXAMPLES)
   enable_testing()
+endif()
+
+if(BUILD_FUNCTIONAL_TESTS)
   add_subdirectory(tests)
 endif()
 
+# Examples
+if (BUILD_EXAMPLES)
+  add_subdirectory(examples)
+endif()
+
 if(BUILD_DOC)
   add_subdirectory(docs)
 endif()

docs/building_the_project.rst

@@ -238,6 +238,12 @@ Testing-Related Options
 * ``build_functional_tests=[True | False]``. Setting it to ``True`` enables
   the building of functional tests. The default value is ``True``.
 
+Example-Related Options
+~~~~~~~~~~~~~~~~~~~~~~~
+
+* ``build_examples=[True | False]``. Setting it to ``True`` enables
+  the building of examples. The default value is ``True``. Compile_time_dispatching examples will always be built if this value is set to true. Run_time_dispatching examples will be build if both this value and  ``build_shared_libs`` is set to true
+  
 Documentation
 ~~~~~~~~~~~~~
 
@@ -447,6 +453,10 @@ CMake.
      - BUILD_FUNCTIONAL_TESTS
      - True, False
      - True      
+   * - build_examples
+     - BUILD_EXAMPLES
+     - True, False
+     - True      
    * - build_doc
      - BUILD_DOC
      - True, False

examples/CMakeLists.txt

@@ -0,0 +1,24 @@
+#===============================================================================
+# Copyright 2022 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions
+# and limitations under the License.
+#
+#
+# SPDX-License-Identifier: Apache-2.0
+#===============================================================================
+
+# builds examples in specified domain
+
+foreach(domain ${TARGET_DOMAINS})
+  add_subdirectory(${domain})
+endforeach()