CMake入门实践(三) ：复杂的HelloWorld项目

阳光穿透心脏的1/2处 2022-05-21 11:58 165阅读 0赞

## 一.需求 ##

1.  为工程添加一个子目录 src，用来放置工程源代码;
2.  添加一个子目录 doc，用来放置这个工程的文档 `hello.txt`
3.  在工程目录添加文本文件README；
4.  在工程目录添加一个`run.sh`脚本，用来调用 hello 二进制
5.  将构建后的目标文件放入构建目录的 bin 子目录；
6.  最终安装这些文件：将 hello 二进制与 runhello.sh 安装至工程目录的bin目录下面

## 二.完整实践 ##

这节全部的代码：  
[**LearningCMake/5.HelloWorld5/**][LearningCMake_5.HelloWorld5]

## 第一步 ##

首先我们先把要建立的的整个目录结构先弄好，比如我这里项目目录为HelloWorld5，因此我在该项目目录下面建立了4个目录，分别是bin（最终存放安装的运行文件），build（编译中间目录），doc（文档），src（源文件）.

首先来看源文件目录src里面的东西：很简单的一个`main.cpp`和`CMakeLists.txt` ，  
其中main.cpp就是之前提到过得非常简单的打印helloworld的源文件

#include <iostream>
    
    int main() {
        std::cout << "Hello, World!" << std::endl;
        return 0;
    }

`CMakeLists.txt` 的内容为：

cmake_minimum_required(VERSION 3.9)
    
    set(CMAKE_CXX_STANDARD 11)
    
    add_executable(HelloWorld main.cpp)
    
    SET(EXECUTABLE_OUTPUT_PATH ${PROJECT_BINARY_DIR}/../bin/)

这里有一个地方可以注意一下，就是我通过SET命令吧生成的可执行文件放到了工程目录的`bin/`目录下面。注意这个用法.

然后在看工程目录下面的`CMakeLists.txt`，其中内容为：

cmake_minimum_required(VERSION 3.9)
    project(HelloWorld5)
    
    set(CMAKE_CXX_STANDARD 11)
    
    ADD_SUBDIRECTORY(src temp)

到这里，我们可以暂时停下来做实验了，进入到build目录下面，运行`cmake ..`,会经历如下一些过程：

-- The C compiler identification is GNU 7.3.0
    -- The CXX compiler identification is GNU 7.3.0
    -- Check for working C compiler: /usr/bin/cc
    -- Check for working C compiler: /usr/bin/cc -- works
    -- Detecting C compiler ABI info
    -- Detecting C compiler ABI info - done
    -- Detecting C compile features
    -- Detecting C compile features - done
    -- Check for working CXX compiler: /usr/bin/c++
    -- Check for working CXX compiler: /usr/bin/c++ -- works
    -- Detecting CXX compiler ABI info
    -- Detecting CXX compiler ABI info - done
    -- Detecting CXX compile features
    -- Detecting CXX compile features - done
    -- Configuring done
    -- Generating done
    -- Build files have been written to: /home/xierhacker/workspace/LearningCMake/5.HelloWorld5/build

然后你会在build下面得到编译的中间文件，其中还有一个`temp`目录，然后运行`make`,能够看到生成的运行文件`HelloWorld`去到了工程目录下面的`bin`目录里面。  
这里要重点注意就是工程目录下面的`CMakeLists.txt`中的那句命令啦，我们详细的解释一下这个命令的作用。

`ADD_SUBDIRECTORY(source_dir [binary_dir] [EXCLUDE_FROM_ALL])`

这个指令用于向当前工程添加存放源文件的子目录，并可以指定中间二进制和目标二进制存放的位置。EXCLUDE\_FROM\_ALL 参数的含义是将这个目录从编译过程中排除，比如，工程的 example，可能就需要工程构建完成后，再进入 example 目录单独进行构建(当然，你也可以通过定义依赖来解决此类问题)。

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

不论是 `SUBDIRS` 还是 `ADD_SUBDIRECTORY`指令(不论是否指定编译输出目录)，我们都可以通过 SET 指令重新定义 **EXECUTABLE\_OUTPUT\_PATH** 和 **LIBRARY\_OUTPUT\_PATH 变量来指定最终的目标二进制的位置(指最终生成的 hello** 或者最终的共享库，不包含编译生成的中间文件)

常见的语句如下：

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

在第一节我们提到了\_BINARY\_DIR 和 PROJECT\_BINARY\_DIR 变量，他们指的编译发生的当前目录，如果是内部编译，就相当于`PROJECT_SOURCE_DIR` 也就是工程代码所在目录，如果是外部编译，指的是外部编译所在目录，也就是本例中的`build`目录。  
所以，上面两个指令分别定义了：可执行二进制的输出路径为 build/bin 和库的输出路径为 build/lib.本节我们没有提到共享库和静态库的构建，所以，你可以不考虑第二条指令。  
问题是，我应该把这两条指令写在工程的 CMakeLists.txt 还是 src 目录下的CMakeLists.txt，

> **把握一个简单的原则，在哪里 ADD\_EXECUTABLE 或 ADD\_LIBRARY，如果需要改变目标存放路径，就在哪里加入上述的定义**

在这个例子里，当然就是指 src 下的 CMakeLists.txt 了。

## 第二步:怎么安装 ##

这里需要引入一个新的 cmake 指令`INSTALL`和一个非常有用的变量  
`CMAKE_INSTALL_PREFIX`。`CMAKE_INSTALL_PREFIX` 变量类似于 configure 脚本的 –prefix，常见的使用方法看起来是这个样子：

> cmake -D 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` 定义的目标文件，可能是可执行二进制、动态库、静态库。

目标类型也就相对应的有三种:  
1. **ARCHIVE** 特指静态库  
2. **LIBRARY** 特指动态库  
3. **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 名称就可以了。

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

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

跟上面的 FILES 指令使用方法一样，唯一的不同是安装后权限为:  
OWNER\_EXECUTE, GROUP\_EXECUTE, 和 WORLD\_EXECUTE，即 755 权限

[LearningCMake_5.HelloWorld5]: https://github.com/XierHacker/LearningCMake/tree/master/5.HelloWorld5