[CMake Advanced Tips] How to create a universal library search template?

---

1. Introduction

In modern software development, build tools have become an integral part of every developer's workflow. CMake, as a cross-platform build system (Cross-platform build system), is undoubtedly the best among them. However, despite the powerful functionality and flexibility it provides developers, many developers have encountered a common problem during use: how to effectively find and introduce external libraries?

1.1 The Importance and Popularity of CMake

As Bjarne Stroustrup said in "The C++ Programming Language": "Tools and environment have an equally important impact on programming." CMake provides us with a unified and efficient environment to configure and manage the project's build process. It eliminates the differences between different platforms and compilers, allowing code to compile and run smoothly almost anywhere.

In the world of CMake, finding libraries is a core concept. why? Because most software projects rely on some external libraries, these libraries provide many predefined functions and interfaces so that developers can complete their work more efficiently. But how do you ensure that these libraries are found and linked correctly in various environments?

1.2 The Challenge of Finding Libraries

Finding a library seems to be a simple task: specify a path and tell CMake where to look. However, the reality is far more complex than this. Finding the library correctly becomes even more difficult, considering that the library may exist on different operating systems, different architectures, or different compilation configurations.

Additionally, there may be multiple versions of the same library. Some versions may be optimized for specific hardware or operating systems, while other versions may contain new features or fix known bugs. How can I ensure that CMake always finds the correct version and is compatible with other libraries?

These issues require in-depth discussion and understanding, but before that, we must first understand the basic principles of the search library.

1.3 Overview and Goals of the Article

The main purpose of this article is to delve into the library lookup mechanism in CMake, explain the principles behind it, and provide a general, template-based approach to simplify and automate this process.

We'll start with the basics of CMake, work our way into its core concepts, and then cover how to create a universal library lookup template. pkg-configAdditionally, we will explore how to enhance and refine our finding strategies in conjunction with other tools, e.g.

Ultimately, we hope that readers will better understand how CMake works, master its advanced features, and be able to effectively find and manage external libraries in their own projects.

2. CMake and the Basics of Library Finding

---

2.1 find_library 函数简介 (Introduction to the find_library Function)

在CMake的世界中，我们经常需要将第三方库或自定义库与我们的项目链接。为了实现这一点，CMake为我们提供了一个强大的工具：find_library函数。

find_library函数的主要作用是在指定的路径或系统默认路径中查找库文件。例如，我们想要查找名为"example"的库，在UNIX系统上，这通常是一个名为libexample.so或libexample.a的文件。

find_library(EXAMPLE_LIBRARY NAMES example)

这条命令会设置一个变量EXAMPLE_LIBRARY，如果找到库，它会包含库的完整路径。正如Bjarne Stroustrup在《The C++ Programming Language》中所说：“工具的正确使用可以提高生产力和代码质量。”

但是，简单地使用find_library函数并不总是能满足我们的需求。我们可能需要指定库的查找路径，或者需要处理静态库和动态库的区别。

---

2.2 默认库查找路径的问题 (Issues with Default Library Search Paths)

find_library函数默认会在系统的标准库路径中查找，例如/usr/lib/和/usr/local/lib/。但是，当我们的库存放在非标准路径下，或者我们有多个版本的同一个库时，这就可能导致问题。

我们的大脑经常需要在大量的信息中筛选和选择，这与CMake在查找库时所面临的挑战类似。当存在多个选择时，我们需要为CMake提供明确的指导，以确保它选择正确的库版本。

---

2.3 如何自定义库查找路径 (Customizing Library Search Paths)

幸运的是，find_library提供了PATHS选项，允许我们指定额外的查找路径。

find_library(EXAMPLE_LIBRARY NAMES example PATHS /path/to/my/libs)

这会使CMake首先在/path/to/my/libs目录下查找example库，然后再查找系统默认路径。我们可以使用多个PATHS来指定多个查找路径。

但是，此方法还不够通用。考虑到不同的操作系统、编译器和架构，我们可能需要考虑多个可能的路径。这就需要我们创建一个更为通用和灵活的库查找模板。

3. 构建通用的库查找模板 (Crafting the Universal Library Finder Template)

当我们想要使用一个库时，通常的做法是直接指定库的路径和头文件，然后将其链接到我们的项目中。但随着项目的增长和跨多种操作系统和硬件架构的需求，这种方法显得不够灵活。正如Bjarne Stroustrup在《The C++ Programming Language》中所说：“我们应该编写代码，让计算机为我们做更多的工作。” 于是，我们需要一个更智能、更自动化的方式来查找和链接库。

3.1 动态构建库查找路径 (Dynamically Constructing the Library Search Path)

在CMake中，我们可以利用各种变量来构建库的查找路径。例如，考虑到不同的操作系统和硬件架构，库的路径可能会有所不同。

if(COMPILER_SYSTEM_WINDOWS)
    set(LIB_PATH ${CMAKE_SOURCE_DIR}/third_party/win/${LIB_NAME})
elseif(COMPILER_SYSTEM_LINUX)
    if(COMPILER_ARCH_AARCH64)
        set(LIB_PATH ${CMAKE_SOURCE_DIR}/third_party/aarch64/${LIB_NAME})
    else()
        set(LIB_PATH ${CMAKE_SOURCE_DIR}/third_party/x86_64/${LIB_NAME})
    endif()
endif()

在上述代码中，我们根据不同的操作系统和硬件架构动态地设置了库的查找路径。这种方法不仅使代码更加清晰和简洁，还使得库查找更加灵活和高效。

3.2 静态库与动态库的区别 (Distinguishing Between Static and Shared Libraries)

在编程中，我们经常遇到两种类型的库：静态库和动态库。这两者的主要区别在于链接方式和运行时行为。正如Bjarne Stroustrup在《The Design and Evolution of C++》中所说：“选择正确的工具对于任务的成功至关重要。”

string(SUBSTRING ${LIB_NAME} 0 3 LIB_NAME_PREFIX)
if(NOT ${LIB_NAME_PREFIX} STREQUAL "lib")
    set(LIB_NAME "lib${LIB_NAME}")
endif()

if(${LIB_TYPE} STREQUAL "STATIC")
    find_library(LIB_PATH NAMES ${LIB_NAME}.a PATHS ${SEARCH_PATH})
elseif(${LIB_TYPE} STREQUAL "SHARED")
    find_library(LIB_PATH NAMES ${LIB_NAME}.so PATHS ${SEARCH_PATH})
endif()

上述代码首先检查库名称是否以“lib”开头，然后根据库类型（静态或动态）查找适当的文件。

3.3 结合pkg-config增强查找 (Enhancing the Search with pkg-config)

pkg-config是一个帮助我们在构建过程中查询已安装库的详细信息的工具。正如Bjarne Stroustrup在《Programming: Principles and Practice Using C++》中所说：“有时候，最好的工具就在你的手边。”

find_package(PkgConfig REQUIRED)
pkg_check_modules(LIB_PKG_CONFIG ${LIB_NAME})
if(LIB_PKG_CONFIG_FOUND)
    set(LIB_PATH ${LIB_PKG_CONFIG_LIBDIR})
endif()

上述代码首先使用find_package来查找pkg-config工具。然后，我们使用pkg_check_modules来查询库的信息。如果查询成功，我们可以直接使用查询到的库路径。

在构建复杂的CMake项目时，组合多种策略和工具可以帮助我们更有效地查找和链接库。通过构建这种通用的库查找模板，我们可以确保代码更加干净、有序，同时也提高了构建的灵活性和可维护性。正如Bjarne Stroustrup在《The C++ Programming Language》中所说：“代码的清晰度和组织结构直接决定了它的质量。”

4. 实际应用与示例 (Practical Application and Examples)

在CMake的众多功能中，其强大的库查找能力无疑是最吸引人的一点。在实际的应用开发过程中，我们经常需要使用第三方库来完成某些功能。这时，如何正确、快速地找到并链接这些库就成了一个非常重要的问题。

4.1 如何在项目中集成模板 (Integrating the Template into a Project)

首先，我们需要确保我们的CMake项目已经包含了我们的通用库查找模板。通常，我们会将这个模板保存为一个单独的.cmake文件，例如FindAnyLibrary.cmake，然后在主CMakeLists.txt文件中使用include()命令将其包含进来。

include(FindAnyLibrary.cmake)

接下来，我们可以在项目的任何地方使用find_library_generic()函数来查找我们需要的库。例如，如果我们需要查找一个名为mylib的静态库，我们可以这样做：

find_library_generic(mylib STATIC)

这时，CMake会自动根据我们的系统和编译器设置去相应的路径下查找这个库。如果找到了，它会设置相应的变量，如MYLIB_FOUND、MYLIB_INCLUDE_DIRS和MYLIB_LIBRARIES。

这种方法的优势在于，我们不需要关心库文件的具体位置或名称。只要给定库的基本名字和类型，CMake就会帮我们完成剩下的工作。

4.2 查找常见库的示例 (Examples of Finding Common Libraries)

在实际的项目开发中，我们可能会遇到各种各样的库。下面，我们将展示如何使用我们的模板来查找一些常见的库。

4.2.1 查找OpenCV

OpenCV是一个非常流行的计算机视觉库。假设我们想在项目中使用它，我们可以这样做：

find_library_generic(opencv STATIC)

正如Bjarne Stroustrup在《The C++ Programming Language》中所说：“我们的工具和库不仅仅是代码，它们是我们思维的延伸”。当我们使用这种方法来查找库时，我们实际上是在利用CMake这个工具的力量，让它帮助我们处理一些繁琐的细节。

4.2.2 查找Boost

Boost是一个广泛使用的C++库集合。为了在项目中使用它，我们可以这样写：

find_library_generic(boost SHARED)

在这里，我们明确指定了我们想要查找的是动态链接库。这样，CMake会在相应的路径下查找名为boost或libboost的动态链接库文件。

4.3 跨平台查找的挑战与解决方案 (Challenges and Solutions for Cross-Platform Finding)

在跨平台的软件开发中，库查找无疑是一个巨大的挑战。不同的操作系统和编译器可能会有不同的库文件命名规则和存放路径。因此，我们的查找模板需要能够处理这些差异。

为了实现这一点，我们的模板首先会检查当前的编译器和目标平台。然后，它会根据这些信息构建出相应的查找路径。例如，对于Windows平台和MSVC编译器，它可能会查找C:/path/to/libs/windows/msvc/这样的路径。

这种方法的优势在于，它为我们提供了一个统一的接口，使我们可以在不同的平台和编译器上以相同的方式查找库。这大大简化了跨平台开发的复杂性，并使我们能够更专注于实际的应用开发。

在实际的软件开发中，我们经常需要在多个平台上部署应用。为了确保应用的稳定性和性能，我们需要确保在所有平台上都使用了正确的库版本。这时，我们的查找模板就显得尤为重要了。正如某位哲学家所说：“工具不仅仅是工具，它是我们与外界沟通的桥梁”。

5. 最佳实践与常见错误 (Best Practices and Common Mistakes)

5.1 维护库查找模板的建议 (Tips for Maintaining the Library Finder Template)

一旦您的项目开始增长，您可能会发现自己需要在多个地方查找库。为了确保查找模板的可维护性，以下是一些建议：

• 代码重用：不要为每个库重复相同的查找逻辑。使用函数或宏来封装查找逻辑，这样在需要时只需调用一次。

  function(find_my_lib LIB_NAME)
      # ...查找逻辑...
  endfunction()
  
  find_my_lib(lib1)
  find_my_lib(lib2)
  

• 路径变量：使用变量来表示经常改变的路径部分，例如第三方库的根路径。这样，当路径发生更改时，您只需在一个地方更新它。

  set(THIRD_PARTY_ROOT "/path/to/third_party")
  

• 版本控制：确保您的CMakeLists文件和模块都纳入版本控制。这不仅能帮助您跟踪更改，还能确保其他开发者可以轻松地获取和使用您的查找模板。

---

5.2 避免常见的库查找错误 (Avoiding Common Mistakes in Library Finding)

CMake虽然功能强大，但它并不是万能的。许多常见的错误都是由于对CMake的理解不足或使用不当导致的。以下是一些在使用CMake进行库查找时经常遇到的常见错误及其解决方案：

• 指定了错误的查找路径：确保指定的查找路径是正确的，且库文件确实存在于指定的路径中。您可以使用message函数来输出查找路径，以帮助诊断问题。

  message("Looking for library in: ${LIB_PATH}")
  

• 未考虑库的版本：当查找库时，考虑库的版本可能很重要。为了避免版本不匹配的问题，使用find_package的VERSION参数来指定所需的版本。

• 使用了相对路径：在CMake中使用相对路径可能会导致一些难以追踪的错误。建议始终使用绝对路径，这样您就可以确保无论在哪里调用CMake，路径都是正确的。

  get_filename_component(ABS_PATH "${REL_PATH}" ABSOLUTE)
  

---

5.3 社区资源与工具推荐 (Recommended Community Resources and Tools)

尽管CMake的官方文档已经很全面，但有时候查找特定的解决方案或最佳实践可能仍然很困难。幸运的是，有一个活跃的CMake社区愿意分享他们的知识和经验。

• CMake官方文档：始终是最可靠的资源。每当您对某个命令或变量有疑问时，首先查看官方文档。
• Stack Overflow：这是一个问题和答案社区，您可以在这里找到许

多关于CMake的问题和答案。

• CMake Mailing List：这是一个活跃的邮件列表，您可以在这里提问或分享您的知识。

6. 结语 (Conclusion)

当我们站在软件开发的巨人肩膀上时，工具和框架的选择显得尤为重要。CMake，作为一个跨平台的构建系统，帮助我们高效地管理和构建项目。但正如Bjarne Stroustrup在《The C++ Programming Language》中所说：“我们需要工具，同样也需要理解这些工具是如何工作的。”

6.1. 库查找模板的价值 (The Value of a Library Finder Template)

在编程的海洋中，库（libraries）就像是那些神秘的岛屿，储藏着宝藏。而在这片海洋中导航，我们需要精确而可靠的地图。CMake的库查找模板为我们提供了这样的地图，允许我们在不同的系统和架构上找到我们所依赖的那些宝藏。

正如人类的探索精神驱使我们寻找新大陆，程序员的好奇心同样驱使我们深入底层，理解我们所使用工具的内部原理。这不仅帮助我们更好地使用这些工具，而且还能激发我们的创造力，引导我们找到新的、更好的方法。

6.2. 鼓励读者进一步探索CMake (Encouraging Readers to Dive Deeper into CMake)

我们已经探索了CMake的库查找模板的表面，但它的深度远不止于此。正如探险家探索未知领域，我鼓励大家深入CMake的源代码，去探索其更多的功能和特性。例如，可以查看CMake的源代码中的 Modules/FindXXX.cmake 文件，理解它是如何实现的。

# 示例：使用CMake查找ZLIB库
find_package(ZLIB REQUIRED)
if(ZLIB_FOUND)
    include_directories(${ZLIB_INCLUDE_DIRS})
    target_link_libraries(my_project ${ZLIB_LIBRARIES})
endif()

这种深入底层的探索可以帮助您更好地理解和使用CMake，同时也可以提高您的编程技能。

6.3. 邀请读者分享反馈与建议 (Inviting Feedback and Suggestions from the Readers)

我们的旅程虽然到此结束，但学习和探索永无止境。我邀请大家分享自己的经验、建议和反馈，共同学习，共同进步。正如Albert Einstein曾说：“学习是经验的积累，经验是过去的学习。”（来源：Albert Einstein quotes）。

结语

在我们的编程学习之旅中，理解是我们迈向更高层次的重要一步。然而，掌握新技能、新理念，始终需要时间和坚持。从心理学的角度看，学习往往伴随着不断的试错和调整，这就像是我们的大脑在逐渐优化其解决问题的“算法”。

这就是为什么当我们遇到错误，我们应该将其视为学习和进步的机会，而不仅仅是困扰。通过理解和解决这些问题，我们不仅可以修复当前的代码，更可以提升我们的编程能力，防止在未来的项目中犯相同的错误。

我鼓励大家积极参与进来，不断提升自己的编程技术。无论你是初学者还是有经验的开发者，我希望我的博客能对你的学习之路有所帮助。如果你觉得这篇文章有用，不妨点击收藏，或者留下你的评论分享你的见解和经验，也欢迎你对我博客的内容提出建议和问题。每一次的点赞、评论、分享和关注都是对我的最大支持，也是对我持续分享和创作的动力。

---

阅读我的CSDN主页,解锁更多精彩内容:泡沫的CSDN主页