[llvm] [llvm][doc][cmake] Use llvm_config instead of llvm_map_components_to_libnames (llvm#34593) (PR #82765)

[Yanglin Xun via llvm-commits]

https://github.com/FurryAcetylCoA created https://github.com/llvm/llvm-project/pull/82765

As discussed in #34593. `llvm_map_components_to_libnames` can not handle LLVM builds with `LLVM_LINK_LLVM_DYLIB`.  And it's recommended to use llvm_config instead.

However, I question the necessity of checking `USE_SHARED` within `llvm_config`. As I can't envision scenarios where `USE_SHARED` is not desired by users ( which  is equivalent to directly calling `explicit_llvm_config`). See foutrelis' [comment](https://reviews.llvm.org/D44391#1036104).
Given this, I propose combining `llvm_config` and `explicit_llvm_config` into one. But this will makes another PR and I'm not sure how to thoroughly test such a change.

closes #34593  closes #82266

>From a873d1876aaa8628e582b5809973577a575568ca Mon Sep 17 00:00:00 2001
From: Yanglin Xun <68182718+FurryAcetylCoA at users.noreply.github.com>
Date: Fri, 23 Feb 2024 21:06:09 +0800
Subject: [PATCH] [llvm] [doc] [cmake] Use llvm_config instead of
 llvm_map_components_to_libnames (llvm#34593))

llvm_map_components_to_libnames can not handle llvm built with LLVM_LINK_LLVM_DYLIB.
---
 llvm/docs/CMake.rst | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/llvm/docs/CMake.rst b/llvm/docs/CMake.rst
index abef4f8103140f..f72c17d3370c02 100644
--- a/llvm/docs/CMake.rst
+++ b/llvm/docs/CMake.rst
@@ -987,12 +987,10 @@ and uses them to build a simple application ``simple-tool``.
   # Now build our tools
   add_executable(simple-tool tool.cpp)
 
-  # Find the libraries that correspond to the LLVM components
-  # that we wish to use
-  llvm_map_components_to_libnames(llvm_libs support core irreader)
+  # Link against the libraries that correspond to the 
+  # LLVM components that we wish to use.
+  llvm_config(simple-tool USE_SHARED support core irreader)
 
-  # Link against LLVM libraries
-  target_link_libraries(simple-tool ${llvm_libs})
 
 The ``find_package(...)`` directive when used in CONFIG mode (as in the above
 example) will look for the ``LLVMConfig.cmake`` file in various locations (see
@@ -1051,13 +1049,15 @@ include
   The path to the directory containing the LLVM tools (e.g. ``llvm-as``).
 
 Notice that in the above example we link ``simple-tool`` against several LLVM
-libraries. The list of libraries is determined by using the
-``llvm_map_components_to_libnames()`` CMake function. For a list of available
-components look at the output of running ``llvm-config --components``.
+libraries. The list of libraries is determined inside the ``llvm_config()`` 
+CMake macro. For a list of available components look at the output of 
+running ``llvm-config --components``.
+
+The ``llvm_config()`` macro behave similarly to ``llvm-config --libs`` when 
+``USE_SHARED`` is provided. When using with LLVM built with 
+``LLVM_LINK_LLVM_DYLIB = on`` and ``LLVM_DYLIB_COMPONENTS = all`` , 
+the components list can be omitted.
 
-Note that for LLVM < 3.5 ``llvm_map_components_to_libraries()`` was
-used instead of ``llvm_map_components_to_libnames()``. This is now deprecated
-and will be removed in a future version of LLVM.
 
 .. _cmake-out-of-source-pass: