[clang] [Clang] [Docs] Add some CMake example code for linking against libclang (PR #166268)

[via cfe-commits]

https://github.com/Sirraide created https://github.com/llvm/llvm-project/pull/166268

Though we have a few code examples in our documentation that show how to *use* libclang, we never actually show how to *link* against it. I myself mostly figured this out through trial and error some time ago, and I’ve since had to explain it to others on several occasions, so I thought adding some very minimal CMake example code might be helpful.

>From 502d608172f750daee2aadb33032f557551d3df3 Mon Sep 17 00:00:00 2001
From: Sirraide <aeternalmail at gmail.com>
Date: Tue, 4 Nov 2025 00:17:30 +0100
Subject: [PATCH 1/3] [Clang] [Docs] Add some CMake example code for linking
 against libclang

---
 clang/docs/LibClang.rst | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/clang/docs/LibClang.rst b/clang/docs/LibClang.rst
index e747022b9c173..d68a5541f835f 100644
--- a/clang/docs/LibClang.rst
+++ b/clang/docs/LibClang.rst
@@ -38,6 +38,7 @@ Code example
 
 .. code-block:: cpp
 
+  // main.cpp
   #include <clang-c/Index.h>
   #include <iostream>
 
@@ -57,6 +58,18 @@ Code example
     CXCursor cursor = clang_getTranslationUnitCursor(unit); //Obtain a cursor at the root of the translation unit
   }
 
+.. code-block:: cmake
+
+  # CMakeLists.txt
+  cmake_minimum_required(VERSION 3.30)
+  project(my_clang_tool VERSION 0.1.0)
+
+  find_package(Clang CONFIG REQUIRED)
+
+  add_executable(my_clang_tool main.cpp)
+  target_include_directories(my_clang_tool PRIVATE ${CLANG_INCLUDE_DIRS})
+  target_link_libraries(my_clang_tool PRIVATE libclang)
+
 Visiting elements of an AST
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The elements of an AST can be recursively visited with pre-order traversal with ``clang_visitChildren``.
@@ -283,6 +296,7 @@ Complete example code
 
 .. code-block:: cpp
 
+  // main.cpp
   #include <clang-c/Index.h>
   #include <iostream>
 
@@ -356,6 +370,17 @@ Complete example code
     );
   }
 
+.. code-block:: cmake
+
+  # CMakeLists.txt
+  cmake_minimum_required(VERSION 3.30)
+  project(my_clang_tool VERSION 0.1.0)
+
+  find_package(Clang CONFIG REQUIRED)
+
+  add_executable(my_clang_tool main.cpp)
+  target_include_directories(my_clang_tool PRIVATE ${CLANG_INCLUDE_DIRS})
+  target_link_libraries(my_clang_tool PRIVATE libclang)
 
 .. _Index.h: https://github.com/llvm/llvm-project/blob/main/clang/include/clang-c/Index.h
 

>From fc669e065fd3ba13d9bd19c3baf9d3f1c0e7defe Mon Sep 17 00:00:00 2001
From: Sirraide <aeternalmail at gmail.com>
Date: Tue, 4 Nov 2025 00:23:03 +0100
Subject: [PATCH 2/3] Set CMake version requirement to 3.20 to match our
 CMakeLists.txt

---
 clang/docs/LibClang.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/clang/docs/LibClang.rst b/clang/docs/LibClang.rst
index d68a5541f835f..95c8bcf696d66 100644
--- a/clang/docs/LibClang.rst
+++ b/clang/docs/LibClang.rst
@@ -61,7 +61,7 @@ Code example
 .. code-block:: cmake
 
   # CMakeLists.txt
-  cmake_minimum_required(VERSION 3.30)
+  cmake_minimum_required(VERSION 3.20)
   project(my_clang_tool VERSION 0.1.0)
 
   find_package(Clang CONFIG REQUIRED)
@@ -373,7 +373,7 @@ Complete example code
 .. code-block:: cmake
 
   # CMakeLists.txt
-  cmake_minimum_required(VERSION 3.30)
+  cmake_minimum_required(VERSION 3.20)
   project(my_clang_tool VERSION 0.1.0)
 
   find_package(Clang CONFIG REQUIRED)

>From d27525bc034fa841cf3c2826fbc770921c659b98 Mon Sep 17 00:00:00 2001
From: Sirraide <aeternalmail at gmail.com>
Date: Tue, 4 Nov 2025 00:49:17 +0100
Subject: [PATCH 3/3] Add some information on how to use a custom build of
 clang

---
 clang/docs/LibClang.rst | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/clang/docs/LibClang.rst b/clang/docs/LibClang.rst
index 95c8bcf696d66..6c62bcb5f8c29 100644
--- a/clang/docs/LibClang.rst
+++ b/clang/docs/LibClang.rst
@@ -64,6 +64,10 @@ Code example
   cmake_minimum_required(VERSION 3.20)
   project(my_clang_tool VERSION 0.1.0)
 
+  # This will find the default system installation of Clang; if you want to
+  # use a different build of clang, pass -DClang_DIR=/foobar/lib/cmake/clang
+  # to the CMake configure command, where /foobar is the build directory where
+  # you built Clang.
   find_package(Clang CONFIG REQUIRED)
 
   add_executable(my_clang_tool main.cpp)
@@ -376,6 +380,10 @@ Complete example code
   cmake_minimum_required(VERSION 3.20)
   project(my_clang_tool VERSION 0.1.0)
 
+  # This will find the default system installation of Clang; if you want to
+  # use a different build of clang, pass -DClang_DIR=/foobar/lib/cmake/clang
+  # to the CMake configure command, where /foobar is the build directory where
+  # you built Clang.
   find_package(Clang CONFIG REQUIRED)
 
   add_executable(my_clang_tool main.cpp)