第一个完整的CMake工程

一、概述

本工程所在的文件夹名称为 hello_project。工程名为 hello。
本篇使用out-of-source外部构建，约定的构建目录是工程目录下的build目录。

为了使hello_project看起来更像一个工程，我们需要做的是：

• 为工程添加一个子目录 src，用来放置工程源代码
• 为工程添加一个子目录 doc，用来放置工程的文档 hello.txt
• 在工程目录中添加文本文件 COPYRIGHT, README
• 在工程目录添加一个 runhello.sh 脚本，用来调用 hello 二进制文件
• 将构建后的目标文件放入构建目录的bin目录
• 最终安装这些文件：
  • 将 hello 二进制可执行文件和 runhello.sh 安装至/usr/bin
  • 将 doc 目录的内容以及 COPYRIGHT 和 README 安装到 /usr/share/doc/hello

二、准备工作

2.1 创建工程

此处使用vscode的CMake Tool创建一个初始的工程hello。如何创建请参考我的另一篇博文：
《vscode使用CMake Tool插件构建第一个CMake的helloworld工程》

对于该工程的一些说明可以参考：
《对CMake Tool创建的第一个hello world工程的说明》

当然了，你也可以纯手工创建一个，没有问题。创建好后，工程看起来是这个样子。

2.2 创建源码目录

在工程目录下，创建一个子目录src，用于存放源码

mkdir src
mv main.cpp src

我们需要为每一个子目录创建一个CMakeLists.txt, 所以进入src子目录，编写CMakeLists.txt, 加入以下内容：

add_executable(hello main.cpp)

修改工程目录下的CMakeLists.txt, 删除原先的 add_executable 语句，加入以下内容：

add_subdirectory(src bin)

它现在看起来是这样：

建立build目录（CMake Tool已经为我们创建了，如果没有，自己手动建一个），进入build目录, 开始构建

cmake ..
make

构建完成后，你会发现生成的目标文件hello位于 build/bin 目录中。

三、换个地方保存目标二进制文件

3.1 add_subdirectory 指令说明

其语法结构为：

ADD_SUBDIRECTORY(source_dir [binary_dir] [EXCLUDE_FROM_ALL])

这个指令用于向当前工程添加存放源文件的子目录，并可以指定中间二进制和目标二进制存放的位置。EXCLUDE_FROM_ALL 参数的含义是将这个目录从编译过程中排出，比如，工程的example，可能就需要工程构建完成后，再进入example目录单独进行构建。

上面的例子工程中，定义了将src子目录加入工程，并制定编译输出（包含编译中间结果）路径为 bin 目录。如果不进行 bin 目录的制定，那么编译结果（包括编译中间结果）都将存放在 build/src 目录（这个 src 跟原有的 src 目录对应），指定 bin 目录后，相当于在编译时将 src 重命名为 bin，所有的中间结果和目标二进制都将存放在 bin 目录。

3.2 重设目标二进制生成目录

我们也可以换个地方保存目标二进制，可以通过 set 指定 重新定义EXECUTABLE_OUTPUT_PATH 和 LIBRARY_OUTPUT_PATH 变量来指定最终的目标二进制的位置(指最终生成的 hello 或者最终的共享库，不包含编译生成的中间文件)。

SET(EXECUTABLE_OUTPUT_PATH ${PROJECT_BINARY_DIR}/bin)
SET(LIBRARY_OUTPUT_PATH ${PROJECT_BINARY_DIR}/lib)

PROJECT_SOURCE_DIR 如果是外部编译，指的是外部编译所在目录，也就是本例中的 build目录。

所以，上面两个指令分别定义了：

• 可执行二进制的输出路径为 build/bin
• 库的输出路径为 build/lib.

本节我们没有提到共享库和静态库的构建，所以，你可以不考虑第二条指令。

问题是，我应该把这两条指令写在工程的 CMakeLists.txt 还是 src 目录下的CMakeLists.txt，把握一个简单的原则，在哪里 ADD_EXECUTABLE 或 ADD_LIBRARY，如果需要改变目标存放路径，就在哪里加入上述的定义。

在本例中，当然就是 src 目录下的 CMakeLists.txt 了。

四、如何安装

4.1 目标文件的安装

那么我们的 hello 应该怎么进行安装呢？ cmake为我们提供了一个非常有用的指令和一个非常有用的变量：

指令：install
变量：CMAKE_INSTALL_PREFIX

install 指令用于定义安装规则，安装的内容可以包括目标二进制、动态库、静态库以及文件、目录、脚本等。

INSTALL 指令包含了各种安装类型：

INSTALL(TARGETS targets...
    [[ARCHIVE|LIBRARY|RUNTIME]
        [DESTINATION <dir>]
        [PERMISSIONS permissions...]
        [CONFIGURATIONS
    [Debug|Release|...]]
        [COMPONENT <component>]
        [OPTIONAL]
    ] [...])

参数中的 TARGETS 后面跟的就是我们通过 ADD_EXECUTABLE 或者 ADD_LIBRARY 定义的目标文件，可能是可执行二进制、动态库、静态库。

目标类型也就相对应的有三种，ARCHIVE 特指静态库，LIBRARY 特指动态库，RUNTIME特指可执行目标二进制。

DESTINATION 定义了安装的路径，如果路径以 / 开头，那么指的是绝对路径，这时候CMAKE_INSTALL_PREFIX 其实就无效了。如果你希望使用 CMAKE_INSTALL_PREFIX 来定义安装路径，就要写成相对路径，即不要以 / 开头，那么安装后的路径就是${CMAKE_INSTALL_PREFIX}/<DESTINATION 定义的路径>

举个简单的例子：

INSTALL(TARGETS myrun mylib mystaticlib
    RUNTIME DESTINATION bin
    LIBRARY DESTINATION lib
    ARCHIVE DESTINATION libstatic
)

• 可执行二进制 myrun 安装到${CMAKE_INSTALL_PREFIX}/bin 目录
• 动态库 libmylib 安装到${CMAKE_INSTALL_PREFIX}/lib 目录
• 静态库 libmystaticlib 安装到${CMAKE_INSTALL_PREFIX}/libstatic 目录

特别注意的是你不需要关心 TARGETS 具体生成的路径，只需要写上 TARGETS 名称就可以了。

4.2 普通文件的安装

INSTALL(FILES files... DESTINATION <dir>
    [PERMISSIONS permissions...]
    [CONFIGURATIONS [Debug|Release|...]]
    [COMPONENT <component>]
    [RENAME <name>] [OPTIONAL])

可用于安装一般文件，并可以指定访问权限，文件名是此指令所在路径下的相对路径。如果默认不定义权限 PERMISSIONS，安装后的权限为：
OWNER_WRITE, OWNER_READ, GROUP_READ,和 WORLD_READ，即 644 权限。

4.3 非目标文件的可执行程序安装(比如脚本之类)：

INSTALL(PROGRAMS files... DESTINATION <dir>
    [PERMISSIONS permissions...]
    [CONFIGURATIONS [Debug|Release|...]]
    [COMPONENT <component>]
    [RENAME <name>] [OPTIONAL])

跟上面的 FILES 指令使用方法一样，唯一的不同是安装后权限为:
OWNER_EXECUTE, GROUP_EXECUTE, 和 WORLD_EXECUTE，即 755 权限

4.4 目录的安装

INSTALL(DIRECTORY dirs... DESTINATION <dir>
    [FILE_PERMISSIONS permissions...]
    [DIRECTORY_PERMISSIONS permissions...]
    [USE_SOURCE_PERMISSIONS]
    [CONFIGURATIONS [Debug|Release|...]]
    [COMPONENT <component>]
    [[PATTERN <pattern> | REGEX <regex>]
    [EXCLUDE] [PERMISSIONS permissions...]] [...])

这里主要介绍其中的 DIRECTORY、PATTERN 以及 PERMISSIONS 参数。

DIRECTORY 后面连接的是所在 Source 目录的相对路径，但务必注意：abc 和 abc/有很大的区别。
如果目录名不以/结尾，那么这个目录将被安装为目标路径下的 abc，如果目录名以/结尾，
代表将这个目录中的内容安装到目标路径，但不包括这个目录本身。

PATTERN 用于使用正则表达式进行过滤，PERMISSIONS 用于指定 PATTERN 过滤后的文件权限。

我们来看一个例子:

INSTALL(DIRECTORY icons scripts/ DESTINATION share/myproj
    PATTERN "CVS" EXCLUDE
    PATTERN "scripts/*"
    PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
    GROUP_EXECUTE GROUP_READ)

这条指令的执行结果是：

将 icons 目录安装到 <prefix>/share/myproj，将 scripts/中的内容安装到
<prefix>/share/myproj

不包含目录名为 CVS 的目录，

对于 scripts/*文件指定权限为 OWNER_EXECUTE
OWNER_WRITE OWNER_READ GROUP_EXECUTE GROUP_READ.

安装时 CMAKE 脚本的执行：

INSTALL([[SCRIPT <file>] [CODE <code>]] [...])

• SCRIPT 参数用于在安装时调用 cmake 脚本文件（也就是.cmake 文件）
• CODE 参数用于执行 CMAKE 指令，必须以双引号括起来。比如：
  INSTALL(CODE “MESSAGE(“Sample install message.”)”)

五、修改hello工程来支持安装

5.1 补全工程所缺文件

回顾一下本文开头定义的任务：

• 为工程添加一个子目录 src，用来放置工程源代码
• 为工程添加一个子目录 doc，用来放置工程的文档 hello.txt
• 在工程目录中添加文本文件 COPYRIGHT, README
• 在工程目录添加一个 runhello.sh 脚本，用来调用 hello 二进制文件
• 将构建后的目标文件放入构建目录的bin目录
• 最终安装这些文件：
  • 将 hello 二进制可执行文件和 runhello.sh 安装至/usr/bin
  • 将 doc 目录的内容以及 COPYRIGHT 和 README 安装到 /usr/share/doc/hello

下面先把缺失的文件补全：

cd hello_project
mkdir doc
echo "this is hello" > doc/hello.txt

cd hello_project
echo "hello" > runhello.sh
echo "this is COPYRIGHT" > COPYRIGHT
echo "this is README" > README

现在的工程看起来是这个样子：

5.2 改写各目录的CMakeLists.txt

1. 安装 COPYRIGHT/README
   直接修改主工程文件 CMakelists.txt，加入以下指令：

   INSTALL(FILES COPYRIGHT README DESTINATION share/doc/${PROJECT_NAME})
   

2. 安装 runhello.sh
   直接修改主工程文件 CMakeLists.txt，加入如下指令：

    INSTALL(PROGRAMS runhello.sh DESTINATION bin)
   

3. 安装 doc 中的 hello.txt
   这里有两种方式：一是通过在 doc 目录建立CMakeLists.txt 并将 doc 目录通过 ADD_SUBDIRECTORY 加入工程来完成。另一种方法是直接在工程目录通过INSTALL(DIRECTORY 来完成)，前者比较简单，各位可以根据兴趣自己完成，我们来尝试后者，顺便演示以下 DIRECTORY 的安装。

   因为 hello.txt 要安装到/<prefix>/share/doc/hello，所以我们不能直接安装整个 doc 目录，这里采用的方式是安装 doc 目录中的内容，也就是使用”doc/”

   在工程文件中添加:

    INSTALL(DIRECTORY doc/ DESTINATION share/doc/{PROJECT_NAME})
   

此时工程根目录下的CMakeLists.txt内容如下：

cmake_minimum_required(VERSION 3.0.0)
project(hello VERSION 0.1.0)

include(CTest)
enable_testing()

add_subdirectory(src bin)
INSTALL(FILES COPYRIGHT README DESTINATION share/doc/${PROJECT_NAME})
INSTALL(PROGRAMS runhello.sh DESTINATION bin)
INSTALL(TARGETS hello RUNTIME DESTINATION bin)
INSTALL(DIRECTORY doc/ DESTINATION share/doc/${PROJECT_NAME})

set(CPACK_PROJECT_NAME ${PROJECT_NAME})
set(CPACK_PROJECT_VERSION ${PROJECT_VERSION})
include(CPack)

现在现在进入 build 目录进行外部编译，注意使用 CMAKE_INSTALL_PREFIX 参数，这里我们
将它安装到了/tmp/hello_project 目录：

cmake -DCMAKE_INSTALL_PREFIX=/tmp/hello_project/usr ..

看看安装效果：

另外如果没有指定 CMAKE_INSTALL_PREFIX ，你会发现它的默认定义是/usr/local