[rocm-libraries] ROCm/rocm-libraries#5074 (commit 66e3be7)

[rocthrust] adding the updated backend build info into the
 documentation (#5074)

## Motivation

The backend build information was removed from the documentation
previously because it was incorrect. This PR reintroduces the topic with
updated information.

This is the companion to #4983 and shouldn't be merged in before 4983 is
merged in.

Author: spolifroni-amd

docs/how-to/rocThrust-build-for-backends.rst

@@ -0,0 +1,95 @@
+.. meta::
+  :description: Building rocThrust for different backends
+  :keywords: rocThrust, ROCm, HIPSTDPAR, installation
+
+*******************************************
+Building rocThrust for different backends
+*******************************************
+
+API calls can run either on the device (GPU) system or on the host (CPU) system. The system on which computations are run depends on the execution policy used in the code, as well as the options that were set when rocThrust was :doc:`built and installed <../install/rocThrust-install-overview>`. 
+
+Two build options are used to set the backend when the different execution policies are used. ``THRUST_DEVICE_SYSTEM`` sets the backend for the ``thrust::device`` execution policy and  ``THRUST_HOST_SYSTEM`` sets the backend for the ``thrust::host`` policy.
+
+The options for ``THRUST_DEVICE_SYSTEM`` are:
+
+.. list-table:: 
+    :widths: 20 80
+    :header-rows: 1
+
+    * - Backend
+      - Description
+
+    * - ``HIP``
+      - | `HIP <https://rocm.docs.amd.com/projects/HIP/en/latest/index.html>`_ backend for device acceleration. 
+        | Requires a HIP-aware clang compiler such as hipcc. 
+        | Default setting.
+
+    * - ``TBB``
+      - | |oneTBB|_ backend. 
+        | Parallelizes computations on the host using oneTBB with no device acceleration. 
+        | Requires a compiler that supports oneTBB.
+
+    * - ``OMP``
+      - | |OMP|_ backend. 
+        | Parallelizes computations on the host using OpenMP with no device acceleration. 
+        | Requires a compiler that supports OpenMP.
+
+    * - ``CPP``
+      - | Uses the g++ or clang++ compiler, and the standard C++ library. 
+        | Forces sequential computation on the host with no device acceleration.
+
+
+.. note:: 
+
+    rocThrust examples and benchmarks require device acceleration. rocThrust must be built with ``THRUST_DEVICE_SYSTEM=HIP`` to use its examples and benchmarks.
+
+The options for ``THRUST_HOST_SYSTEM`` are:
+
+.. list-table:: 
+    :widths: 20 80
+    :header-rows: 1
+
+    * - Backend
+      - Description 
+
+    * - ``CPP``
+      - | The standard C++ library. 
+        | Uses the g++ or clang++ compiler for sequential computations on the host with no device acceleration. 
+        | Default setting.
+
+    * - ``OMP`` 
+      - | OpenMP backend. 
+        | Parallelizes host-side operations using OpenMP. 
+        | Requires a compiler that supports OpenMP.
+
+    * - ``TBB`` 
+      - | oneTBB backend. 
+        | Parallelizes host-side operations using oneTBB.
+        | Requires a compiler that supports oneTBB.
+
+.. note::
+
+    If ``THRUST_DEVICE_SYSTEM`` is set to ``OMP``, ``TBB``, or ``CPP``, then ``THRUST_HOST_SYSTEM`` must be set to the same backend.
+
+rocThrust will link to the rocPRIM libraries even when the ``thrust::host`` execution policy is used and ``THRUST_DEVICE_SYSTEM`` is set to ``OMP``, ``TBB``, or ``CPP``. For full host-side execution, without linking to rocPRIM, rocThrust must be built with ``LINK_HIP_DEVICE_LIBS=OFF``.  Setting ``LINK_HIP_DEVICE_LIBS=OFF`` at build time will prevent rocThrust from linking to the rocPRIM libraries.
+
+When rocThrust is built with ``LINK_HIP_DEVICE_LIBS=OFF``, the ``thrust::device`` policy will be ignored and the API calls will run on the host device.
+
+For example, to build rocThrust with no device acceleration, using only the g++ compiler:
+
+.. code:: shell
+
+    `ROCM_PATH=/opt/rocm CXX=g++ cmake -B build -DBUILD_BENCHMARK=OFF -DBUILD_TEST=OFF -DTHRUST_HOST_SYSTEM=CPP -DTHRUST_DEVICE_SYSTEM=CPP -DLINK_HIP_DEVICE_LIBS=OFF`
+ 
+For more information about build options and how to set them, see :doc:`building rocThrust with CMake <../install/rocThrust-install-with-cmake>` and :doc:`building rocThrust with rmake <../install/rocThrust-rmake-install>`.
+
+
+.. |reg| raw:: html
+
+    &reg;
+
+.. |oneTBB| replace:: Intel\ |reg| oneAPI Threading Building Blocks (oneTBB)
+.. _oneTBB: https://www.intel.com/content/www/us/en/developer/tools/oneapi/onetbb.html
+
+.. |OMP| replace:: OpenMP\ |reg| 
+.. _OMP: https://www.openmp.org

docs/index.rst

@@ -25,6 +25,7 @@ The rocThrust project is located in https://github.com/ROCm/rocm-libraries/tree/
 
   .. grid-item-card:: How to
 
+    * :doc:`Build rocThrust for different backends <./how-to/rocThrust-build-for-backends>`
     * :doc:`Add rocThrust to a CMake project <./how-to/use-rocThrust-in-a-project>`
     * :doc:`Run tests on multiple GPUs <./how-to/run-rocThrust-tests-on-multiple-gpus>`
     * :doc:`Use HIPSTDPAR <./how-to/rocThrust-hipstdpar>`

docs/install/rocThrust-rmake-install.rst

@@ -24,6 +24,12 @@ The ``-c`` option builds all clients, including the unit tests:
 
     python rmake.py -c
 
+:doc:`CMake build options <./rocThrust-install-with-cmake>` can be passed to the ``rmake.py`` script using the ``--cmake-darg`` option:
+
+.. code:: shell 
+
+    python rmake.py -ci --cmake-darg THRUST_HOST_SYSTEM=OMP --cmake-darg THRUST_DEVICE_SYSTEM=OMP
+
 To see a complete list of ``rmake.py`` options, run:
 
 .. code-block:: shell

docs/sphinx/_toc.yml.in

@@ -20,6 +20,8 @@ subtrees:
 
 - caption: How to
   entries:
+  - file: how-to/rocThrust-build-for-backends.rst
+    title: Build for different backends
   - file: how-to/use-rocThrust-in-a-project.rst
     title: Add rocThrust to a CMake project
   - file: how-to/run-rocThrust-tests-on-multiple-gpus