Remove thrust_set_libcudacxx_target function from CMake user API.

There's no way for a user to meaningfully use this, since libcudacxx
is a required dependency. It is checked during the initial
`find_package(Thrust)` call, before the user would have access to
Thrust's CMake API.

Updated the CMake README.md with instructions for using an explicit
libcudacxx target.

thrust/cmake/README.md

@@ -101,7 +101,7 @@ find_package(Thrust 1.9.10.1 EXACT)
 
 would only match the 1.9.10.1 release.
 
-#### Using a Specific TBB or OpenMP Environment
+#### Using an Explicit TBB or OpenMP CMake Target
 
 When `thrust_create_target` is called, it will lazily load the requested
 systems on-demand through internal `find_package` calls. If a project already
@@ -112,9 +112,20 @@ thrust_set_TBB_target(MyTBBTarget)
 thrust_set_OMP_target(MyOMPTarget)
 ```
 
-These functions must be called **before** `thrust_create_target`, and will
-have no effect if the dependency is loaded as a
-`find_package(Thrust COMPONENT [...])` component.
+These functions must be called **before** the corresponding system is loaded
+through `thrust_create_target` or `find_package(Thrust COMPONENT [OMP|TBB])`.
+
+#### Using an Explicit libcu++ CMake Target
+
+In contrast to the optional TBB/OMP dependencies, there is no
+`thrust_set_libcudacxx_target` function that specifies an explicit libcu++
+target. This is because libcu++ is always required and must be found during the
+initial `find_target(Thrust)` call that defines these functions.
+
+To force Thrust to use a specific libcu++ target, ensure that either the
+`Thrust::libcudacxx` or `libcudacxx::libcudacxx` targets are defined prior to
+the first invocation of `find_package(Thrust)`. Thrust will automatically use
+these, giving preference to the `Thrust::libcudacxx` target.
 
 #### Testing for Systems
 

thrust/cmake/thrust-config.cmake

@@ -37,15 +37,14 @@
 #   [ADVANCED]                       # Optionally mark options as advanced
 # )
 #
-# # Use a custom TBB, CUB, libcudacxx, and/or OMP
+# # Use a custom TBB, CUB, and/or OMP
 # # (Note that once set, these cannot be changed. This includes COMPONENT
 # # preloading and lazy lookups in thrust_create_target)
 # find_package(Thrust REQUIRED)
 # thrust_set_CUB_target(MyCUBTarget)  # MyXXXTarget contains an existing
 # thrust_set_TBB_target(MyTBBTarget)  # interface to XXX for Thrust to use.
-# thrust_set_libcudacxx_target(MyLibcudacxxTarget)
 # thrust_set_OMP_target(MyOMPTarget)
-# thrust_create_target(ThrustWithMyCUBAndLibcudacxx DEVICE CUDA)
+# thrust_create_target(ThrustWithMyCUB DEVICE CUDA)
 # thrust_create_target(ThrustWithMyTBB DEVICE TBB)
 # thrust_create_target(ThrustWithMyOMP DEVICE OMP)
 #
@@ -460,9 +459,10 @@ function(thrust_set_CUB_target cub_target)
   endif()
 endfunction()
 
-# Use the provided libcudacxx_target for the CUDA backend. If Thrust::libcudacxx
-# already exists, this call has no effect.
-function(thrust_set_libcudacxx_target libcudacxx_target)
+# Internal use only -- libcudacxx must be found during the initial
+# `find_package(Thrust)` call and cannot be set afterwards. See README.md in
+# this directory for details on using a specific libcudacxx target.
+function(_thrust_set_libcudacxx_target libcudacxx_target)
   if (NOT TARGET Thrust::libcudacxx)
     thrust_debug("Setting libcudacxx target to ${libcudacxx_target}" internal)
     # Workaround cmake issue #20670 https://gitlab.kitware.com/cmake/cmake/-/issues/20670
@@ -712,7 +712,7 @@ if (NOT TARGET Thrust::libcudacxx)
   )
 
   if (TARGET libcudacxx::libcudacxx)
-    thrust_set_libcudacxx_target(libcudacxx::libcudacxx)
+    _thrust_set_libcudacxx_target(libcudacxx::libcudacxx)
   else()
     thrust_debug("Expected libcudacxx::libcudacxx target not found!" internal)
   endif()