Cmake Practice 总结 Project

2024-02-18 13:03:16

所有的构建我们都将采用out-of-source外部构建，约定的构建目录是工程目录下的build自录。

本小节的任务是让前面的Hello World更像一个工程，我们需要作的是：

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

准备工作：

在~/cmake_practice/目录下建立t2目录。
将t1工程的main.c和CMakeLists.txt拷贝到t2目录中。

Cmake编程

添加子目录src：

mkdir src
mv main.c src

现在的工程看起来是这个样子：
一个子目录src，一个CMakeLists.txt。

上一节我们提到，需要为任何子目录建立一个CMakeLists.txt，
进入子目录src，编写CMakeLists.txt如下：

add_executable(hello main.c)

将t2工程的CMakeLists.txt修改为：

project(HELLO)
add_subdirectory(src bin)

然后建立build目录，进入build目录进行外部编译。

cmake ..
make

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

语法解释：

add_subdirectory指令

add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL])

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

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

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

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

上面两个指令分别定义了：
可执行二进制的输出路径为build/bin和库的输出路径为build/lib.

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

安装

引入一个新的cmake指令 install 和一个非常有用的变量 CMAKE_INSTALL_PREFIX。
常见的使用方法:

cmake .. -DCMAKE_INSTALL_PREFIX=/usr

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目录

普通文件的安装:

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权限。

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

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

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

目录的安装：

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目录安装到 /share/myproj，将scripts/中的内容安装到/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.\")")

小节任务详解

添加doc目录及文件:
cd ~/cmake_practice/t2
mkdir doc
vi doc/hello.txt

在工程目录添加runhello.sh脚本

添加工程目录中的COPYRIGHT和README

下面改写各目录的CMakeLists.txt文件。

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

install(FILES COPYRIGHT README DESTINATION share/doc/cmake/t2)

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

install(PROGRAMS runhello.sh DESTINATION bin)

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

install(TARGETS hello
  RUNTIME DESTINATION bin)

安装doc中的hello.txt，直接修改主工程文件CMakeLists.txt，加入如下指令：

install(DIRECTORY doc/ DESTINATION share/doc/cmake/t2)

尝试我们修改的结果：

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

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

然后运行

make
make install

让我们进入/tmp/t2目录看一下安装结果：
./usr
./usr/share
./usr/share/doc
./usr/share/doc/cmake
./usr/share/doc/cmake/t2
./usr/share/doc/cmake/t2/hello.txt
./usr/share/doc/cmake/t2/README
./usr/share/doc/cmake/t2/COPYRIGHT
./usr/bin
./usr/bin/hello
./usr/bin/runhello.sh

如果你要直接安装到系统，可以使用如下指令：

cmake -DCMAKE_INSTALL_PREFIX=/usr ..

如果我没有定义CMAKE_INSTALL_PREFIX会安装到什么地方？
CMAKE_INSTALL_PREFIX的默认定义是/usr/local

码农公寓