【动态库.so | 头文件.hpp】基于CMake与CMakeList编写C++自定义库

前言

最近比较忙，其他系列教程得等到年后一起更！请大家多多包涵！！
相信各位在配置C++环境和各类库的时候一定经常看到如下小连招

git clone https://github.com/opencv/opencv.git 
cd opencv
mkdir build && cd build
cmake .. && make -j4
sudo make install 
sudo ldconfig

今天我们就来谈一谈上述每一行指令的具体含义，并尝试构造我们自己的示例库。
之后我们就可以使用编译生成的动态库文件.so和我们提供的头文件hpp给用户使用。
通过配置我们可以在cmake直接包含链接我们的自定义库find_package(MyTime REQUIRED)

1 分布讲解

1-1 拉去仓库

git clone https://github.com/opencv/opencv.git

用于从远程仓库复制一个完整的版本库到本地。
https://github.com/opencv/opencv.git: 指定了要克隆的远程仓库的URL。此处是OpenCV的官方GitHub仓库地址。

执行此命令后，会在当前目录下生成一个名为opencv的子文件夹，其中包含OpenCV的完整源代码。

cd opencv

1-2 编译

mkdir build && cd build

创建一个名为build的子目录，并切换到该目录。通常在此目录中进行编译过程。

cmake .. && make -j4

使用CMake生成构建配置并启动构建过程。
- cmake ..: 运行CMake命令，..表示CMake应该在父目录（即源代码目录）中查找CMakeLists.txt文件。CMake会根据这个文件生成构建配置文件（如Makefile或Visual Studio工程文件等）。
- make -j4: 使用make工具来开始构建过程。-j4指定了并行构建的线程数，这里是4个线程，可以加速编译过程。

1-3 安装

sudo make install

make install: 这个命令会将构建完成的库、头文件和可执行文件拷贝到系统的标准位置（例如/usr/local/lib、/usr/local/include等）。具体的安装路径和内容是由CMakeLists.txt文件中指定的。
sudo: 由于make install通常需要系统级的权限，所以需要sudo来提权执行命令。

sudo ldconfig

ldconfig: 是一个用于更新动态链接库缓存的命令。操作系统会根据/etc/ld.so.conf和/lib、/usr/lib等目录中的库文件来更新缓存。ldconfig命令的目的是让操作系统能够找到新安装的库文件。
sudo: 因为ldconfig需要修改系统级配置，所以需要sudo权限。

1-4 使用

通过上述过程，如果你在其他项目中需要使用到 OpenCV，你只需要在项目中正确配置 OpenCV 的头文件和库文件路径，并在编译时链接 OpenCV 库即可。

cmake_minimum_required(VERSION 3.10)project(MyProject)# 查找 OpenCV 包
find_package(OpenCV REQUIRED)# 将 OpenCV 的 include 目录添加到编译器的头文件路径
include_directories(${OpenCV_INCLUDE_DIRS})# 定义源文件
add_executable(my_program main.cpp)# 将 OpenCV 库链接到项目中
target_link_libraries(my_program ${OpenCV_LIBS})

2 构建自己的库

通过上述说明，你也许还是懵懵懂懂，下面我们创建自己的一个库，并逐步细致的说明。

2-1 创建文件夹

我们打开终端，创建一个文件夹用来存放我们的自定义库，我们给库取名为MyTime,并在这个文件夹下创建src和include目录。

mkdir -p MyTime/src MyTime/include

-p：表示递归创建目录，若父目录不存在，也会一并创建。
MyTime/src：存放源代码文件。

MyTime/include：存放头文件。

2-2 编写头文件

我们实现一个简单的打印当前时间库，这个库将提供几个函数
- printCurrentDate：打印当前日期（年月日格式）。
- getFormattedTime：返回当前时间的格式化字符串（比如 “YYYY-MM-DD HH:MM:SS”）。
- calculateTimeDifference：计算两个时间点之间的差异，返回秒数。
然后根据上述旨意，我们编写include/MyTime.hpp

// MyTime/include/MyTime.h
#ifndef __MY_TIME_HPP__
#define __MY_TIME_HPP__#include <string>namespace mytime{class MyTime{public:// 打印当前的时间void printCurrentTime();// 打印当前的日期（年月日）void printCurrentDate();// 获取当前时间的格式化字符串（YYYY-MM-DD HH:MM:SS）std::string getFormattedTime();// 计算两个时间点之间的差异，返回秒数double calculateTimeDifference(const std::string& time1, const std::string& time2);};};#endif // __MY_TIME_HPP__

头文件保护机制：#ifndef, #define 和 #endif 这一组预处理指令保证了头文件只会被包含一次，从而防止重复定义。
- __MY_TIME_HPP__ 是一个宏定义，它会在头文件被第一次包含时被定义，从而防止第二次包含。
- 除此之外我们还可以使用pragma once防止头文件被重复编译

命名空间 mytime：为了避免与其他库中的类名冲突，我们将 MyTime 类放在 mytime 命名空间中。这样你就可以通过 mytime::MyTime 来访问 MyTime 类。
MyTime 类声明：
- printCurrentTime：用于打印当前系统时间。
- printCurrentDate：用于打印当前系统日期，格式为 YYYY-MM-DD。
- getFormattedTime：返回当前时间的格式化字符串，格式为 YYYY-MM-DD HH:MM:SS。
- calculateTimeDifference：计算两个给定时间字符串之间的差异，单位为秒。该函数接受两个字符串形式的时间（格式为 YYYY-MM-DD HH:MM:SS），并返回它们之间的差异（秒）。

2-3 编写源代码

src\Mytime.cpp

// MyTime/src/MyTime.cpp
#include "../include/MyTime.hpp"
#include <iostream>
#include <chrono>
#include <ctime>
#include <sstream>
#include <iomanip>namespace mytime {// 打印当前的时间void MyTime::printCurrentTime() {// 获取当前时间auto now = std::chrono::system_clock::now();std::time_t now_time = std::chrono::system_clock::to_time_t(now);// 打印时间std::cout << "Current time: " << std::ctime(&now_time);}// 打印当前的日期（年月日）void MyTime::printCurrentDate() {// 获取当前时间auto now = std::chrono::system_clock::now();std::time_t now_time = std::chrono::system_clock::to_time_t(now);std::tm *tm = std::localtime(&now_time);// 打印日期（格式为 YYYY-MM-DD）std::cout << "Current date: "<< std::put_time(tm, "%Y-%m-%d")  // 格式化为 YYYY-MM-DD<< std::endl;}// 获取当前时间的格式化字符串（YYYY-MM-DD HH:MM:SS）std::string MyTime::getFormattedTime() {// 获取当前时间auto now = std::chrono::system_clock::now();std::time_t now_time = std::chrono::system_clock::to_time_t(now);std::tm *tm = std::localtime(&now_time);// 使用 stringstream 格式化时间为字符串std::ostringstream oss;oss << std::put_time(tm, "%Y-%m-%d %H:%M:%S");  // 格式化为 YYYY-MM-DD HH:MM:SSreturn oss.str();}// 计算两个时间点之间的差异，返回秒数double MyTime::calculateTimeDifference(const std::string& time1, const std::string& time2) {std::tm tm1 = {}, tm2 = {};std::istringstream ss1(time1), ss2(time2);// 解析时间字符串（格式: YYYY-MM-DD HH:MM:SS）ss1 >> std::get_time(&tm1, "%Y-%m-%d %H:%M:%S");ss2 >> std::get_time(&tm2, "%Y-%m-%d %H:%M:%S");// 将 std::tm 转换为 time_tstd::time_t t1 = std::mktime(&tm1);std::time_t t2 = std::mktime(&tm2);// 计算两个时间点的时间差，单位为秒double diff = std::difftime(t2, t1);return diff;}} // namespace mytime

2-4 Cmake

2-4-1 Cmake介绍

CMake 是一个跨平台的自动化构建工具，它能够生成不同平台（如 Linux、Windows、macOS）上的构建文件，并支持多种构建系统（如 Make, Ninja, Visual Studio, Xcode 等）。CMake 主要用于管理大型软件项目的构建过程，通过配置项目的构建步骤来生成适合目标平台的构建文件。

2-4-2 CMake 的核心概念

CMakeLists.txt：这是 CMake 项目的配置文件，通常在每个子目录中都有一个，CMake 会根据这些文件来决定如何构建整个项目。CMakeLists.txt 文件包含了 CMake 的指令和设置，它们告诉 CMake 如何配置、编译和链接项目。
CMake 构建过程： CMake 的构建过程通常包括两个步骤：
- 配置步骤：通过执行 cmake 命令，CMake 会根据 CMakeLists.txt 文件的内容生成构建系统的配置文件（如 Makefile、Visual Studio 项目文件等）。
- 构建步骤：通过执行构建命令（如 make、ninja 等），CMake 会使用生成的构建文件来编译项目。
CMake 变量： CMake 允许在 CMakeLists.txt 文件中定义变量，这些变量可以在整个项目中使用。变量可以用来指定路径、设置编译选项或管理构建参数。
目标（Target）：在 CMake 中，“目标” 是你要构建的最终产物（比如库文件、可执行文件等）。通过 CMake 指令如 add_executable、add_library 来定义目标。

2-4-3 CMake 的主要指令

cmake_minimum_required(VERSION <version>)：这个指令设置项目所需的最低 CMake 版本。如果当前的 CMake 版本低于这个版本，CMake 会发出警告。

cmake_minimum_required(VERSION 3.10)

project(<project-name>)：设置当前项目的名称。

project(MyProject)

set(<variable> <value>)：设置变量的值。CMake 中的变量可以用来存储路径、文件名、编译选项等。

set(CMAKE_CXX_STANDARD 11)

add_executable(<target> <source-files>)：用于创建一个可执行文件目标，指定源文件列表。

add_executable(MyApp main.cpp)

add_library(<target> <source-files>)：用于创建一个库目标，可以是静态库或动态库。

add_library(MyLib STATIC mylib.cpp)

target_link_libraries(<target> <libraries>)：指定可执行文件或库所依赖的其他库。

target_link_libraries(MyApp MyLib)

include_directories(<dir>)：用于添加头文件的搜索路径。

include_directories(${CMAKE_SOURCE_DIR}/include)

find_package(<package-name>)：查找已安装的外部库（如 Boost、OpenGL、Qt 等）。

find_package(Boost REQUIRED)

install(<target>)：指定安装规则，用于将构建好的目标安装到指定目录。

install(TARGETS MyApp DESTINATION /usr/local/bin)

2-5 配置Cmake

我们为我们的MyTime库进行cmake的配置
我们在MyTime文件夹下新建文件CMakeLists.txt

# 设置最低 CMake 版本
cmake_minimum_required(VERSION 3.10)# 设置工程名称
project(MyTime)# 设置 C++ 标准
set(CMAKE_CXX_STANDARD 11)# 设置包含头文件的目录
include_directories(${CMAKE_SOURCE_DIR}/include)# 添加源文件目录
add_library(MyTime SHAREDsrc/MyTime.cpp
)# 如果你要构建可执行文件（例如测试程序），可以添加以下内容
# add_executable(MyTimeTest src/test.cpp)
# target_link_libraries(MyTimeTest MyTime)

2-5-1 静态库和动态库

静态库（Static Library）和动态库（Dynamic Library）是两种常见的库类型，它们主要在 编译时 和 运行时 的行为上有很大的不同。

特性	静态库（Static Library）	动态库（Dynamic Library）
链接时机	编译时链接，生成的程序包含库的代码	运行时链接，程序在运行时加载库
文件格式	`.a`（Linux/macOS）或 `.lib`（Windows）	`.so`（Linux）、`.dll`（Windows）、`.dylib`（macOS）
文件大小	可执行文件较大，因为库代码包含在内	可执行文件较小，库共享但需单独管理
程序启动时间	启动较快，不需要加载外部库文件	启动时需要加载外部库文件，可能稍慢
依赖性	不依赖外部库，完全独立	依赖外部库，必须保证库文件存在
更新和维护	更新库时必须重新编译所有依赖该库的程序	更新库时无需重新编译程序，只要库接口不变
内存使用	每个程序有一份库的副本	多个程序共享一份库的副本
兼容性	编译后不易出现兼容性问题	可能出现库版本不匹配或丢失的问题

在CMakeLists.txt中,我们可以制定参数SHARED用于配置动态库

add_library(MyTime SHAREDsrc/MyTime.cpp
)

如果你希望配置静态库，可以把SHARED替换为STATIC

add_library(MyTime STATICsrc/MyTime.cpp
)

2-6 cmake …

在配置好CMakeLists以后，我们就可以进行编译了，我们需要创建一个build文件夹，build文件夹通常用于存储编译中间和结果文件

mkdir build && cd build

自此我们的库一共有如下结构
紧接着我们进行编译，再cd build进入build目录下以后，我们执行

cmake ..

请添加图片描述

执行完上述指令后，我们可以看到build目录下多出了如下文件

CMakeCache.txt
- 作用：CMakeCache.txt 是 CMake 配置过程的缓存文件，保存了配置过程中产生的一些变量值（例如编译器路径、编译选项等）。当你重新运行 CMake 时，它会使用这个文件中的信息来加速配置过程。
- 内容：文件中包含了各种设置项，如编译器路径、标志、包含的头文件路径、库路径等。
- 解释：CMake 使用这个文件存储了用户和 CMake 检测到的配置结果，因此如果没有做任何修改，下一次执行 cmake 时会直接读取此文件，加速配置过程。
CMakeFiles 目录
- 作用：CMakeFiles 目录包含 CMake 使用的内部文件，这些文件是 CMake 在生成构建系统时创建的。
- 内容：该目录中包含了一些用于构建的中间文件和子目录，CMake 会根据它们来管理依赖关系和生成最终的构建文件。
- 解释：通常你不需要直接操作这个目录，它是 CMake 在后台处理过程中需要用到的。
cmake_install.cmake
- 作用：cmake_install.cmake 是 CMake 在配置时生成的安装脚本文件。当你执行 make install 或其他安装命令时，CMake 会使用这个文件来执行安装过程。
- 内容：该文件定义了安装目标，如如何将生成的可执行文件、库文件、头文件等复制到指定的系统目录。
- 解释：通常你不需要手动编辑这个文件，除非你有特定的安装需求。它是构建完成后安装过程的关键部分。
Makefile
- 作用：Makefile 是一个标准的构建脚本文件，CMake 在执行配置时生成它。它包含了如何编译项目的详细信息和规则。
- 内容：这个文件列出了所有的源文件、编译选项、依赖关系以及如何将它们编译和链接成最终的可执行文件。
- 解释：当你运行 make 命令时，它会读取 Makefile，并根据其中的规则来执行编译任务。你可以使用 make 来编译项目，或者使用 make install 来安装项目。

实际上我们使用cmake ..就是借助CMakeLists.txt的配置项去生成编译最关键的Makefile,用于辅助一会要进行的make,值得一提的是makefile是可以直接手写的，因此cmake ..这一步骤不是必要的，但是当构建大型项目的时候，手写makefile不方便，因此我们通常借助CMakeLists.txt和cmake ..进行makefile的生成。

2-7 make -j4

在CMakeLists.txt的辅助下,我们已经生成了makefile,因此我们正式开始编译

make -j4

请添加图片描述

**[ 50%] Building CXX object CMakeFiles/MyTime.dir/src/MyTime.cpp.o**这行表示正在编译 src/MyTime.cpp 这个源文件。
- Building CXX object：说明正在编译 C++ 源文件，目标是生成对应的目标文件（.o 文件）。此时，CMake 会将 src/MyTime.cpp 文件编译成一个名为 MyTime.cpp.o 的目标文件（即中间文件）。
[100%] Linking CXX shared library libMyTime.so
- 这行表示链接阶段，正在将之前生成的目标文件（如 .o 文件）链接成一个共享库（.so 文件）。
编译完成后，我们看到build文件夹下生成了libMyTime.so的动态库文件
有了编译生成的libMyTime.so和头文件MyTime.hpp,用户就可以在没有源文件的情况下使用你的代码了。

2-8 sudo make install 安装

在用户完成编译后，手动链接动态库其实就可以直接使用你的库了，但是一般我们会使用sudo make install将编译生成的动态库和静态库移动到usr/local/lib中，这样方便我们直接调用。

sudo make install

然后不出意外你会抱错
那是因为如果你在项目的 Makefile 或 CMakeLists.txt 中没有显式定义 install 规则，make install 命令就无法找到要执行的目标。install 是一种标准的构建目标，但它不是自动存在的，必须在 CMakeLists.txt 或 Makefile 中显式声明。
我们在CMakeLists.txt中添加

install(TARGETS MyTime DESTINATION /usr/local/lib)
install(FILES include/MyTime.hpp DESTINATION /usr/local/include)

然我们需要重新生成构建文件并编译

cmake .. && make -j4

然后执行

sudo make install

请添加图片描述

我们可以在上述路径中找到这两个文件。这样用户在使用代码的时候，就不需要手动进行库链接了。

2-9 sudo ldconfig

sudo ldconfig

sudo ldconfig 是一个在 Linux 系统中用于更新和管理动态链接库缓存的命令。它会扫描系统上指定的库目录，并更新缓存，以便程序能够找到新的共享库（.so 文件）。通常在安装新库（尤其是共享库）时，执行 sudo ldconfig 以确保系统能够正确地识别和链接新库。

更新共享库缓存：
- Linux 系统使用动态链接库（shared libraries）来支持程序的运行。ldconfig 会扫描 /etc/ld.so.conf 文件中列出的目录以及 LD_LIBRARY_PATH 环境变量指定的路径，找到所有共享库，并将它们的信息保存到缓存中。这个缓存文件通常位于 /etc/ld.so.cache。
- 执行 ldconfig 后，程序在运行时就可以更快地查找需要的库文件，而不必每次都重新搜索整个文件系统。
让新安装的库生效：
- 当你使用 make install 或通过包管理工具（如 apt、yum 等）安装共享库时，ldconfig 会帮助系统更新库的路径，使得程序能够找到新安装的库。特别是在安装自定义库时，执行 ldconfig 是很有必要的。
让 ld 和 ld.so 正确工作：
- 在使用动态链接器加载共享库时（例如，运行一个依赖于共享库的程序），ldconfig 会确保这些库的路径信息被正确记录，并且链接器能够正确地找到并加载这些库。

3 使用自定义库

通过上述过程，我们已经成功把MyTime写入下属路径了

-- Up-to-date: /usr/local/lib/MyTime.so
-- Installing: /usr/local/include/MyTime.hpp

我们分别讲讲手动链接和Cmake链接

3-1 调用头文件`<MyTime.hpp>`

我们创建一个新的cpp文件并调用我们的自定义库，testMyTime.cpp

#include <iostream>
#include <MyTime.hpp>int main() {mytime::MyTime timeObj;// 打印当前时间timeObj.printCurrentTime();// 打印当前日期（年月日）timeObj.printCurrentDate();// 获取当前时间的格式化字符串std::string formattedTime = timeObj.getFormattedTime();std::cout << "Formatted time: " << formattedTime << std::endl;// 计算两个时间点之间的差异double timeDiff = timeObj.calculateTimeDifference("2024-12-09 10:00:00", "2024-12-09 12:00:00");std::cout << "Time difference: " << timeDiff << " seconds" << std::endl;return 0;
}

3-2 手动链接

由于MyTime是一个动态链接库（.so文件），你需要确保在编译时链接该库。可以通过以下两种方式之一来链接：
- 编译时指定库路径：在编译时，使用-L选项指定库文件的路径（例如：/usr/local/lib/），并使用-l选项指定库名（不包括lib前缀和文件扩展名）。例如：
```
g++ -o testMyTime testMyTime.cpp -L/usr/local/lib -lMyTime
```
- 设置环境变量：你还可以通过设置LD_LIBRARY_PATH环境变量来告诉系统动态库的路径：
```
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
```

3-3 编译并测试

编译

g++ -o testMyTime testMyTime.cpp -L/usr/local/bin -lMyTime

请添加图片描述

可以看到我们中途在手动链接的时候出现了错误

./testMyTime: error while loading shared libraries: libMyTime.so: cannot open shared object file: No such file or directory

顾名思义是由于找不到动态库.so导致的，我们只需要手动进行制定即可

export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

3-4 CMake配置

上述手动配置对于小的项目还好，大的项目还是要借助CMake比较方便
同理我们创建src目录，并把testMyTime.cpp移动到底下，并创建CMakeLists.txt

# 设置最低 CMake 版本
cmake_minimum_required(VERSION 3.10)# 设置工程名称
project(MyTime)# 设置 C++ 标准
set(CMAKE_CXX_STANDARD 11)set(CMAKE_INSTALL_PREFIX "/usr/local")
# 设置包含头文件的目录
include_directories(${CMAKE_SOURCE_DIR}/include)# 添加源文件目录
add_library(MyTime SHAREDsrc/MyTime.cpp
)
install(TARGETS MyTime DESTINATION /usr/local/lib)
install(FILES include/MyTime.hpp DESTINATION /usr/local/include)
# 安装 CMake 配置文件 
install(FILES cmake/MyTimeConfig.cmake DESTINATION /usr/local/lib/cmake/myTime)# 如果你要构建可执行文件（例如测试程序），可以添加以下内容
# add_executable(MyTimeTest src/test.cpp)
# target_link_libraries(MyTimeTest MyTime)

然后我们

 mkdir build && cd build cmake .. && make -j4

可以看到我们的so被找到，程序正确执行了。

4 如何让 `find_package(myTime REQUIRED)` 可用

果你希望通过 find_package(myTime REQUIRED) 来查找你的自定义库 MyTime，你需要为它提供一个合适的 CMake 配置文件或者模块。

4-1 配置`myTimeConfig.cmake`

我们让MyTime 库提供一个 CMake 配置文件 myTimeConfig.cmake，这样你可以直接使用 find_package(myTime REQUIRED)。
我们回到刚刚的库MyTime文件夹中,创建文件夹cmake,并在底下创建myTimeConfig.cmake

# myTimeConfig.cmake# 设置 MyTime 库的位置
set(MYTIME_LIBRARY /usr/local/lib/libMyTime.so)# 设置 MyTime 头文件的路径
set(MYTIME_INCLUDE_DIR /usr/local/include)# 提供 MyTime 库和头文件路径
set(MyTime_INCLUDE_DIRS ${MYTIME_INCLUDE_DIR})
set(MyTime_LIBRARIES ${MYTIME_LIBRARY})# 设置 MyTime_FOUND 标志
set(MyTime_FOUND TRUE)

然后我们需要在CMakeLists.txt 中设置安装规则

# 安装 CMake 配置文件
install(FILES cmake/myTimeConfig.cmake DESTINATION /usr/local/lib/cmake/myTime)

请添加图片描述

cd build 
cmake .. && make -j4
sudo make install
sudo ldconfig

注意取名必须是 MyTimeConfig.cmake 或者 mytime-config.cmake
否则你在进行find_package(myTime REQUIRED)会出现报错

4-2 `find_package(myTime REQUIRED)`

我们打开TestMyTime文件夹下的CMakeLists.txt

# 设置最低的 CMake 版本要求
cmake_minimum_required(VERSION 3.10)# 设置项目名称
project(MyTimeProject)# 设置 C++ 标准
set(CMAKE_CXX_STANDARD 11)# 查找 MyTime 库和其配置
find_package(MyTime REQUIRED)# 添加源文件
add_executable(testMyTime src/testMyTime.cpp)# 使用 MyTime 库链接目标
target_include_directories(testMyTime PRIVATE ${MyTime_INCLUDE_DIRS})
target_link_libraries(testMyTime PRIVATE ${MyTime_LIBRARIES})# 如果 MyTime 库是动态库，还需要设置运行时库路径
# 这样在运行时可以找到动态库
# 如果动态库不在默认的路径中，可以通过以下方式指定：
# set(CMAKE_INSTALL_RPATH /usr/local/lib)