cmake基础(3)——安装

一、简介

install命令用于指定安装时的规则，由于安装命令比较复杂，这里做一部分内容的介绍，后续用到再继续完善。

1.命令简介

本文档基于3.20，目前有6种安装方式。

install(TARGETS <target>... [...])
install({FILES | PROGRAMS} <file>... [...])
install(DIRECTORY <dir>... [...])
install(SCRIPT <file> [...])
install(CODE <code> [...])
install(EXPORT <export-name> [...])

首先是通用参数：

1.1 DESTINATION

指定安装的目标目录。参数后接路径，可以是相对路径也可以是绝对路径。

相对路径则是相对于CMAKE_INSTALL_PREFIX变量值。也可以在安装时通过DESTDIR修改。

make DESTDIR=/package/stage install

实际上，上述方式是在UNIX系统下，而更加常用的是使用--prefix选项

cmake --install binPath --prefix="destPath"

1.2 PERMISSIONS

指定被安装文件的权限。包括OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ, GROUP_WRITE, GROUP_EXECUTE, WORLD_READ, WORLD_WRITE, WORLD_EXECUTE, SETUID, 和 SETGID。对于平台中不支持的权限则忽略。

1.3 CONFIGURATIONS

指定一个构建配置的列表(Debug,Release等)，作用于之后的内容，不对之前的内容不生效。

对于这个参数，必须要提到的是，cmake的安装动作(配置)是由外部控制的:

cmake --install srcPath --config Debug|Release...

通过上述命令中的--config参数，来控制执行安装Debug内容还是Release内容。

而对于当前配置CONFIGURATIONS则是表示其后内容隶属的动作(在Debug，Release还是其他动作时执行)。比如下面的例子：

install(TARGETS ${PROJECT_NAME}  CONFIGURATIONS ReleaseARCHIVE DESTINATION ${PROJECT_SOURCE_DIR}/lib/ReleaseLIBRARY DESTINATION ${PROJECT_SOURCE_DIR}/lib/ReleaseCONFIGURATIONS DebugRUNTIME DESTINATION ${PROJECT_SOURCE_DIR}/bin/Debug)

则表示执行

cmake --install srcPath --config Debug

命令时，只安装RUNTIME内容，而不安装ARCHIVE和LIBRARY内容。相反的，如果执行

cmake --install srcPath --config Release

命令时，只安装ARCHIVE和LIBRARY内容，而不安装RUNTIME内容。

此外，默认的安装动作和安装配置都是Release的。

1.4 COMPONENT

指定安装的组件名。目前还不确定组件的创建方式，等待后续完善。

1.5 EXCLUDE_FROM_ALL

不安装的内容。

1.6 RENAME

1.7 OPTIONAL

表示此安装命令为可选项，找不到也不会报错。

二、Installing Targets

install(TARGETS targets... [EXPORT <export-name>][[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE][DESTINATION <dir>][PERMISSIONS permissions...][CONFIGURATIONS [Debug|Release|...]][COMPONENT <component>][NAMELINK_COMPONENT <component>][OPTIONAL] [EXCLUDE_FROM_ALL][NAMELINK_ONLY|NAMELINK_SKIP]] [...][INCLUDES DESTINATION [<dir> ...]])

1.支持的target

1.1 ARCHIVE

静态库(除了macOS)、dll导入库（也就是dll对应的lib文件）

1.2 LIBRARY

共享库(lib文件，不包括dll文件)

1.3 RUNTIME

可执行文件，dll文件。

1.4 OBJECTS

对象库的对象文件。参考add_library中的object library。

1.5 FRAMEWORK、BUNDLE、PUBLIC_HEADER、PRIVATE_HEADER、RESOURCE

这些都是与apple平台相关的内容，没有环境，不做解释。

其中PUBLIC_HEADER、PRIVATE_HEADER、RESOURCE官文解释非apple平台也有效，但是实际使用时没有反应。

---

HEADER使用方式：

set_target_properties(${PROJECT_NAME} PROPERTIES PUBLIC_HEADER src/hello.h)install(TARGETS ${PROJECT_NAME}  PUBLIC_HEADER DESTINATION ${PROJECT_SOURCE_DIR}/include)

2 其他参数

2.1 NAMELINK_COMPONENT、NAMELINK_ONLY、NAMELINK_SKIP

component相关。

2.2 EXPORT

将库名导出，与install(EXPORT)共同作用，将target导出。

2.3 INCLUDES DESTINATION

在执行install(EXPORT)命令进行导出时，将指定目录列表添加到target的属性INTERFACE_INCLUDE_DIRECTORIES中。

最后，对于install(targets)命令而言，一条install可以安装多个target，而一个target也有可能被install多次（都生效，而不是覆盖）。

三、Installing Files

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

1.FILES | PROGRAMS

两者都是安装文件，只不过FILES安装后的文件默认权限为OWNER_WRITE, OWNER_READ, GROUP_READ和WORLD_READ(如果设置了PERMISSIONS则按PERMISSIONS来)；而对PROGRAMS而言，还多了OWNER_EXECUTE, GROUP_EXECUTE和WORLD_EXECUTE三个权限。

安装的文件内容，可以是生成器表达式$<...>,但是以任何表达式开始的文件都要求是完整路径(实际上不是表达式也需要全路径)。

2.TYPE | DESTINATION

两者用于指定文件安装的目标目录，两者不能同事存在。如果使用TYPE的话则会指定文件的类型，并从GNUInstallDirs中获取相应的变量，而如果没有定义此变量则使用内置的默认值。下表则是文件类型对应的变量和默认路径。

TYPE Argument	GNUInstallDirs Variable	Built-In Default
BIN	${CMAKE_INSTALL_BINDIR}	bin
SBIN	${CMAKE_INSTALL_SBINDIR}	sbin
LIB	${CMAKE_INSTALL_LIBDIR}	lib
INCLUDE	${CMAKE_INSTALL_INCLUDEDIR}	include
SYSCONF	${CMAKE_INSTALL_SYSCONFDIR}	etc
SHAREDSTATE	${CMAKE_INSTALL_SHARESTATEDIR}	com
LOCALSTATE	${CMAKE_INSTALL_LOCALSTATEDIR}	var
RUNSTATE	${CMAKE_INSTALL_RUNSTATEDIR}	<LOCALSTATEdir>/run
DATA	${CMAKE_INSTALL_DATADIR}	<DATAROOTdir>
INFO	${CMAKE_INSTALL_INFODIR}	<DATAROOTdir>/info
LOCALE	${CMAKE_INSTALL_LOCALEDIR}	<DATAROOTdir>/locale
MAN	${CMAKE_INSTALL_MANDIR}	<DATAROOTdir>/man
DOC	${CMAKE_INSTALL_DOCDIR}	<DATAROOTdir>/doc

如果提供了DESTINATION参数，则使用DESTINATION参数提供的目录。

四、Installing Directories

install(DIRECTORY dirs...TYPE <type> | DESTINATION <dir>[FILE_PERMISSIONS permissions...][DIRECTORY_PERMISSIONS permissions...][USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER][CONFIGURATIONS [Debug|Release|...]][COMPONENT <component>] [EXCLUDE_FROM_ALL][FILES_MATCHING][[PATTERN <pattern> | REGEX <regex>][EXCLUDE] [PERMISSIONS permissions...]] [...])

用于安装一个或多个目录到目标目录，目录结构被完整的拷贝。每个目录的最后一项会被添加到目标目录，如果不想这样则可以以/结尾，表示最后一项为空。

#表示将build目录下的内容安装到test目录下
install(DIRECTORY  ${PROJECT_SOURCE_DIR}/build/ 
DESTINATION ${PROJECT_SOURCE_DIR}/test)#表示将build目录的内容安装到test目录下
install(DIRECTORY  ${PROJECT_SOURCE_DIR}/build 
DESTINATION ${PROJECT_SOURCE_DIR}/test)

如果输入目录为空，则创建目标目录，且内容为空。

1.权限

FILE_PERMISSIONS、DIRECTORY_PERMISSIONS 、USE_SOURCE_PERMISSIONS三者用于控制目标目录(DIRECTORY_PERMISSIONS)和文件(FILE_PERMISSIONS)的权限。如果使用了USE_SOURCE_PERMISSIONS，而FILE_PERMISSIONS没有指定，则文件权限与源文件权限一样。

如果没有指定FILE_PERMISSIONS权限，则文件的权限与FILES命令的权限一样（OWNER_WRITE, OWNER_READ, GROUP_READ和WORLD_READ），而目录权限与PROGRAMS一样（OWNER_WRITE, OWNER_READ, GROUP_READ，WORLD_READ，OWNER_EXECUTE, GROUP_EXECUTE和WORLD_EXECUTE）

2.过滤

目录的安装可以通过PATTERN和REGEX选项细粒度的控制，其中PATTERN匹配完整文件名，REGEX默认匹配文件名中的任何一部分(可以通过/或者$实现与PATTERN相同的效果)。

默认情况下，所有文件和目录都会被install(不论PATTERN和REGEX的匹配结果),但是我们可以通过设置FILES_MATCHING过滤没有匹配的文件。

#目录全部拷贝，安装以target开始的文件
install(DIRECTORY  ${PROJECT_SOURCE_DIR}/build/ DESTINATION ${PROJECT_SOURCE_DIR}/test
FILES_MATCHINGPATTERN "target*")#目录全部拷贝，只安装target文件
install(DIRECTORY  ${PROJECT_SOURCE_DIR}/build/ DESTINATION ${PROJECT_SOURCE_DIR}/test
FILES_MATCHINGPATTERN "target")#目录全部拷贝，安装文件名包含target的文件
install(DIRECTORY  ${PROJECT_SOURCE_DIR}/build/ DESTINATION ${PROJECT_SOURCE_DIR}/test
FILES_MATCHINGREGEX "target")#REGEX通过前缀$或后缀/达到与PATTERN相同的效果
install(DIRECTORY  ${PROJECT_SOURCE_DIR}/build/ DESTINATION ${PROJECT_SOURCE_DIR}/test
FILES_MATCHINGREGEX "target/")
install(DIRECTORY  ${PROJECT_SOURCE_DIR}/build/ DESTINATION ${PROJECT_SOURCE_DIR}/test
FILES_MATCHINGREGEX "$target")

五、Installing Exports

install(EXPORT <export-name> DESTINATION <dir>[NAMESPACE <namespace>] [[FILE <name>.cmake]|[PERMISSIONS permissions...][CONFIGURATIONS [Debug|Release|...]][EXPORT_LINK_INTERFACE_LIBRARIES][COMPONENT <component>][EXCLUDE_FROM_ALL])

生成并安装一个CMake文件，该文件包含了将targets从安装目录中导入到其他项目的代码。安装的内容是跟上面install(TARGETS)中EXPORT的选项一样。

NAMESPACE选项将在目标名被写入导入文件时在前面添加<namespace>。默认生成的文件为<export-name>.cmake，而FILE选项可以将其设置为其他名字，这个名字必须以.cmake结尾。

下面是一个简单的例子：

创建一个项目hello：

cmake_minimum_required(VERSION 3.20)
project(target01 VERSION 1.0.0)
file(GLOB SOURCES "src/*")set(CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS ON)
set(CMAKE_INSTALL_PREFIX ${PROJECT_SOURCE_DIR}/../helloPkg/)add_library(${PROJECT_NAME} SHARED ${SOURCES})set_target_properties(${PROJECT_NAME} PROPERTIES PUBLIC_HEADER src/hello.h)install(TARGETS ${PROJECT_NAME} EXPORT ${PROJECT_NAME}ARCHIVE DESTINATION ${PROJECT_SOURCE_DIR}/../helloPkg/lib/ReleaseRUNTIME DESTINATION ${PROJECT_SOURCE_DIR}/../helloPkg/bin/ReleasePUBLIC_HEADER DESTINATION ${PROJECT_SOURCE_DIR}/../helloPkg/include)# install(FILES ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}Config.cmakeinstall(EXPORT ${PROJECT_NAME} DESTINATION ${PROJECT_SOURCE_DIR}/../helloPkg/lib/cmake/${PROJECT_NAME}NAMESPACE TEST::)
configure_file(${PROJECT_SOURCE_DIR}/${PROJECT_NAME}.cmake.in ${PROJECT_BINARY_DIR}/${PROJECT_NAME}Config.cmake @ONLY)
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}Config.cmakeDESTINATION ${PROJECT_SOURCE_DIR}/../helloPkg/lib/cmake/${PROJECT_NAME})

同目录下创建src文件夹，并创建：

class __declspec(dllexport) Hello
{
public:void print();
};

#include "hello.h"
#include <iostream>void Hello::print() {std::cout << "hello world!" << std::endl;
}

CMakeLists.txt统计目录下创建target01.cmake.in：

@PACKAGE_INIT@include("${CMAKE_CURRENT_LIST_DIR}/@PROJECT_NAME@.cmake")

然后在hello同级目录下创建main项目

cmake_minimum_required(VERSION 3.20)
project(main)set(CMAKE_INSTALL_PREFIX  ${PROJECT_SOURCE_DIR}/../helloPkg/lib/cmake)
set(target01_DIR  ${PROJECT_SOURCE_DIR}/../helloPkg/lib/cmake/target01/)find_package(target01 REQUIRED PATHS ${PROJECT_SOURCE_DIR}/../helloPkg/)
add_executable(${PROJECT_NAME} src/main.cpp)target_include_directories(${PROJECT_NAME} PRIVATE ${PROJECT_SOURCE_DIR}/../helloPkg/include)
target_link_libraries(${PROJECT_NAME} PRIVATE TEST::target01)

创建src目录并创建main.cpp

#include "hello.h"int main()
{Hello h;h.print();return 0;
}

最后，在main项目同级目录下创建helloPkg文件夹。

这里虽然没搞懂中间的configure_file和*.cmake.in文件的作用，但是试出来了，先记一下。