CMake安装C++库的基本流程

鉴于大部分C++库都支持通过CMake安装，这里出一期通过CMake安装C++库的基本流程讲解，今后介绍其他库时，安装流程都可以参照本篇文章，如有例外会进行额外说明。

整体流程可分为四个主要步骤：源码下载、项目构建、库的生成、库的安装，其中每个步骤都有不同的执行方案，包括使用命令行的和使用图形界面（gui）的，下面就每个步骤进行详细讲解，读者可根据自己的喜好使用不同的方案来组合出不同的流程。

0. 写在前面

首先请确保你安装了CMake，并且将安装路径添加到了环境变量的PATH变量中（这样你才能在命令行中直接执行cmake命令），具体安装过程不做赘述。

一个CMake项目的根目录中一定包含一个名为CMakeLists.txt的文本文件，如果你安装的这个库的源码中没有，那么请确认它是否支持使用CMake安装。

整个流程我们使用jsoncpp库进行示例演示，项目GitHub页面：https://github.com/open-source-parsers/jsoncpp

1. 源码下载

首先在整个流程之前，最最最重要的当然是先把库的源码下载下来。如果有项目主页，一般可以在项目主页上获取源码，如果是发布在GitHub上的项目，一般有三种方式获取源码：

jsoncpp的GitHub页面

  1. git clone

    点击Code，复制其链接，打开终端进入一个拥有读写权限的路径，输入命令

    git clone <URL>

    这里的<URL>即为你刚才复制的链接，如

    git clone https://github.com/open-source-parsers/jsoncpp.git

    此时当前路径下就会多出一个与项目同名的文件夹，这就是项目的源码文件夹。

  2. 下载源码压缩包

    点击Code，点击Download ZIP即可下载源码压缩包，解压出来后即可得到源码文件夹。

  3. 进入Release页面下载源码

    项目一般都会有Release页面，点击进入后可以下载不同版本的源码压缩包，解压后即为对应版本的项目源码。

对于这三种方式，如果只是想把库安装起来，我比较推荐第三种方法，Releases的版本一般较为稳定。

前两种方法获取的源码一般会比Releases的最新版本更新（至少不落后于它，因为作者可能有小更新），如果对此有需求也可以考虑前两种方案。

如果想研究源码，想要在不同版本间随时切换，并且会使用git，甚至想修改源码的，建议采用第一种方案。

2. 项目构建

获取了项目的源码后，首先需要构建整个项目。

在Windows下默认使用 Visual Studio 作为生成器，构建完项目后可以在构建路径中找到一个.sln文件，这就是构建得到的vs工程文件，这个过程等价于你新建一个vs项目，然后给它添加各种头文件和源代码文件，以及修改项目属性的过程。

在其他系统下默认使用 Unix Makefiles 作为生成器，会在构建路径中生成一个 Makefile 文件。

这里有两种方案完成项目构建过程：

  1. cmake-gui（CMake图形化界面）

    Windows下安装CMake一般会自cmake-gui（CMake图形化界面），macos或Linux下也可以选择性安装。

    cmake-gui 1

    打开cmake-gui，选择源码路径（刚才的源码文件夹）以及构建路径（一个空文件夹），然后点击Configure，生成器选择默认的即可（如果是vs，请确保你的电脑中安装了对应版本的vs）。

    cmake-gui 2

    当下面的输出栏中出现Configuring done字样时，表示已经完成了初步配置，这时中间部分会出现很多可供修改的变量，大部分选项我们使用其默认值（即不进行修改），一般比较重要的几个变量有：

    • CMAKE_INSTALL_PREFIX：这个表示库的安装路径，Windows下一般默认为C/Program Files(X86)/<库名>，macos或Linux下一般默认为/usr/local。由于Windows下默认安装在一个独立的文件夹中，之后想要删除也可以很方便地移除，是否需要修改取决于用户自己，如果希望便于管理则建议修改为自定的路径。其他系统中如果采用默认路径，则会将头文件拷贝到/usr/local/include中，库文件拷贝到/usr/local/lib中，还有一些其他额外的文件，对于之后的删除很不方便，所以建议修改到自定的路径，如/usr/local/<库名>，我这里修改为了/usr/local/jsoncpp.

    • CMAKE_BUILD_TYPE：如果不需要调试信息的话建议修改为Release，会进行优化、提高速度，但是排除调试信息，如果需要调试信息但又希望尽可能保证速度，也可以选择修改为RelWithDebInfo，它会进行一定程度的优化，同时保留调试信息。

      Tip：请注意，Windows下使用vs作为生成器时，这个变量是不生效的，需要在后面的过程额外调整

    • BUILD_SHARED_LIBS：表示是否构建动态库，一般都勾选上。

    修改完变量后点击Generate，便会根据你修改的变量构建项目，当输出栏出现Generating done字样时表示已经完成构建，进入构建路径会发现这里多了很多文件。

  2. 命令行

    可以在命令行中使用cmake命令来进行构建过程。

    这一步在大多数教程中都是在源码路径中执行以下命令：

    mkdir build & cd build
cmake ..

    其中第一行命令为在当前路径下新建一个名为build的文件夹，然后进入build文件夹中，第二行命令表示将上一级路径（源码路径）中的CMake项目构建到当前路径（build文件夹）中。

    我一般喜欢使用这样的执行方式：

    cmake -B build

    表示将当前路径（源码路径）中的CMake项目构建到build文件夹中，如果没有build文件夹则会自动新建一个。

    Tip：这个命令更完整的执行方式是 cmake -S <源码路径> -B <构建路径>，cmake命令不加任何参数时默认的源码路径和构建路径都是当前路径，如果在后面添加一个路径（如cmake ..），则是将其设置为源码路径。

    以上的任何一种命令执行方式都可以使用默认的变量值完成对项目的构建，但是如果需要修改变量值，则需要添加额外参数，但是在gui中我们可以清晰地看到有哪些变量可供修改，但是现在我们怎么看呢？我们可以在执行完上面的命令后执行以下命令查看变量及其默认值：

    cmake <构建路径> -LH

    如cmake build -LH，确定好哪些变量需要修改后，在之前的构建命令的基础上，添加形如-D<变量名>=<变量值>的参数以修改变量，如：

    cmake -B build -DCMAKE_INSTALL_PREFIX=/usr/local/jsoncpp -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON

    执行后即可完成构建过程。

3. 库的生成

完成项目的构建后，便可以开始编译生成这个库。

这里同样介绍两种方式完成这个步骤。

  1. 命令行

    编译整个项目，我们可以直接在命令行中执行：

    cmake --build <构建路径>

    如：cmake --build build，但是请注意，我们前面提到了在Windows下使用VS作为生成器时，CMAKE_BUILD_TYPE变量是不生效的，这一步会默认使用Debug模式来编译，需要添加额外的参数进行修改：

    cmake --build <构建路径> --config <配置>

    如：cmake --build build --config Release，完成这一步便可以得到对应的库文件了。

    Tip：在其他教程中你可能会看到他们的这一步是在build文件夹中执行make .命令，但这个命令只适用于使用Unix Makefiles生成器构建项目，在构建路径中会得到一个makefile文件，实际执行效果和cmake --build是一样的。

    执行cmake --build命令时，CMake会根据你的平台以及生成器，自动地选择合适的编译方式，是一种更具有普适性的执行方式。

  2. Visual Studio

    在Windows下使用VS作为生成器时，完成项目构建后，在构建路径中我们会找到一个.sln工程文件，这就是一个VS项目，可以用VS直接打开它。

    1750604043959.png

    打开后会发现项目默认为Debug模式，请先将其修改为Release模式（或者其他你希望的模式）。在解决方案资源管理器中有很多目标，我们只需要关注最重要的两个：ALL_BUILD、INSTALL。INSTALL会在下一步中涉及，这里我们右键点击ALL_BUILD，然后点击"生成"，即可完成库的编译生成，这时不要急着把项目关闭，下一步中还会用到。

    1750603582478.png

4. 库的安装

完成库的编译生成后，就已经得到了库文件了，但是为了便于使用，我们还需将库安装到我们之前指定的路径中。其实安装过程本质上就是把编译得到的一些文件给复制到安装路径中，这一步的执行同样有两种方式。

  1. 命令行

    在命令行中执行：

    cmake --install <构建路径>

    如cmake --install build，Windows下使用VS作为生成器时，最好加上额外参数：

    cmake --install <构建路径> --config <配置>

    如cmake --install build --config Release，执行完安装命令后，进入到指定的安装路径中，便可以看到头文件、库文件以及一些其他文件都已经被拷贝过来了。

  2. Visual Studio

    紧跟着上一步的编译生成，ALL_BUILD目标生成完毕后，右键点击INSTALL，然后点击"生成"，便可完成库的安装过程。

    1750603646835.png

5. 设置环境变量

Tip：如果之后会在CMake配置的项目中使用这个库，则务必进行这一步，如果不在CMake配置的项目中使用，只在普通的VS项目中使用的话，这一步可有可无。

众所周知，在CMake中，我们通常使用find_package()函数来搜索指定依赖库，这个函数会在一些默认搜索路径中去搜索<库名>Config.cmake文件（Config模式下），这些默认路径包含了项目构建时CMAKE_INSTALL_PREFIX变量的默认值，所以如果在项目构建时没有修改这个变量，那么不需要任何额外设置也能直接搜索到库，如果修改了它，我们需要添加一个额外的环境变量<库名>_DIR，值为安装路径（可以设置得更深一点，如<安装路径>/lib或<安装路径>/lib/cmake，离<库名>Config.cmake越近越容易找到），在设置了这个环境变量的前提下它会优先到这个路径中去搜索。

在macos或Linux中添加环境变量只需要在~/.zprfile或~/.bash_profile（取决于你使用的终端是zsh还是bash）的末尾添加一行：

export <库名>_DIR=<安装路径>

如：

export jsoncpp_DIR=/usr/local/jsoncpp

保存后重启终端或在终端中执行命令source ~/.zprofile或source ~/.bash_profile即可生效。

在Windows中添加环境变量则需在“系统设置——高级系统设置——环境变量——用户变量”中点击“新建”，分别填写变量名与变量值，然后点击确定即可。添加后同样需要重启终端才可生效。

总结

完成全部流程后，便可愉快地将库引入到自己的项目中了。

此流程在三大操作系统上针对大部分C++库基本都适用（只要支持使用CMake构建），平常用CMake构建自己的C++项目也可以套用2、3两步。

至于在配置自己的项目时如何更加便捷地构建、生成，如何编写CMakeLists.txt，在之后的文章中我会进行详细的讲解。