Update documentation for oneDPL 2022.2.0

uxlfoundation · Jul 25, 2023 · 281dddf · 281dddf
1 parent ef06f8c
commit 281dddf
Show file tree

Hide file tree

Showing 78 changed files with 4,892 additions and 178 deletions.
diff --git a/_sources/cmake_support.rst.txt b/_sources/cmake_support.rst.txt
@@ -0,0 +1,109 @@
+CMake Support
+#############
+
+General Usage
+=============
+`CMake <https://cmake.org/cmake/help/latest/index.html>`_ is a cross-platform build system generator. It can be used to generate build scripts which can then be used to build and link your application.
+
+``oneDPLConfig.cmake`` and ``oneDPLConfigVersion.cmake`` are distributed with |onedpl_short|. These files allow integration of |onedpl_short| into user projects with the `find_package <https://cmake.org/cmake/help/latest/command/find_package.html>`_ command. Successful invocation of ``find_package(oneDPL <options>)`` creates imported target `oneDPL` that can be passed to the `target_link_libraries <https://cmake.org/cmake/help/latest/command/target_link_libraries.html>`_ command.
+
+Some useful CMake variables (`here <https://cmake.org/cmake/help/latest/manual/cmake-variables.7.html>`_ you can find a full list of CMake variables for the latest version):
+
+- `CMAKE_CXX_COMPILER <https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_COMPILER.html>`_ - C++ compiler used for build: ``CMAKE_CXX_COMPILER=dpcpp``.
+- `CMAKE_BUILD_TYPE <https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html>`_ - build type that affects optimization level and debug options; For example: ``CMAKE_BUILD_TYPE=Release``.
+- `CMAKE_CXX_STANDARD <https://cmake.org/cmake/help/latest/variable/CMAKE_CXX_STANDARD.html>`_ - C++ standard: ``CMAKE_CXX_STANDARD=17``.
+
+Requirements
+============
+The minimal supported CMake version for |onedpl_short| is 3.11 on Linux and 3.20 on Windows.
+
+The supported `CMake Generator <https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#ninja-generators>`_ for Linux is `Unix Makefiles <https://cmake.org/cmake/help/latest/generator/Unix%20Makefiles.html>`_ (default). In the Windows environment, the supported generator is `Ninja <https://cmake.org/cmake/help/latest/generator/Ninja.html>`_ as described in the `Intel® oneAPI DPC++/C++ Compiler Developer Guide and Reference <https://www.intel.com/content/www/us/en/docs/dpcpp-cpp-compiler/developer-guide-reference/current/use-cmake-with-the-compiler.html>`_ which may be specified via ``-GNinja``.
+
+|onedpl_short| Backend Options
+==============
+
+Backend for Parallel Execution Policies (par and par_unseq)
+-----------------------------------------------------------
+The |onedpl_short| backend for parallel execution policies controls how algorithms with parallel execution policies (``par`` or ``par_unseq``) are implemented. This option is controlled via the ``ONEDPL_PAR_BACKEND`` setting.
+
++--------------------+--------+--------+--------+
+| ONEDPL_PAR_BACKEND | oneTBB | OpenMP | Serial |
++====================+========+========+========+
+| [not set]          |     oneDPL heuristics    |
++--------------------+--------+--------+--------+
+| tbb                |   X    |        |        |
++--------------------+--------+--------+--------+
+| openmp             |        |    X   |        |
++--------------------+--------+--------+--------+
+| serial             |        |        |    X   |
++--------------------+--------+--------+--------+
+
+The |onedpl_short| heuristics are the following: the first suitable backend is chosen among ``oneTBB``, ``OpenMP`` and ``Serial``, in that order. If ``ONEDPL_PAR_BACKEND`` is specified, but the selected backend is not found or unsupported, |onedpl_short| is considered not found (``oneDPL_FOUND=False``).
+
+Backend for Device Execution Policies
+-----------------------------------------------------------
+The |onedpl_short| backend for device execution policies controls if device policies are enabled.
+
++-------------------+
+|       DPCPP       |
++===================+
+| oneDPL heuristics |
++-------------------+
+
+The heuristics are the following: ``DPCPP`` backend is enabled if the compiler supports ``-fsycl`` option and SYCL headers are available.
+
+For more details on |onedpl_short| backends, see :doc:`Execution Policies <parallel_api/execution_policies>`.
+
+Example CMake File
+==================
+To use |onedpl_short| with CMake, you must create a ``CMakeLists.txt`` file for your project and add |onedpl_short|. This file should be placed in the project's base directory. Below is an example ``CMakeLists.txt`` file:
+
+.. code:: cpp
+
+  if (CMAKE_HOST_WIN32)
+    find_package(oneDPLWindowsIntelLLVM)
+  endif()
+
+  project(Foo)
+  add_executable(foo foo.cpp)
+  
+  # Search to find oneDPL
+  find_package(oneDPL REQUIRED)
+  
+  # Connect oneDPL to foo
+  target_link_libraries(foo oneDPL)
+
+.. note::
+  On Windows, some workarounds may be required to use ``icx[-cl]`` successfully with |onedpl_short|. We recommend updating to the most recent version of CMake to minimize the workarounds required for successful use. A CMake package has been provided, ``oneDPLWindowsIntelLLVM``, to provide the necessary workarounds to enable support for ``icx[-cl]`` on Windows with CMake versions 3.20 and greater. Some workarounds are provided for ``icpx``, but it is not fully supported on Windows at this time. To use this package, please add ``find_package(oneDPLWindowsIntelLLVM)`` to your CMake file *before* you call ``project()``.
+
+
+Example CMake Invocation
+========================
+After creating a ``CMakeLists.txt`` file for your project, you may use a command line CMake invocation to generate build scripts.
+
+Below is an example ``Linux`` CMake invocation which generates Unix makefiles for the project with the ``icpx`` compiler, ``oneTBB`` backend and ``Release`` build type:
+
+.. code:: cpp
+
+  mkdir build && cd build
+  cmake -DCMAKE_CXX_COMPILER=icpx -DCMAKE_BUILD_TYPE=release -DONEDPL_PAR_BACKEND=tbb ..
+
+Below is an example ``Windows`` CMake invocation which generates ``Ninja`` build scripts (see :ref:`Requirements Section<Requirements>`) for the project in the parent directory with the ``icx`` compiler, ``OpenMP`` backend and ``debug`` build type:
+
+.. code:: cpp
+
+  mkdir build && cd build
+  cmake -GNinja -DCMAKE_CXX_COMPILER=icx -DCMAKE_BUILD_TYPE=debug -DONEDPL_PAR_BACKEND=openmp ..
+
+Both of these examples assume the starting working directory is the project's base directory which contains ``CMakeLists.txt``. The build scripts are generated in a newly created ``build`` directory.
+
+
+Example Build Command
+=====================
+Once build scripts have been generated for your desired configuration following the instruction above, a `build command <https://cmake.org/cmake/help/latest/manual/cmake.1.html#build-a-project>`_ can be issued to build your project:
+
+.. code:: cpp
+
+  cmake --build .
+
+This example assumes the starting working directory is in the directory which contains the CMake generated build scripts, ``build``, if following the instructions above.
diff --git a/_sources/index.rst.txt b/_sources/index.rst.txt
@@ -23,6 +23,7 @@ For general information, refer to the `oneDPL GitHub* repository
    parallel_api_main
    api_for_sycl_kernels_main
    macros
+   cmake_support
    oneDPL_2022.0_changes
 
 .. toctree::

diff --git a/_sources/introduction.rst.txt b/_sources/introduction.rst.txt
@@ -6,16 +6,16 @@ Policies <https://en.cppreference.com/w/cpp/algorithm/execution_policy_tag_t>`_
 to enable parallelism on the host.
 
 The |onedpl_long| (|onedpl_short|) is implemented in accordance with the `oneDPL
-Specification <https://spec.oneapi.com/versions/latest/elements/oneDPL/source/index.html>`_.
+Specification <https://spec.oneapi.io/versions/latest/elements/oneDPL/source/index.html>`_.
 
 To support heterogeneity, |onedpl_short| works with the DPC++ API. More information can be found in the
-`DPC++ Specification <https://spec.oneapi.com/versions/latest/elements/dpcpp/source/index.html#dpc>`_.
+`oneAPI Specification <https://spec.oneapi.io/versions/latest/elements/sycl/source/index.html>`_.
 
 Before You Begin
 ================
 
 Visit the |onedpl_short| `Release Notes
-<https://software.intel.com/content/www/us/en/develop/articles/intel-oneapi-dpcpp-library-release-notes.html>`_
+<https://www.intel.com/content/www/us/en/developer/articles/release-notes/intel-oneapi-dpcpp-library-release-notes.html>`_
 page for:
 
 * Where to Find the Release
@@ -26,7 +26,7 @@ page for:
 * Known Issues and Limitations
 * Previous Release Notes 
 
-Install the `Intel® oneAPI Base Toolkit (Base Kit) <https://software.intel.com/en-us/oneapi/base-kit>`_
+Install the `Intel® oneAPI Base Toolkit (Base Kit) <https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit.html#gs.xaontv>`_
 to use |onedpl_short|.
 
 All |onedpl_short| header files are in the ``oneapi/dpl`` directory. To use the |onedpl_short| API,
@@ -132,7 +132,7 @@ Build Your Code with |onedpl_short|
 Follow the steps below to build your code with |onedpl_short|:
 
 #. To build with the |dpcpp_cpp|, see the `Get Started with the Intel® oneAPI DPC++/C++ Compiler
-   <https://software.intel.com/content/www/us/en/develop/documentation/get-started-with-dpcpp-compiler/top.html>`_
+   <https://www.intel.com/content/www/us/en/docs/dpcpp-cpp-compiler/get-started-guide/current/overview.html>`_
    for details.
 #. Set the environment variables for |onedpl_short| and |onetbb_short|.
 #. To avoid naming device policy objects explicitly, add the ``-fsycl-unnamed-lambda`` option.
@@ -144,4 +144,4 @@ Below is an example of a command line used to compile code that contains
 
   dpcpp [-fsycl-unnamed-lambda] test.cpp [-ltbb|-fopenmp] -o test
 
-.. _`Intel® oneAPI Threading Building Blocks (oneTBB) Release Notes`: https://software.intel.com/content/www/us/en/develop/articles/intel-oneapi-threading-building-blocks-release-notes.html
+.. _`Intel® oneAPI Threading Building Blocks (oneTBB) Release Notes`: https://www.intel.com/content/www/us/en/developer/articles/release-notes/intel-oneapi-threading-building-blocks-release-notes.html
diff --git a/_sources/introduction/onedpl_gsg.rst.txt b/_sources/introduction/onedpl_gsg.rst.txt
@@ -2,7 +2,7 @@ Get Started with the |onedpl_long|
 ##################################
 
 |onedpl_long| (|onedpl_short|) works with the
-`Intel® oneAPI DPC++/C++ Compiler <https://software.intel.com/content/www/us/en/develop/documentation/get-started-with-dpcpp-compiler/top.html>`_
+`Intel® oneAPI DPC++/C++ Compiler <https://www.intel.com/content/www/us/en/docs/dpcpp-cpp-compiler/get-started-guide/current/overview.html>`_
 to provide high-productivity APIs to developers, which can minimize SYCL*
 programming efforts across devices for high performance parallel applications.
 
@@ -14,14 +14,17 @@ programming efforts across devices for high performance parallel applications.
 
 
 For general information about |onedpl_short|, visit the `oneDPL GitHub* repository <https://github.com/oneapi-src/oneDPL>`_,
-or visit the `Intel® oneAPI DPC++ Library Guide <https://software.intel.com/content/www/us/en/develop/documentation/oneapi-dpcpp-library-guide/top.html>`_
-and the `Intel® oneAPI DPC++ Library main page <https://software.intel.com/content/www/us/en/develop/tools/oneapi/components/dpc-library.html>`_.
+or visit the `Intel® oneAPI DPC++ Library Guide <https://www.intel.com/content/www/us/en/docs/onedpl/developer-guide/current/overview.html>`_
+and the `Intel® oneAPI DPC++ Library main page <https://www.intel.com/content/www/us/en/developer/tools/oneapi/dpc-library.html>`_.
 
-Before You Begin
-================
+Quick Start
+===========
+
+Installation
+------------
 
 Visit the |onedpl_short| `Release Notes
-<https://software.intel.com/content/www/us/en/develop/articles/intel-oneapi-dpcpp-library-release-notes.html>`_
+<https://www.intel.com/content/www/us/en/developer/articles/release-notes/intel-oneapi-dpcpp-library-release-notes.html>`_
 page for:
 
 * Where to Find the Release
@@ -30,7 +33,7 @@ page for:
 * Fixed Issues
 * Known Issues and Limitations
 
-Install the `Intel® oneAPI Base Toolkit (Base Kit) <https://software.intel.com/en-us/oneapi/base-kit>`_
+Install the `Intel® oneAPI Base Toolkit (Base Kit) <https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit.html>`_
 to use |onedpl_short|.
 
 To use Parallel API, include the corresponding header files in your source code.
@@ -41,42 +44,80 @@ All |onedpl_short| header files are in the ``oneapi/dpl`` directory. Use ``#incl
 To use tested C++ standard APIs, you need to include the corresponding C++ standard header files
 and use the ``std`` namespace.
 
+CMake Support
+-------------
+`CMake <https://cmake.org/cmake/help/latest/index.html>`_ generates build scripts which can then be used to build and link your application. |onedpl_short| can be added to your project via CMake.
+
+A simple example for Linux is provided below. For more detailed usage and options including details specific to Windows, please look to the `CMake Support Page <https://oneapi-src.github.io/oneDPL/cmake-support.html>`_.
+
+Simple Example CMake File
+*************************
+To use |onedpl_short| with CMake, create a CMakeLists.txt file for your project's base directory and use `find_package <https://cmake.org/cmake/help/latest/command/find_package.html>`_ and `target_link_libraries <https://cmake.org/cmake/help/latest/command/target_link_libraries.html>`_ to add oneDPL.
+For example:
+
+.. code:: cpp
+
+  project(Foo)
+  add_executable(foo foo.cpp)
+  
+  # Search to find oneDPL
+  find_package(oneDPL REQUIRED)
+  
+  # Connect oneDPL to foo
+  target_link_libraries(foo oneDPL)
+
+Simple Example CMake Invocation
+*******************************
+The following is an example CMake invocation which generates build scripts for the project in the parent directory: 
+
+.. code:: cpp
+
+  mkdir build && cd build
+  cmake -DCMAKE_CXX_COMPILER=icpx -DCMAKE_BUILD_TYPE=release ..
+
+Example Build Command
+*********************
+Once build scripts have been generated for your desired configuration following the instruction above, a `build command <https://cmake.org/cmake/help/latest/manual/cmake.1.html#build-a-project>`_ can be issued to build your project:
+
+.. code:: cpp
+
+  cmake --build .
 
 pkg-config Support
-==================
+------------------
 
 The pkg-config program is used to retrieve information about your installed libraries, and
 to compile and link against one or more libraries.
 
 Use pkg-config with |onedpl_short|
-----------------------------------
+**********************************
 
 Use pkg-config with the ``--cflags`` flag to get the include path to the oneDPL directory:
 
 .. code:: cpp
 
-  dpcpp test.cpp $(pkg-config --cflags dpl)
+  icpx -fsycl foo.cpp $(pkg-config --cflags dpl)
   
 The ``--msvc-syntax`` flag is required when you use a Microsoft Visual C++* compiler.
 This flag converts your compiling and linking flags to the appropriate form:
 
 .. code:: cpp
 
-  dpcpp test.cpp $(pkg-config --msvc-syntax --cflags dpl)
+  icpx -fsycl foo.cpp $(pkg-config --msvc-syntax --cflags dpl)
 
 .. note::
   Use the pkg-config tool to get rid of large hard-coded paths and make compilation more portable.
 
 
 Usage Examples
-==============
+--------------
 
 |onedpl_short| sample code is available from the
 `oneAPI GitHub samples repository <https://github.com/oneapi-src/oneAPI-samples/tree/master/Libraries/oneDPL>`_.
 Each sample includes a readme with build instructions.
 
 \<oneapi/dpl/random\> Header Usage Example
-------------------------------------------
+******************************************
 
 This example illustrates |onedpl_short| random number generator usage.
 The sample below shows you how to create an random number generator engine object (the source of pseudo-randomness),
@@ -107,7 +148,7 @@ This example performs its computations on your default SYCL device. You can set
     }
 
 Pi Benchmark Usage Example
---------------------------
+**************************
 
 This example uses a Monte Carlo method to estimate the value of π.
 The basic idea is to generate random points within a square, and to check what
@@ -162,13 +203,13 @@ Find More
 
    * - Resource Link
      - Description
-   * - `Intel® oneAPI DPC++ Library Guide <https://software.intel.com/content/www/us/en/develop/documentation/oneapi-dpcpp-library-guide/top.html>`_
+   * - `Intel® oneAPI DPC++ Library Guide <https://www.intel.com/content/www/us/en/docs/onedpl/developer-guide/current/overview.html>`_
      - Refer to the |onedpl_short| guide for  more in depth information.
-   * - `System Requirements <https://software.intel.com/content/www/us/en/develop/articles/intel-oneapi-dpcpp-system-requirements.html>`_
+   * - `System Requirements <https://www.intel.com/content/www/us/en/developer/articles/system-requirements/intel-oneapi-dpcpp-system-requirements.html>`_
      - Check system requirements before you install |onedpl_short|.
-   * - `Intel® oneAPI DPC++ Library Release Notes <https://software.intel.com/content/www/us/en/develop/articles/intel-oneapi-dpcpp-library-release-notes.html>`_
+   * - `Intel® oneAPI DPC++ Library Release Notes <https://www.intel.com/content/www/us/en/developer/articles/release-notes/intel-oneapi-dpcpp-library-release-notes.html>`_
      - Check the release notes to learn about updates in the latest release.
    * - `oneDPL Samples <https://github.com/oneapi-src/oneAPI-samples/tree/master/Libraries/oneDPL>`_
      - Learn how to use |onedpl_short| with samples.
-   * - `Layers for Yocto* Project <https://www.intel.com/content/www/us/en/develop/documentation/get-started-with-intel-oneapi-iot-linux/top/adding-oneapi-components-to-yocto-project-builds.html>`_
+   * - `Layers for Yocto* Project <https://www.intel.com/content/www/us/en/docs/oneapi-iot-toolkit/get-started-guide-linux/current/adding-oneapi-components-to-yocto-project-builds.html>`_
      - Add oneAPI components to a Yocto project build using the meta-intel layers.
diff --git a/_sources/macros.rst.txt b/_sources/macros.rst.txt
@@ -40,11 +40,7 @@ Macro                              Description
                                    are executed with unsequenced policies.
                                    For further details about the pragma,
                                    see the `vector page in the Intel® oneAPI DPC++/C++ Compiler Developer Guide and Reference
-                                   <https://software.intel.com/
-                                   content/www/us/en/develop/documentation/
-                                   oneapi-dpcpp-cpp-compiler-dev-guide-and-reference/top/
-                                   compiler-reference/pragmas/
-                                   intel-specific-pragma-reference/vector.html>`_.
+                                   <https://www.intel.com/content/www/us/en/docs/dpcpp-cpp-compiler/developer-guide-reference/current/vector.html>`_.
                                    If the macro evaluates to a non-zero value,
                                    the use of ``#pragma vector nontemporal`` is enabled.
                                    By default, the macro is not defined.